docs: Add docs website

README.md

@@ -27,9 +27,11 @@ We appreciate any participation in the project, including:
 
 ## Documentation
 
-- [Introduction](docs/introduction.md)
-- [Getting Started](docs/getting_started.md)
-- [Writing Extensions](docs/writing_extensions.md)
-  - [Writing an extension in Go](docs/writing_extensions_go.md)
-  - [Writing an extension in Javascript/Typescript](docs/writing_extensions_nodejs.md)
-- [Operator Manual](docs/operator_manual.md)
+Docs have a website (TODO: host and provide URL. Website private for those with access to [the dagger/cloak repo](https://github.com/dagger/cloak)) that you can run locally using [these instructions](docs/_README.md). The links in the docs assume you are viewing via the website.
+
+- [Introduction](docs/unxpq-introduction.mdx)
+- [Getting Started](docs/guides/2ku9n-getting_started.md)
+- [Writing Extensions](docs/guides/bnzm7-writing_extensions.md)
+  - [Writing an extension in Go](docs/guides/y0yh0-writing_extensions_go.md)
+  - [Writing an extension in Javascript/Typescript](docs/guides/oy1q7-writing_extensions_nodejs.md)
+- [Operator Manual](docs/guides/d7yxc-operator_manual.md)

docs/_README.md

@@ -0,0 +1,45 @@
+## How can I run docs locally?
+
+You will need to have `yarn` and Node.js v18 installed.
+
+From the `website` directory run the following command: `yarn start`
+
+This will install all dependencies, start the docs web server locally and open [localhost:3000](http://localhost:3000/) in your browser.
+
+## How should I do markdown hyperlinks?
+
+Since all docs have a unique id in Docusaurus no matter where they live on the filesystem (see adding a new doc below), we refer to other docs in links by their id and name like this:
+
+```markdown
+[Learn more about writing extensions](/bnzm7/writing_extensions)
+
+```
+
+This will make a link to a file called `bnzm7-writing_extensions` (that was created with `new.sh` at some point). In this case, the file lives in `docs/guides` but that doesn't matter. We can move it wherever and Docusaurus will find it. Take note of the leading `/` and how the `-` is changed to a path separator `/` as well.
+
+## How can I add a new doc page?
+
+```bash
+.
+├── docs/
+│   └── new.sh        1. $ ./new.sh my-doc-title (generates random id)
+│   └── guides/       2. $ mv r4nd0-my-doc-title guides/. (move & edit doc)
+└── website/          3. $ yarn install && yarn start
+    └── sidebars.js   4. (edit sidebars.js to slot your new guide into place)
+                      5. $ yarn start (check things out for real!)
+```
+
+NOTE: you'll see some `.mdx` files around. They are markdown files that support JavaScript components. Most docs won't need these.
+
+NOTE: docs support [Mermaid diagrams](https://mermaid-js.github.io/mermaid/#/)!
+
+1. From the `docs` dir, run `./new.sh my-doc-title`
+   This will create a new Markdown file for the new doc page with a random ID, e.g `docs/r4nd0-my-doc-title.md`
+
+2. Move your shiny new doc into the `guides` directory.
+
+3. Run `yarn install && yarn start` from the `/website` directory. This will download dependencies and also verifies no links are broken when parsing markdown, among other things, so it's a good way to "test" your new doc. Use `ctrl-c` to break out.
+
+4. Edit the sidebars.js file in the `website` directory to slot your new guide into place. We'll undoubtedly move things around over time.
+
+5. Run `yarn start` from the `/website` directory again to see your doc in the sidebar and working like a champ!

docs/getting_started.md → docs/guides/2ku9n-getting_started.md

@@ -1,3 +1,8 @@
+---
+slug: /2ku9n/getting_started
+displayed_sidebar: '0.3'
+---
+
 # Getting started with Cloak
 
 ## Install

docs/writing_extensions.md → docs/guides/bnzm7-writing_extensions.md

@@ -1,3 +1,8 @@
+---
+slug: /bnzm7/writing_extensions
+displayed_sidebar: '0.3'
+---
+
 # Writing an API extension
 
 ## Overview
@@ -6,8 +11,8 @@ This document explains how to write an API extension for Dagger/cloak.
 
 ## SDK-specific guides
 
-- [Writing an extension in Go](writing_extensions_go.md)
-- [Writing an extension in Javascript/Typescript](writing_extensions_nodejs.md)
+- [Writing an extension in Go](/y0yh0/writing_extensions_go)
+- [Writing an extension in Javascript/Typescript](/oy1q7/writing_extensions_nodejs)
 
 ## Concepts
 
@@ -23,7 +28,7 @@ are provided to a resolver and how outputs are provided back to the Cloak server
 
 It is up to each runtime implementation to determine how the inputs are converted to outputs.
 
-[Extension Runtime Protocol reference](extension_runtime_protocol.md)
+[Extension Runtime Protocol reference](/f5cij/extension_runtime_protocol)
 
 ## Dependency
 
@@ -48,7 +53,7 @@ being requested; we call this "invoking a resolver". When an extension is loaded
 that takes args must be associated with a resolver.
 
 Resolvers are provided to Cloak in the form of a Filesystem+ImageConfig pair. The entrypoint of the image config is expected
-to be an executable that implements the [Runtime Protocol](extension_runtime_protocol.md)
+to be an executable that implements the [Runtime Protocol](/f5cij/extension_runtime_protocol)
 
 Resolvers have access to the Cloak API during execution, which enables them to invoke other resolvers as needed.
 

docs/operator_manual.md → docs/guides/d7yxc-operator_manual.md

@@ -1,3 +1,8 @@
+---
+slug: /d7yxc/operator_manual
+displayed_sidebar: '0.3'
+---
+
 # Cloak operator manual
 
 ## Overview

docs/extension_runtime_protocol.md → docs/guides/f5cij-extension_runtime_protocol.md

@@ -1,3 +1,8 @@
+---
+slug: /f5cij/extension_runtime_protocol
+displayed_sidebar: '0.3'
+---
+
 # Extension Runtime Protocol
 
 An Extension Runtime is the bridge between the Dagger GraphQL server and executable programs implementing an extension. On a high-level, it is responsible for:

docs/writing_extensions_nodejs.md → docs/guides/oy1q7-writing_extensions_nodejs.md

@@ -1,3 +1,8 @@
+---
+slug: /oy1q7/writing_extensions_nodejs
+displayed_sidebar: '0.3'
+---
+
 # Writing a new project with NodeJS (Javascript or Typescript)
 
 Say we are creating a new project called `foo`. It will have
@@ -125,8 +130,8 @@ dependencies:
     ```
 
   - Also see other examples:
-    - [yarn](../examples/yarn/schema.graphql)
-    - [netlify](../examples/netlify/ts/schema.graphql)
+    - [yarn](https://github.com/dagger/cloak/blob/main/examples/yarn/schema.graphql)
+    - [netlify](https://github.com/dagger/cloak/blob/main/examples/netlify/ts/schema.graphql)
   - NOTE: this step may become optional in the future if code-first schemas are supported
 
 - Create a new file `ext/operations.graphql`. This file will determine which functions are included in code-generated client stubs (for scripts or other projects that depend on this extension).
@@ -143,8 +148,8 @@ dependencies:
     ```
 
   - Also see other examples:
-    - [yarn](../examples/yarn/operations.graphql)
-    - [netlify](../examples/netlify/ts/operations.graphql)
+    - [yarn](https://github.com/dagger/cloak/blob/main/examples/yarn/operations.graphql)
+    - [netlify](https://github.com/dagger/cloak/blob/main/examples/netlify/ts/operations.graphql)
   - NOTE: In most cases, this file is easy to derive from `schema.graphql`; we thus expect to be able to autogenerate it for many cases and make its creation optional in the long term.
 
 ### Implement the extension
@@ -171,8 +176,8 @@ server.run();
 
 1. Also feel free to import any other third-party dependencies as needed the same way you would with any other go project. They should all be installed and available when executing in the cloak engine.
 1. Some more examples:
-   - [yarn](../examples/yarn/index.ts)
-   - [netlify](../examples/netlify/ts/index.ts)
+   - [yarn](https://github.com/dagger/cloak/blob/main/examples/yarn/index.ts)
+   - [netlify](https://github.com/dagger/cloak/blob/main/examples/netlify/ts/index.ts)
 
 ### Invoke your extension
 

docs/writing_extensions_go.md → docs/guides/y0yh0-writing_extensions_go.md

@@ -1,3 +1,8 @@
+---
+slug: /y0yh0/writing_extensions_go
+displayed_sidebar: '0.3'
+---
+
 # Writing a new project with Go
 
 Say we are creating a new project called `foo`. It will have
@@ -120,8 +125,8 @@ dependencies:
     ```
 
   - Also see other examples:
-    - [alpine](../examples/alpine/schema.graphql)
-    - [netlify](../examples/netlify/go/schema.graphql)
+    - [alpine](https://github.com/dagger/cloak/blob/main/examples/alpine/schema.graphql)
+    - [netlify](https://github.com/dagger/cloak/blob/main/examples/netlify/go/schema.graphql)
   - NOTE: this step may become optional in the future if code-first schemas are supported
 
 - Create a new file `ext/operations.graphql`. This file will determine which functions are included in code-generated client stubs (for scripts or other projects that depend on this extension).
@@ -138,8 +143,8 @@ dependencies:
     ```
 
   - Also see other examples:
-    - [alpine](../examples/alpine/operations.graphql)
-    - [netlify](../examples/netlify/go/operations.graphql)
+    - [alpine](https://github.com/dagger/cloak/blob/main/examples/alpine/operations.graphql)
+    - [netlify](https://github.com/dagger/cloak/blob/main/examples/netlify/go/operations.graphql)
   - NOTE: In most cases, this file is easy to derive from `schema.graphql`; we thus expect to be able to autogenerate it for many cases and make its creation optional in the long term.
 
 ### Generate initial extension code
@@ -165,8 +170,8 @@ dependencies:
 1. When you need to call a dependency declared in `cloak.yaml`, you can import the client from `<your module>/ext/gen/<dependency>`
 1. Also feel free to import any other third-party dependencies as needed the same way you would with any other go project. They should all be installed and available when executing in the cloak engine.
 1. Some examples:
-   - [alpine](../examples/alpine/main.go)
-   - [netlify](../examples/netlify/go/main.go)
+   - [alpine](https://github.com/dagger/cloak/blob/main/examples/alpine/main.go)
+   - [netlify](https://github.com/dagger/cloak/blob/main/examples/netlify/go/main.go)
 
 ### Invoke your extension
 

docs/new.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+## Create a new documentation article
+
+function new() {
+	local name
+	name="$1"
+	if [ -z "$name" ]; then
+		echo >&2 "Usage: $0 NAME"
+		return 1
+	fi
+	local next
+	next=$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c5)
+
+	local filename="$next-$name.md"
+	echo "Creating $filename"
+	cat <<- EOF > "$filename"
+		---
+		slug: /$next/$name
+		displayed_sidebar: '0.3'
+		---
+EOF
+}
+
+new "$@"

docs/introduction.md → docs/unxpq-introduction.mdx

@@ -1,3 +1,8 @@
+---
+slug: /
+displayed_sidebar: '0.3'
+---
+
 # Introduction to Dagger/Cloak
 
 ## What is Dagger?
@@ -177,7 +182,7 @@ Writing an extension is more advanced than writing a workflow, because in additi
 
 * Unlike workflows, extensions are fully sandboxed and cannot access the host system.
 
-[Learn more about writing extensions](writing_extensions.md)
+[Learn more about writing extensions](/bnzm7/writing_extensions)
 
 ## Project File examples
 

website/.gitignore

@@ -0,0 +1,21 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": false,
+  "jsxBracketSameLine": true,
+  "printWidth": 80,
+  "proseWrap": "never",
+  "singleQuote": false,
+  "trailingComma": "all"
+}

website/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};