Merge pull request #545 from slumbering/daggosaurus

docs: init Docusaurus

Makefile

@@ -49,3 +49,8 @@ integration: dagger-debug
 .PHONY: install
 install: dagger
 	go install ./cmd/dagger
+
+.PHONY: docs
+docs:
+	yarn --cwd "./tools/daggosaurus" install
+	yarn --cwd "./tools/daggosaurus" start

docs/README.md

@@ -1,3 +1,10 @@
+---
+sidebar_position: 1
+slug: /
+sidebar_label: Introduction
+hide_table_of_contents: true
+---
+
 # Dagger
 
 Dagger is a programmable deployment system.

docs/guides/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Guides",
+  "position": 4
+}

docs/guides/operator.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 2
+---
+
 # Dagger Operator Manual
 
 ## Custom buildkit setup

docs/guides/programming.md

@@ -1,9 +1,14 @@
+---
+sidebar_position: 1
+slug: /programming
+---
+
 # Dagger Programming Guide
 
 ## Overview
 
-1. A developer writes a *plan* specifying how to deliver their application. Plans are written in the [Cue](https://cuelang.org) data language.
-2. Dagger executes plans in isolated *environments*. Each environment has its own configuration and state.
+1. A developer writes a _plan_ specifying how to deliver their application. Plans are written in the [Cue](https://cuelang.org) data language.
+2. Dagger executes plans in isolated _environments_. Each environment has its own configuration and state.
 
 ## Programming in Cue
 
@@ -12,15 +17,15 @@ of GCL, the language used to configure all of Google's infrastructure.
 
 Cue extends JSON with powerful features:
 
-* Composition: layering, templating, references
-* Correctness: types, schemas
-* Developer experience: comments, packages, first-class tooling, builtin functions
-* And mucn more.
+- Composition: layering, templating, references
+- Correctness: types, schemas
+- Developer experience: comments, packages, first-class tooling, builtin functions
+- And mucn more.
 
 To get started with Cue, we recommend the following resources:
 
-* [Cuetorials](https://cuetorials.com)
-* [Cue playground](https://cuelang.org/play/)
+- [Cuetorials](https://cuetorials.com)
+- [Cue playground](https://cuelang.org/play/)
 
 ## Writing your first plan
 
@@ -34,7 +39,7 @@ To create a Dagger plan:
 
 For example: `dagger new staging`.
 
-3\. Create a new file with the *.cue* extension in `.dagger/env/staging/plan`, and open it with any text editor or IDE.
+3\. Create a new file with the _.cue_ extension in `.dagger/env/staging/plan`, and open it with any text editor or IDE.
 
 For example: `.dagger/env/staging/plan/staging.cue`.
 
@@ -64,14 +69,16 @@ ctr: docker.#Build & {
 
 For more inspiration, see these examples:
 
-* [Deploy a static page to S3](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-static-page-to-s3)
-* [Deploy a simple React application](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-simple-react-application)
-* [Deploy a complete JAMstack app](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-complete-jamstack-app)
-* [Provision a Kubernetes cluster on AWS](https://github.com/dagger/dagger/blob/main/examples/README.md#provision-a-kubernetes-cluster-on-aws)
-* [Add HTTP monitoring to your application](https://github.com/dagger/dagger/blob/main/examples/README.md#add-http-monitoring-to-your-application)
-* [Deploy an application to your Kubernetes cluster](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-an-application-to-your-kubernetes-cluster)
+- [Deploy a static page to S3](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-static-page-to-s3)
+- [Deploy a simple React application](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-simple-react-application)
+- [Deploy a complete JAMstack app](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-complete-jamstack-app)
+- [Provision a Kubernetes cluster on AWS](https://github.com/dagger/dagger/blob/main/examples/README.md#provision-a-kubernetes-cluster-on-aws)
+- [Add HTTP monitoring to your application](https://github.com/dagger/dagger/blob/main/examples/README.md#add-http-monitoring-to-your-application)
+- [Deploy an application to your Kubernetes cluster](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-an-application-to-your-kubernetes-cluster)
 
-5\. Extend your plan with relay definitions from [Dagger Universe](../stdlib), an encyclopedia of cue packages curated by the Dagger community.
+5\. Extend your plan with relay definitions from [Dagger
+Universe](https://github.com/dagger/dagger/tree/main/stdlib), an encyclopedia of
+cue packages curated by the Dagger community.
 
 6\. If you can't find the relay you need in the Universe, you can simply create your own.
 
@@ -108,26 +115,26 @@ american: #Greeting & {
 
 ### Plans
 
-A *plan* specifies, in code, how to deliver a particular application in a particular way.
+A _plan_ specifies, in code, how to deliver a particular application in a particular way.
 
 It lays out the application's supply chain as a graph of interconnected nodes:
 
-* Development tools: source control, CI, build systems, testing systems
-* Hosting infrastructure: compute, storage, networking, databases, CDN..
-* Software dependencies: operating systems, languages, libraries, frameworks, etc.
+- Development tools: source control, CI, build systems, testing systems
+- Hosting infrastructure: compute, storage, networking, databases, CDN..
+- Software dependencies: operating systems, languages, libraries, frameworks, etc.
 
 The graph models the flow of code and data through the supply chain:
 
-* 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;
-* etc.
+- 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;
+- etc.
 
 Dagger plans are written in [Cue](https://cuelang.org), a powerful declarative language by the creator of GQL, the language used to deploy all applications at Google.
 
 ### Environments
 
-An *environment* is a live implementation of a *plan*, with its own user inputs and state.
+An _environment_ is a live implementation of a _plan_, with its own user inputs and state.
 The same plan can be executed in multiple environments, for example to differentiate production from staging.
 
 An environment can be updated with `dagger up`. When updating an environment, Dagger determines which inputs have
@@ -138,21 +145,24 @@ the frontend, it will build, test and deploy the new frontend, without changing
 
 ### Relays
 
-*Relays* are the basic components of a *plan*. Each relay is a node in the graph defined by the plan,
+_Relays_ are the basic components of a _plan_. Each relay is a node in the graph defined by the plan,
 performing the task assigned to that node. For example one relay fetches source code; another runs a build;
 another uploads a container image; etc.
 
-Relays are standalone software components: they are defined in [Cue](https://cuelang.org), but can
-execute code in any language using the [Dagger pipeline API](FIXME).
+Relays are standalone software components: they are defined in [Cue](https://cuelang.org/), but can
+execute code in any language using the [Dagger pipeline
+API](https://github.com/dagger/dagger/blob/main/stdlib/dagger/op/op.cue).
 
 A relay is made of 3 parts:
 
-* Inputs: data received from the user, or upstream relays
-* A processing pipeline: code executed against each new input, using the [pipeline API](FIXME)
-* Outputs: data produced by the processing pipeline
+- Inputs: data received from the user, or upstream relays
+- A processing pipeline: code executed against each new input, using the
+  [pipeline
+  API](https://github.com/dagger/dagger/blob/main/stdlib/dagger/op/op.cue)
+- Outputs: data produced by the processing pipeline
 
 Relays run in parallel, with their inputs and outputs interconnected into a special kind of graph,
-called a *DAG*. When a relay receives a new input, it runs it through the processing pipeline,
+called a _DAG_. When a relay receives a new input, it runs it through the processing pipeline,
 and produces new outputs, which are propagated to downstream relays as inputs, and so on.
 
 ### Using third-party relays
@@ -202,8 +212,8 @@ Thanks to its native support of LLB, Dagger offers native compatibility with Doc
 
 This makes it very easy to extend an existing Docker-based workflow, including:
 
-* Reusing Dockerfiles and docker-compose files without modification
-* Wrapping other deployment tools in a Dagger relay by running them inside a container
-* Robust multi-arch and multi-OS support, including Arm and Windows.
-* Integration with existing Docker engines and registries
-* Integration with Docker for Mac and Docker for Windows on developer machines
+- Reusing Dockerfiles and docker-compose files without modification
+- Wrapping other deployment tools in a Dagger relay by running them inside a container
+- Robust multi-arch and multi-OS support, including Arm and Windows.
+- Integration with existing Docker engines and registries
+- Integration with Docker for Mac and Docker for Windows on developer machines

docs/install.md

@@ -1,3 +1,8 @@
+---
+sidebar_position: 2
+slug: /install
+---
+
 # Install Dagger
 
 ## Option 1: Use Homebrew (Mac OS only)

docs/sidebar/sidebar.yml

@@ -1,24 +0,0 @@
-# Sidebar navigation
-
-- label: Introduction
-  link: "/"
-
-- label: "Install Dagger"
-  link: "/install"
-
-- label: "Dagger vs. Other software"
-  link: "/vs"
-
-- label: Guides
-  items:
-    - label: "Programming Guide"
-      link: "/programming"
-    - label: "Operator Manual"
-      link: "/operator"
-
-- label: Community
-  items:
-    - label: "GitHub"
-      link: https://github.com/dagger/dagger
-    - label: "Discord"
-      link: https://discord.gg/Rmffpmc

docs/vs.md

@@ -1,3 +1,9 @@
+---
+sidebar_position: 3
+slug: /vs
+sidebar_label: Dagger vs. Other software
+---
+
 # Dagger vs. Other Software
 
 ## Dagger vs. PaaS (Heroku, Firebase, etc.)

netlify.toml

@@ -0,0 +1,6 @@
+[build]
+  base = "tools/daggosaurus/"
+  publish = "build/"
+  command = "yarn build"
+  # build only if there are changes within daggosaurus or docs directories.
+  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../../docs/"

tools/daggosaurus/.gitignore

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

tools/daggosaurus/README.md

@@ -0,0 +1,33 @@
+# 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.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

tools/daggosaurus/babel.config.js

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

tools/daggosaurus/custom_plugins/index.js

@@ -0,0 +1,12 @@
+module.exports = function (context, options) {
+    return {
+        name: "custom-docusaurus-plugin",
+        configureWebpack(config, isServer, utils) {
+            return {
+                resolve: {
+                    symlinks: false
+                }
+            };
+        }
+    };
+};

tools/daggosaurus/docs

@@ -0,0 +1 @@
+../../docs

tools/daggosaurus/docusaurus.config.js

@@ -0,0 +1,49 @@
+const path = require('path');
+
+/** @type {import('@docusaurus/types').DocusaurusConfig} */
+module.exports = {
+  title: 'Dagger',
+  tagline: 'Dagger is a programmable deployment system',
+  url: 'https://docs.dagger.io',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/favicon.png',
+  organizationName: 'Dagger',
+  projectName: 'Dagger',
+  stylesheets: [
+    'https://fonts.gstatic.com',
+    'https://fonts.googleapis.com/css2?family=Poppins:wght@700&display=swap',
+    'https://fonts.googleapis.com/css2?family=Karla&family=Poppins:wght@700&display=swap'
+  ],
+  themeConfig: {
+    sidebarCollapsible: false,
+    prism: {
+      defaultLanguage: 'go',
+    },
+    navbar: {
+      logo: {
+        alt: 'My Site Logo',
+        src: 'img/dagger-logo.png',
+        srcDark: 'img/dagger_logo_dark.png',
+      },
+    },
+  },
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          editUrl:
+            'https://github.com/dagger/dagger/blob/main',
+          routeBasePath: '/',
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+  plugins: [path.resolve(__dirname, './custom_plugins')],
+};

tools/daggosaurus/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "daggosaurus",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids"
+  },
+  "dependencies": {
+    "@docusaurus/core": "2.0.0-beta.0",
+    "@docusaurus/preset-classic": "2.0.0-beta.0",
+    "@mdx-js/react": "^1.6.21",
+    "@svgr/webpack": "^5.5.0",
+    "clsx": "^1.1.1",
+    "file-loader": "^6.2.0",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1",
+    "url-loader": "^4.1.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

tools/daggosaurus/sidebars.js

@@ -0,0 +1,45 @@
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+
+module.exports = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  tutorialSidebar: [
+    { type: 'autogenerated', dirName: '.' },
+    {
+      type: 'category',
+      label: 'Community',
+      collapsed: false,
+      items: [
+        {
+          type: 'link',
+          label: 'Github',
+          href: 'https://github.com/dagger/dagger'
+        },
+        {
+          type: 'link',
+          label: 'Discord',
+          href: 'https://discord.gg/Rmffpmc'
+        },
+      ],
+    },
+  ],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['hello'],
+    },
+  ],
+   */
+};

tools/daggosaurus/src/css/custom.css

@@ -0,0 +1,103 @@
+/* stylelint-disable docusaurus/copyright-header */
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #0e2b3d;
+  --ifm-color-primary-dark: #131226;
+  --ifm-color-primary-darker: rgb(31, 165, 136);
+  --ifm-color-primary-darkest: rgb(26, 136, 112);
+  --ifm-color-primary-light: #fffef3;
+  --ifm-color-primary-lighter: rgb(102, 212, 189);
+  --ifm-color-primary-lightest: rgb(146, 224, 208);
+  --ifm-code-font-size: 95%;
+  --ifm-navbar-height: 5rem;
+  --ifm-background-color: var(--ifm-color-primary-light);
+  --ifm-navbar-background-color: transparent;
+  --ifm-menu-color-active: var(--ifm-color-primary-dark);
+  --ifm-font-family-base: "Karla", sans-serif;
+  /* --ifm-font-family-monospace: "Karla", sans-serif; */
+  --ifm-h2-font-size: 2rem;
+  --ifm-menu-color-background-active: var(--ifm-color-primary);
+  --ifm-menu-color-active: var(--ifm-color-primary-light);
+  --ifm-leading-desktop: 2;
+}
+
+html[data-theme="dark"] {
+  --ifm-background-color: var(--ifm-color-primary-dark);
+  --ifm-navbar-background-color: transparent;
+  --ifm-menu-color-active: var(--ifm-color-primary-light);
+  --ifm-menu-color-active: var(--ifm-color-primary-light);
+  --ifm-link-color: var(--ifm-color-primary-light);
+}
+
+#__docusaurus {
+  background-color: var(--ifm-color-primary-light);
+}
+
+html[data-theme="dark"] #__docusaurus {
+  background: linear-gradient(
+    180deg,
+    var(--ifm-color-primary-dark),
+    var(--ifm-color-primary)
+  );
+}
+
+.docusaurus-highlight-code-line {
+  background-color: rgb(72, 77, 91);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+.navbar__brand {
+  height: var(--ifm-navbar-height);
+}
+
+.navbar {
+  max-width: var(--ifm-container-width-xl);
+  align-self: center;
+  box-shadow: none;
+}
+
+.main-wrapper {
+  max-width: var(--ifm-container-width-xl);
+  align-self: center;
+}
+
+h1,
+h2,
+h3 {
+  font-family: "Poppins", sans-serif;
+}
+
+h2 {
+  font-weight: 700;
+  line-height: 32px;
+}
+
+.markdown > h2 {
+  --ifm-h2-font-size: 1.5rem;
+}
+
+p {
+  font-size: 18px;
+  font-weight: 400;
+  line-height: 24px;
+}
+
+.table-of-contents {
+  font-size: 1rem;
+}
+
+.table-of-contents__link--active {
+  font-weight: bold;
+}
+html[data-theme="dark"] .table-of-contents__link--active,
+html[data-theme="dark"] .table-of-contents__link:hover {
+  color: var(--ifm-color-primary-light);
+}