FAQ
Why a Docs Engine?
tl:dr; You write good Markdown (MDX), 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. Over time we’ve found that it’s especially difficult to balance two important goals:
- Content is easily managed by the product team that owns it.
- 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 and a wide variety of composable MDX components.
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).
The link text is automatically determined by the title of the page, which by default comes from the first h1 inside the document.
How does the table of contents work?
For pages with the "document" type (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.
How does the search work?
Search is powered by Algolia DocSearch and must be configured in docs-config.js. Make a PR on @algolia/docsearch-configs to obtain an indexName and apiKey (e.g. see the Workers PR). Then simply set those values as search.indexName and search.apiKey (e.g. see the Workers config). To disable search, set those values to the empty string (e.g. Docs Engine example site).