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 -