Write docs on targets

Author: mkaput

website/pages/docs/reference/targets.mdx

@@ -1 +1,64 @@
+import { Callout } from "nextra-theme-docs";
+
 # Targets
+
+Scarb packages consist of _targets_ which correspond to source files which can be compiled into a package, and the way how this package is compiled.
+Packages can have a built-in library target, and/or more externally defined targets.
+The list of targets can be configured in `Scarb.toml`.
+By default, if the manifest does not list any targets, Scarb will assume the library target with its default parameters.
+
+## Library
+
+The library target defines a "library" that can be used by other packages.
+In other words, if a package does not provide a library target, it cannot be used as a dependency.
+If not specified, the name of the library defaults to the name of the package.
+A package can have only one library target.
+
+### Sierra and CASM code generation
+
+The library target accepts following configuration parameters, with default values for the default _release_ profile:
+
+```toml
+[lib]
+sierra = true  # Enable Sierra codegen.
+casm = false   # Enable CASM codegen.
+```
+
+By default, the library target builds unprocessed Sierra code in textual form for the package.
+When the `casm` option is enabled, Scarb can also automatically compile this Sierra code down to CASM.
+
+## External targets
+
+Scarb supports registering targets that are handled by Scarb extensions.
+Such targets are called _external_ and are defined in a `[[target.*]]{:toml}` array of tables.
+
+<Callout type="info">
+  This is not fully implemented, and we track this work in [#111](https://github.com/software-mansion/scarb/issues/111).
+  As for now, Scarb only supports internally hardcoded targets:
+
+  - [`starknet-contract`](../starknet/contract-target)
+</Callout>
+
+If multiple targets of the same kind are defined in the package, they all must specify unique [names](#name).
+
+## Configuring a target
+
+All of the `[lib]{:toml}` and `[[target.*]]{:toml}` sections in `Scarb.toml` support configuration options that are not target-specific and control how Scarb manages these targets.
+The following is an overview of the TOML settings for each target, with each field described in detail below.
+
+```toml
+[lib]
+name = "foo"  # The name of the target.
+```
+
+<Callout type="warning">
+  Scarb reserves itself a right to introduce new global configuration fields in future versions.
+  Potentially, new parameters may end up being conflicting with ones accepted by external targets.
+  Introducing new parameters will always be done in major Scarb version bump, and will be loudly communicated earlier.
+</Callout>
+
+### `name`
+
+The `name` field specifies the name of the target, which corresponds to the filename of the artifact that will be generated.
+If missing, this defaults to the name of the package.
+If multiple targets of the same kind are defined in the package, they all must specify unique names.

website/pages/docs/starknet/contract-target.mdx

@@ -10,4 +10,4 @@ To enable it for a package, write a following line in `Scarb.toml`:
 [[target.starknet-contract]]
 ```
 
-This target does not accept any configuration arguments beside ones [shared among all targets](../reference/targets).
+This target does not accept any configuration arguments beside ones [shared among all targets](../reference/targets#configuring-a-target).