From 00f7a31a46ad88efc70fa67390eef5cb858c1292 Mon Sep 17 00:00:00 2001 From: Adam Schwartz Date: Mon, 5 Oct 2020 15:01:21 -0400 Subject: [PATCH] docs engine content updates (wip) --- .../content-framework.md} | 4 +- .../content/contributing/development-setup.md | 66 +++++++ .../src/content/contributing/index.md | 8 + .../content/contributing/to-docs-engine.md | 22 +++ .../src/content/example-pages/index.md | 9 - .../code-block-examples.md | 2 +- .../docs-engine/src/content/examples/index.md | 8 + .../pages}/class.md | 0 .../pages}/example.md | 0 .../src/content/examples/pages/index.md | 9 + products/docs-engine/src/content/faq.md | 37 ++++ .../{getting-started.md => how-it-works.md} | 54 +++--- .../how-to-guides/contribute-to-a-product.md | 29 +++ .../src/content/how-to-guides/index.md | 8 + .../how-to-guides/migrate-a-product.md | 119 ++++++++++++ .../how-to-guides/set-up-a-new-repo.md | 40 ++++ products/docs-engine/src/content/index.md | 41 ++--- .../src/content/reference/configuration.md | 154 ++++++++++++++++ .../src/content/reference/index.md | 8 + .../src/content/{ => reference}/markdown.md | 88 +-------- .../src/content/reference/pages.md | 172 ++++++++++++++++++ .../src/content/site-configuration.md | 56 ------ 22 files changed, 731 insertions(+), 203 deletions(-) rename products/docs-engine/src/content/{contributors-guide.md => contributing/content-framework.md} (99%) create mode 100644 products/docs-engine/src/content/contributing/development-setup.md create mode 100644 products/docs-engine/src/content/contributing/index.md create mode 100644 products/docs-engine/src/content/contributing/to-docs-engine.md delete mode 100644 products/docs-engine/src/content/example-pages/index.md rename products/docs-engine/src/content/{markdown => examples}/code-block-examples.md (99%) create mode 100644 products/docs-engine/src/content/examples/index.md rename products/docs-engine/src/content/{example-pages => examples/pages}/class.md (100%) rename products/docs-engine/src/content/{example-pages => examples/pages}/example.md (100%) create mode 100644 products/docs-engine/src/content/examples/pages/index.md create mode 100644 products/docs-engine/src/content/faq.md rename products/docs-engine/src/content/{getting-started.md => how-it-works.md} (57%) create mode 100644 products/docs-engine/src/content/how-to-guides/contribute-to-a-product.md create mode 100644 products/docs-engine/src/content/how-to-guides/index.md create mode 100644 products/docs-engine/src/content/how-to-guides/migrate-a-product.md create mode 100644 products/docs-engine/src/content/how-to-guides/set-up-a-new-repo.md create mode 100644 products/docs-engine/src/content/reference/configuration.md create mode 100644 products/docs-engine/src/content/reference/index.md rename products/docs-engine/src/content/{ => reference}/markdown.md (83%) create mode 100644 products/docs-engine/src/content/reference/pages.md delete mode 100644 products/docs-engine/src/content/site-configuration.md diff --git a/products/docs-engine/src/content/contributors-guide.md b/products/docs-engine/src/content/contributing/content-framework.md similarity index 99% rename from products/docs-engine/src/content/contributors-guide.md rename to products/docs-engine/src/content/contributing/content-framework.md index f5042d4bc497b6..04f13186fde6b3 100644 --- a/products/docs-engine/src/content/contributors-guide.md +++ b/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. diff --git a/products/docs-engine/src/content/contributing/development-setup.md b/products/docs-engine/src/content/contributing/development-setup.md new file mode 100644 index 00000000000000..4409a89c10765c --- /dev/null +++ b/products/docs-engine/src/content/contributing/development-setup.md @@ -0,0 +1,66 @@ +--- +order: 0 +--- + +# Development setup + + + +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. + + diff --git a/products/docs-engine/src/content/contributing/index.md b/products/docs-engine/src/content/contributing/index.md new file mode 100644 index 00000000000000..4f118597b05625 --- /dev/null +++ b/products/docs-engine/src/content/contributing/index.md @@ -0,0 +1,8 @@ +--- +type: overview +order: 3 +--- + +# Contributing + + diff --git a/products/docs-engine/src/content/contributing/to-docs-engine.md b/products/docs-engine/src/content/contributing/to-docs-engine.md new file mode 100644 index 00000000000000..08b394a23f35e6 --- /dev/null +++ b/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. diff --git a/products/docs-engine/src/content/example-pages/index.md b/products/docs-engine/src/content/example-pages/index.md deleted file mode 100644 index 03f20a33ad14ed..00000000000000 --- a/products/docs-engine/src/content/example-pages/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -order: 20 ---- - -# Example pages - -Use these as a starting point for writing consistent documentation. - - diff --git a/products/docs-engine/src/content/markdown/code-block-examples.md b/products/docs-engine/src/content/examples/code-block-examples.md similarity index 99% rename from products/docs-engine/src/content/markdown/code-block-examples.md rename to products/docs-engine/src/content/examples/code-block-examples.md index 844c012ef17e41..432f7ce25907e4 100644 --- a/products/docs-engine/src/content/markdown/code-block-examples.md +++ b/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). -------------------------------- diff --git a/products/docs-engine/src/content/examples/index.md b/products/docs-engine/src/content/examples/index.md new file mode 100644 index 00000000000000..99441d4f1c6f5f --- /dev/null +++ b/products/docs-engine/src/content/examples/index.md @@ -0,0 +1,8 @@ +--- +type: overview +order: 5 +--- + +# Examples + + diff --git a/products/docs-engine/src/content/example-pages/class.md b/products/docs-engine/src/content/examples/pages/class.md similarity index 100% rename from products/docs-engine/src/content/example-pages/class.md rename to products/docs-engine/src/content/examples/pages/class.md diff --git a/products/docs-engine/src/content/example-pages/example.md b/products/docs-engine/src/content/examples/pages/example.md similarity index 100% rename from products/docs-engine/src/content/example-pages/example.md rename to products/docs-engine/src/content/examples/pages/example.md diff --git a/products/docs-engine/src/content/examples/pages/index.md b/products/docs-engine/src/content/examples/pages/index.md new file mode 100644 index 00000000000000..eabd103b7a1c3b --- /dev/null +++ b/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. + + diff --git a/products/docs-engine/src/content/faq.md b/products/docs-engine/src/content/faq.md new file mode 100644 index 00000000000000..153a21a5469b14 --- /dev/null +++ b/products/docs-engine/src/content/faq.md @@ -0,0 +1,37 @@ +--- +type: overview +order: 6 +--- + +# FAQ + + + +
Why a Docs Engine?
+ +__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). + +
+ +
How does the main navigation work?
+ +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. + +
+ +
How does the table of contents work?
+ +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`. + +
+ + diff --git a/products/docs-engine/src/content/getting-started.md b/products/docs-engine/src/content/how-it-works.md similarity index 57% rename from products/docs-engine/src/content/getting-started.md rename to products/docs-engine/src/content/how-it-works.md index 66cee3841ea0e2..ec42e442a0b7d0 100644 --- a/products/docs-engine/src/content/getting-started.md +++ b/products/docs-engine/src/content/how-it-works.md @@ -2,27 +2,27 @@ order: 1 --- -# Getting started +# How it works -