Docs engine content updates

products/docs-engine/src/content/contributors-guide.md → products/docs-engine/src/content/contributing/content-framework.md

@@ -1,8 +1,8 @@
 ---
-order: 3
+order: 1
 ---
 
-# Contributor’s guide
+# Content framework
 
 This page provides an overview of how best to contribute to Cloudflare’s documentation. This is a living document and will be updated as recommendations change.
 

products/docs-engine/src/content/contributing/development-setup.md

@@ -0,0 +1,66 @@
+---
+order: 0
+---
+
+# Development setup
+
+<Aside>
+
+__Note for Cloudflare employees__
+
+Follow the [Migrate a Product](/how-to-guides/migrate-a-product) how-to guide instead.
+
+The content below is here for completeness, and describes the theoretical way to set up the Docs Engine with _any_ project. At Cloudflare we’ve decided to follow the monorepo approach for our docs content, putting all of our docs content inside [@cloudflare/cloudflare-docs](http://github.com/cloudflare/cloudflare-docs) rather than a per-product repo. As such, the how-to guide listed above includes the specific instructions for setting up a development environment with our monorepo.
+
+</Aside>
+
+The basic steps for setting up a development are as follows.
+
+1. Clone [@cloudflare/cloudflare-docs-engine](http://github.com/cloudflare/cloudflare-docs-engine) and your repo (`@example-username/my-docs-content` below):
+
+  ```sh
+  ~/ $ git clone git@github.com:cloudflare/cloudflare-docs-engine.git
+  ~/ $ git clone git@github.com:example-username/my-docs-content.git
+  ```
+
+2. `cd` into `cloudflare-docs-engine`, run `npm link`, then return to the parent directory.
+
+  ```sh
+  ~/ $ cd cloudflare-docs-engine
+  ~/cloudflare-docs-engine $ npm link
+  ~/cloudflare-docs-engine $ cd ..
+  ```
+
+3. `cd` into `my-docs-content`:
+
+  ```sh
+  ~/ $ cd my-docs-content
+  ```
+
+5. Inside your project’s folder, link the engine:
+
+  ```sh
+  ~/my-docs-content $ npm link cloudfare-docs-engine
+  ```
+
+6. Run the engine’s [`bootstrap` command](https://github.com/cloudflare/cloudflare-docs-engine/blob/765bc30127b0e80b570aade7044036925928c3ea/bin/commands.sh#L19-L39):
+
+  ```sh
+  ~/my-docs-content $ npm run bootstrap
+  ```
+
+7. Run the local development server:
+
+  ```sh
+  ~/my-docs-content $ npm run develop
+  ```
+
+8. Open up `localhost:8000` in your browser to see your docs site.
+
+At this point, you can make changes to the Markdown files inside the contect directory (e.g. `my-docs-content/src/content`) to improve your docs site.
+
+<Aside>
+
+__Note:__ Unfortunately, for now you’ll need to stop and restart `npm run develop` every time you make changes. This is something we’re urgently looking to fix and can be tracked [in this Github issue](https://github.com/cloudflare/cloudflare-docs-engine/issues/279), which also includes a workaround which may help in the interim.
+
+</Aside>

products/docs-engine/src/content/contributing/index.md

@@ -0,0 +1,8 @@
+---
+type: overview
+order: 3
+---
+
+# Contributing
+
+<DirectoryListing path="/contributing"/>

products/docs-engine/src/content/contributing/to-docs-engine.md

@@ -0,0 +1,22 @@
+---
+title: To Docs Engine
+order: 2
+---
+
+# Contribute to the Docs Engine
+
+## Background
+
+The Cloudflare Docs Engine is based on [Gatsby](https://www.gatsbyjs.com), and enables developers to quickly build out docs sites by allowing them to focus on the Markdown content.
+
+Authors can leverage the power of MDX by building custom compontents or utilize the powerful [built-in components](/reference/markdown).
+
+## Contributing
+
+To contribute, just make a pull request on [@cloudflare/cloudflare-docs-engine](https://github.com/cloudflare/cloudflare-docs-engine).
+
+There are a number of [open issues](https://github.com/cloudflare/cloudflare-docs-engine/issues) we would love the community’s help with solving.
+
+## More to come
+
+There are a number of meaty issues we’re really excited to tackle with the community. Stay tuned for more information about those here.

products/docs-engine/src/content/markdown/code-block-examples.md → products/docs-engine/src/content/examples/code-block-examples.md

@@ -2,7 +2,7 @@
 
 Code blocks inside [Docs Engine Markdown](/reference/markdown) offer a variety of custom presentation mechanisms. This page contains practical examples for inspiration.
 
-Learn more about [using code blocks inside Markdown](/reference/markdown#codeblocks).
+Learn more about [using code blocks inside Markdown](/reference/markdown#code-blocks).
 
 --------------------------------
 

products/docs-engine/src/content/examples/index.md

@@ -0,0 +1,8 @@
+---
+type: overview
+order: 5
+---
+
+# Examples
+
+<DirectoryListing path="/examples"/>

products/docs-engine/src/content/examples/pages/index.md

@@ -0,0 +1,9 @@
+---
+order: 3
+---
+
+# Example pages
+
+Use these as a starting point for writing consistent docs.
+
+<DirectoryListing path="/examples/example-pages"/>

products/docs-engine/src/content/faq.md

@@ -0,0 +1,37 @@
+---
+type: overview
+order: 6
+---
+
+# FAQ
+
+<ContentColumn>
+
+<details open><summary>Why a Docs Engine?</summary><div>
+
+__tl:dr;__ You write good [Markdown (MDX)](/markdown), and the rest is taken care of.
+
+__Details:__ Cloudflare has a large number of teams shipping product updates often. Most of these products have [their own documentation](https://developers.cloudflare.com/docs/). Over time we’ve found that it’s especially difficult to balance two important goals:
+
+1. Content is easily managed by the product team that owns it.
+2. Docs are consistent across products, providing the _best experience for our customers_, who commonly use more than one Cloudflare product together.
+
+The Docs Engine strives to solve these problems by providing smart defaults with minimal [configuration](/site-configuration) and a wide variety of [composable MDX components](/markdown).
+
+</div></details>
+
+<details><summary>How does the main navigation work?</summary><div>
+
+The sidebar tree is automatically generated from the file structure inside the content directory (`src/content` by default, configurable with [`contentRepoFolder`](/reference/configuration#properties)).
+
+The link text is automatically determined by [the `title` of the page](/reference/pages#title), which by default comes from the first `h1` inside the document.
+
+</div></details>
+
+<details><summary>How does the table of contents work?</summary><div>
+
+For pages with the [`"document"` type](/reference/pages#title) (the default), their table of contents is automatically generated from the header hierarchy. For this reason it’s critical that each document begin with an `h1` and that for all `N > 1`, all `h{N}` immediately follow an `h{N-1}`. For example an `h3` should never succeed an `h1`.
+
+</div></details>
+
+</ContentColumn>

products/docs-engine/src/content/getting-started.md → products/docs-engine/src/content/how-it-works.md

@@ -2,37 +2,41 @@
 order: 1
 ---
 
-# Getting started
+# How it works
 
-<Aside type="warning">
+<Aside>
 
-__Warning:__ The process for building a docs site using the Cloudflare Docs Engine is currently in flux. Please hold off on using the Docs Engine until this notice is removed.
+__Note for Cloudflare employees:__ The details of this process are still being worked out. For the time being, please do not migrate any Cloudflare products without first checking in Adam ([afs@cloudflare.com](mailto:afs@cloudflare.com), [@adamschwartz on Github](https://github.com/adamschwartz)). Thanks for your patience.
 
 </Aside>
 
-<Aside>
+In short, docs sites built with the Cloudflare Docs Engine are [Gatsby](https://www.gatsbyjs.com) sites with a bunch of [custom MDX components](/markdown) and a shell UI you that’s consistent across products, all deployed as a [Workers Sites project](https://workers.cloudflare.com/sites) via the [Wrangler Github Action](https://github.com/cloudflare/wrangler-action).
 
-__Note:__ The instructions below assume that you already have a paid [Cloudflare Workers](https://workers.cloudflare.com) account, so you can deploy your docs site using [Workers Sites](https://workers.cloudflare.com/sites). You can theoretically use any static site deploy tool; however only Workers Sites has been tested at this time.
+--------------------------------
 
-</Aside>
+## Requirements
 
-In short, docs sites built with the Cloudflare Docs Engine are [Gatsby](https://www.gatsbyjs.com) sites with a bunch of [custom MDX components](/markdown) and a shell UI you that’s consistent across products, all deployed as a [Workers Sites project](https://workers.cloudflare.com/sites) via the [Wrangler Github Action](https://github.com/cloudflare/wrangler-action).
+The instructions below assume you already have a paid [Cloudflare Workers](https://workers.cloudflare.com) account so you can deploy your docs site using [Workers Sites](https://workers.cloudflare.com/sites). You can theoretically use any static site deploy tool; however, only Workers Sites has been tested at this time.
 
 --------------------------------
 
 ## Minimal setup
 
-To create a new docs site built with the Cloudflare Docs Engine, you’ll need the following:
+Each docs site built with the engine needs the following structure:
 
 1. A `package.json` with one dependency and some custom scripts configured.
 2. A `docs-config.js` which exports a JavaScript object for configuring a number of strings and a few settings.
 3. A `wrangler.toml` with the correct `[site]` configured.
 4. A `.gitignore` file which ignores at least `.docs`, `dist/worker.js`, and `node_modules`.
 5. Content — An `index.md` file in `src/content/` will do.
 
+All of these files can be in the root, as is the case with the [Docs Engine example](https://github.com/adamschwartz/docs-engine-example/tree/c45fa9f0a8affc68baf5d3517f8b890ba0522531).
+
+However, this whole structure can also be placed inside any sub-folder of your project. When doing this, you’ll need to then customize the `contentRepoFolder` property in `docs-config.js`, which is how the [products inside @cloudflare/cloudflare-docs](https://github.com/cloudflare/cloudflare-docs/tree/master/products) are all set up, e.g. the [Workers product](https://github.com/cloudflare/cloudflare-docs/blob/1efd366c25bc1bdd1a40f7bc4737310c6b00d15e/products/workers/docs-config.js#L6).
+
 ### 1. package.json
 
-Your `package.json` needs to depend on the Docs Engine (located at @adamschwartz/cloudflare-docs-engine for now), and it needs to include three scripts:
+Your `package.json` needs to depend on the Docs Engine, and it needs to include scripts for bootstrapping the engine, building the project, and local development.
 
 ```json
 ---
@@ -42,7 +46,7 @@ highlight: [4, 7, 8, 9]
 {
   "private": true,
   "dependencies": {
-    "cloudflare-docs-engine": "git+https://github.com/adamschwartz/cloudflare-docs-engine.git"
+    "cloudflare-docs-engine": "git+https://github.com/cloudflare/cloudflare-docs-engine.git"
   },
   "scripts": {
     "bootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh bootstrap",
@@ -52,11 +56,9 @@ highlight: [4, 7, 8, 9]
 }
 ```
 
-More on this later.
-
 ### 2. docs-config.js
 
-In the root, you’ll also need a `docs-config.js` file, similar to [`gatsby-config.js`](https://www.gatsbyjs.com/docs/api-files-gatsby-config/):
+You’ll also need a `docs-config.js` file, which is used to customize the project’s title, logo, external links menu, and site metadata, which are used to populate fields inside the project’s underlying [`gatsby-config.js`](https://www.gatsbyjs.com/docs/api-files-gatsby-config/):
 
 ```js
 ---
@@ -68,13 +70,9 @@ module.exports = {
   productLogoPathD: "M8 8v32h32V26H22V8zm18-2h16v16H26z",
   contentRepo: "adamschwartz/docs-engine-example",
   externalLinks: [
-    {
-      title: "Adam Schwartz website",
-      url: "https://adamschwartz.co"
-    },
     {
       title: "Docs Engine on GitHub",
-      url: "https://github.com/adamschwartz/cloudflare-docs-engine"
+      url: "https://github.com/cloudflare/cloudflare-docs-engine"
     },
     {
       title: "example.com",
@@ -87,19 +85,25 @@ module.exports = {
   },
   siteMetadata: {
     title: "Example docs",
-    description: "These docs are an example of of a docs site built with https://github.com/cloudflare/workers-docs-engine.",
+    description: "These docs are an example of of a docs site built with the Cloudflare Docs Engine.",
     author: "@adamschwartz",
-    url: "http://adamschwartz.co/docs-engine-example",
+    url: "https://docs-engine-example.adam.workers.dev/",
     image: "data:image/x-icon;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQEAYAAABPYyMiAAAABmJLR0T///////8JWPfcAAAACXBIWXMAAABIAAAASABGyWs+AAAAF0lEQVRIx2NgGAWjYBSMglEwCkbBSAcACBAAAeaR9cIAAAAASUVORK5CYII=",
   },
 }
 ```
 
-Many of these fields are self-explanatory. View the [site configuration docs](/site-configuration) for more information.
+The `search` field is used to add a search to the site, powered by Algolia DocSearch. To hide search, set `search.indexName` and `search.apiKey` to the empty string, as in the example above. For an example of a project using search, see the [Workers config](https://github.com/cloudflare/cloudflare-docs/blob/e72247549d20f649786251d0368de19560d1bbb2/products/workers/docs-config.js#L21-L24).
+
+Many of the other fields are self-explanatory. See [Configuration](/reference/configuration) for details.
 
 ### 3. wrangler.toml
 
-Configure the Workers Sites `bucket` and `entry-point` with a `.docs` prefix.
+Each docs site is deployed as a [Workers Sites project](https://workers.cloudflare.com/sites) via a [Wrangler Github Action](https://github.com/cloudflare/wrangler-action).
+
+To set this up, you’ll need to [configure your `wrangler.toml`](https://developers.cloudflare.com/workers/cli-wrangler/configuration#keys) file just as you would any other [Workers Sites project](https://developers.cloudflare.com/workers/platform/sites/).
+
+Since the Docs Engine builds your site inside a hidden `.docs` folder, you’ll need to set your `bucket` and `entry-point` appropriately with the `.docs/` prefix.
 
 ```toml
 ---
@@ -145,6 +149,8 @@ Some helpful things to know:
 
 - If you want to create reusable “partials” that don’t generate pages, start the file names with `_`. See [an example in the Workers docs](https://github.com/cloudflare/workers-docs-engine/blob/9cd282f3384bb07a98498816954408001149f348/src/content/_partials/_tutorials-before-you-start.md). Then you can [import them](https://github.com/cloudflare/workers-docs-engine/blob/9cd282f3384bb07a98498816954408001149f348/src/content/tutorials/build-a-slackbot/index.md#L6-L10) as you would any other MDX component.
 
+Learn more about the [content framework](/contributing/content-framework) used by new Cloudflare docs sites and how to use the [built-in MDX components](/reference/markdown).
+
 --------------------------------
 
 ## Example site
@@ -167,5 +173,5 @@ __[Open demo](https://docs-engine-example.adam.workers.dev)__ · ([Github](https
 
 ## See also
 
-- [Docs Engine Markdown](/markdown)
-- [Site configuration](/site-configuration)
+- [Markdown reference](/reference/markdown)
+- [Configuration reference](/reference/configuration)

products/docs-engine/src/content/how-to-guides/contribute-to-a-product.md

@@ -0,0 +1,29 @@
+---
+order: 1
+---
+
+# Contribute to a product
+
+<Aside>
+
+__Note for Cloudflare employees:__ The details of this process are still being worked out. For the time being, please do not migrate any Cloudflare products without first checking in with Adam ([afs@cloudflare.com](mailto:afs@cloudflare.com), [@adamschwartz on Github](https://github.com/adamschwartz)). Thanks for your patience.
+
+</Aside>
+
+This document is intended to help __Cloudflare employees__ contribute to products that have already been migrated to the new Docs Engine.
+
+A product has been migrated if it is listed in the [migration table](https://github.com/cloudflare/cloudflare-docs#migration-progress) and its `Prod` column contains a link to a production site at `developers.cloudflare.com/$productName`.
+
+--------------------------------
+
+## Two ways to contibute
+
+1. For small changes, simply find the `.md` file you want to modify inside the product’s `src/content/` directory. The `Edit on Github` link in the footer of every deployed page will automatically link you there.
+
+2. For larger changes, or changes made to multiple files at once, you’ll want to set up a local development environment, which you can do by [following these steps](/how-to-guides/migrate-a-product#step-2-set-up-local-development).
+
+--------------------------------
+
+## Stay tuned...
+
+These docs are in active development.

products/docs-engine/src/content/how-to-guides/index.md

@@ -0,0 +1,8 @@
+---
+type: overview
+order: 2
+---
+
+# How-to guides
+
+<DirectoryListing path="/how-to-guides"/>