Skip to content
Mihir's Projects
Docs
Mihir's Projects
Docs
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Docs on GitHub
Set theme to dark (⇧+D)

How it works

In short, docs sites built with the Cloudflare Docs Engine are Gatsby sites with a bunch of custom MDX components and a shell UI you that’s consistent across products, all deployed as a Workers Sites project via the Wrangler GitHub Action.

Requirements

The instructions below assume you already have a paid Cloudflare Workers account so you can deploy your docs site using Workers Sites. You can theoretically use any static site deploy tool; however, only Workers Sites has been tested at this time.

Minimal setup

Each docs site built with the engine needs the following structure:

  1. A package.json with the engine dependency and some custom scripts configured.
  2. A docs-config.js config which exports a JavaScript object.
  3. A wrangler.toml with the correct [site] configured.
  4. A .gitignore which ignores at least .docs, dist/worker.js, and node_modules.
  5. Content in src/content/ — A single index.md will do.

For a repo holding a single docs site, everything but the content should be in the root.

However, these files 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 are all set up, e.g. the Workers product.

1. package.json

Your package.json needs to depend on the Docs Engine, and it needs to include scripts for bootstrapping the engine, building the project, local development, and deployment.

package.json
{
  "private": true,
  "dependencies": {
    "cloudflare-docs-engine": "git+https://github.com/cloudflare/cloudflare-docs-engine.git"
  },
  "scripts": {
    "bootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh bootstrap",
    "build": "node_modules/cloudflare-docs-engine/bin/commands.sh build",
    "develop": "node_modules/cloudflare-docs-engine/bin/commands.sh develop",
    "ghactionsbootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh ghactionsbootstrap",
    "savechanges": "node_modules/cloudflare-docs-engine/bin/commands.sh savechanges",
    "serve": "node_modules/cloudflare-docs-engine/bin/commands.sh serve"
  }
}

2. docs-config.js

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:

docs-config.js
module.exports = {
  product: "Docs Engine",
  pathPrefix: "/docs-engine",
  productIconKey: "docs-engine",
  contentRepo: "cloudflare/cloudflare-docs",
  contentRepoFolder: "products/docs-engine",
  externalLinks: [
    {
      title: "Docs Engine on GitHub",
      url: "https://github.com/cloudflare/cloudflare-docs-engine"
    },
    {
      title: "Cloudflare Developer documentation",
      url: "https://developers.cloudflare.com/docs"
    },
  ],
  search: {
    indexName: "",
    apiKey: "",
    algoliaOptions: { "facetFilters": "" }
  },
  siteMetadata: {
    title: "Cloudflare Docs Engine docs",
    description: "Documentation for the open-source Cloudflare Documentation engine which powers Cloudflare's open-source documentation.",
    author: "@cloudflare",
    url: "http://developers.cloudflare.com/docs-engine",
    image: "https://www.cloudflare.com/img/cf-twitter-card.png",
  }
}

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.

Many of the other fields are self-explanatory. See Configuration for details.

3. wrangler.toml

Each docs site is deployed as a Workers Sites project via a Wrangler GitHub Action.

To set this up, you’ll need to configure your wrangler.toml file just as you would any other Workers Sites project.

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.

wrangler.toml
# ...


[site]
bucket = ".docs/public/" # Add pathPrefix here if necessary
entry-point = ".docs/workers-site"

4. gitignore

You’ll want to at least ignore these:

.gitignore
.docs
node_modules
dist/worker.js

5. Content

Last but not least, content.

Inside of src/content/ you must have at least an index.md. However outside of that, you can structure it more or less however you want.

Some helpful things to know:

  • The sidebar navigation tree and page paths are automatically generated from the file structure and naming in src/content/.

    • Page title is automatically pulled from the first h1 (# in Markdown) in the document if no front matter title is specified.

    • index.md files inside sub-folders of src/content/ will take the pathname of their parent directory.

  • You can include custom MDX components in src/content/ as .js files right alongside your .md files. Import them relatively.

  • You can also include media the same way. For pages which reference several image files, a common pattern is group them in a media/ directory which is a sibling of the index.md file. So src/content/some-page/index.md and src/content/some-page/media/*.png.

  • If you want to create reusable “partials” that don’t generate pages, start the file names with _. See an example in the Workers docs. Then you can import them as you would any other MDX component.

Learn more about the content framework used by new Cloudflare docs sites and how to use the built-in MDX components.

See also