diff --git a/docs/learn/102-dev.md b/docs/learn/102-dev.md index 42fc10f3..91edcea5 100644 --- a/docs/learn/102-dev.md +++ b/docs/learn/102-dev.md @@ -19,13 +19,13 @@ configuration. An environment is made of 3 parts: -* A *plan*, authored by the environment's *developer*, using the [Cue](https://cuelang.org) language. +- A _plan_, authored by the environment's _developer_, using the [Cue](https://cuelang.org) language. -* *Inputs*, supplied by the environment's *user* via the `dagger input` command, and written to a special file. Inputs may be configuration values, artifacts, or encrypted secrets. +- _Inputs_, supplied by the environment's _user_ via the `dagger input` command, and written to a special file. Inputs may be configuration values, artifacts, or encrypted secrets. -* *Outputs*, computed by the Dagger engine via the `dagger up` command, and recorded to a special directory. +- _Outputs_, computed by the Dagger engine via the `dagger up` command, and recorded to a special directory. -We will first develop our environment's *plan*, then configure its initial inputs, then finally run it to verify that it works. +We will first develop our environment's _plan_, then configure its initial inputs, then finally run it to verify that it works. ### Anatomy of a plan @@ -38,15 +38,15 @@ of interconnected nodes. Each node in the graph represents a component of the supply chain, for example: -* Development tools: source control, CI, build systems, testing systems -* Hosting infrastructure: compute, storage, networking, databases, CDNs -* Software dependencies: operating systems, languages, libraries, frameworks, etc. +- Development tools: source control, CI, build systems, testing systems +- Hosting infrastructure: compute, storage, networking, databases, CDNs +- Software dependencies: operating systems, languages, libraries, frameworks, etc. Each link in the graph represents a flow of data between nodes. For example: -* source code flows from a git repository to a build system -* system dependencies are combined in a docker image, then uploaded to a registry -* configuration files are generated then sent to a compute cluster or load balancer +- source code flows from a git repository to a build system +- system dependencies are combined in a docker image, then uploaded to a registry +- configuration files are generated then sent to a compute cluster or load balancer ### Introduction to Cue development @@ -69,9 +69,9 @@ Although not strictly necessary, for an optimal development experience we recomm If you are new to Cue, we recommend keeping the following resources in browser tabs: -* The unofficial but excellent [Cuetorials](https://cuetorials.com/overview/foundations/) in a browser tab, to look up Cue concepts as they appear. +- The unofficial but excellent [Cuetorials](https://cuetorials.com/overview/foundations/) in a browser tab, to look up Cue concepts as they appear. -* The official [Cue interactive sandbox](https://cuelang.org/play) for easy experimentation. +- The official [Cue interactive sandbox](https://cuelang.org/play) for easy experimentation. ### Setup example app @@ -127,8 +127,8 @@ The first component of our plan is the source code of our React application. In Dagger terms, this component has 2 important properties: -1. It is an *artifact*: something that can be represented as a directory. -2. It is an *input*: something that is provided by the end user. +1. It is an _artifact_: something that can be represented as a directory. +2. It is an _input_: something that is provided by the end user. Let's write the corresponding Cue code to a new file in our package: @@ -164,15 +164,15 @@ app: yarn.#Package & { Let's break it down: -* `package multibucket`: this file is part of the multibucket package -* `import ( "dagger.io/js/yarn" )`: import a package from the [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). -* `app: yarn.#Package`: apply the `#Package` definition at the key `app` -* `&`: also merge the following values at the same key... -* `{ source: src }`: set the key `app.source` to the value of `src`. This connects our 2 components, forming the first link in our DAG. +- `package multibucket`: this file is part of the multibucket package +- `import ( "dagger.io/js/yarn" )`: import a package from the [Dagger Universe](/reference/universe/README). +- `app: yarn.#Package`: apply the `#Package` definition at the key `app` +- `&`: also merge the following values at the same key... +- `{ source: src }`: set the key `app.source` to the value of `src`. This connects our 2 components, forming the first link in our DAG. ### Component 3: dedicated S3 bucket -*FIXME*: this section is not yet available, because the [Amazon S3 package](https://github.com/dagger/dagger/tree/main/stdlib/aws/s3) does [not yet support bucket creation](https://github.com/dagger/dagger/issues/623). We welcome external contributions :) +_FIXME_: this section is not yet available, because the [Amazon S3 package](https://github.com/dagger/dagger/tree/main/stdlib/aws/s3) does [not yet support bucket creation](https://github.com/dagger/dagger/issues/623). We welcome external contributions :) ### Component 4: deploy to Netlify @@ -193,23 +193,23 @@ site: "netlify": netlify.#Site & { This is very similar to the previous component: -* We use the same package name as the other files -* We import another package from the [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). -* `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict. -* `&`: also merge the following values at the same key... -* `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This connects our components 2 and 3, forming the second link in our DAG. +- We use the same package name as the other files +- We import another package from the [Dagger Universe](/reference/universe/README). +- `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict. +- `&`: also merge the following values at the same key... +- `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This connects our components 2 and 3, forming the second link in our DAG. ### Exploring a package documentation But wait: how did we know what fields were available in `yarn.#Package` and `netlify.#Site`? -Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). +Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](/reference/universe/README). ```shell dagger doc dagger.io/netlify dagger doc dagger.io/js/yarn ``` -You can also browse the [Dagger Universe](/reference/universe) reference in the documentation. +You can also browse the [Dagger Universe](/reference/universe/README) reference in the documentation. ## Setup the environment