Skip to content
Docs Engine
Visit Docs Engine on GitHub
Set theme to dark (⇧+D)

Formatting

This document provides general formatting and typography guidelines for Cloudflare documentation.


General formatting

  • Use sentence casing for headlines and page titles.

  • Ensure proper header hierarchy. 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.

  • For longer pages, use a separator between h2 sections. Written as an <hr/> in Markdown (--------):

    ## Some heading
    Imagine several paragraphs of text here.
    --------------------------------
    ## Some other heading
    <!-- ... -->
  • Always add a language hint to code blocks. If you don’t want any syntax highlighting, explicitly use txt:

    ```txt
    https://example.com
    ```
  • When using an ellipsis (...) in a code block, make sure to place it in a comment for the appropriate language.

    Here’s an example:
    ```js
    let foo = "bar"
    // ...
    console.log(foo)
    ```

Typography

As the medium of communication, typography is critical to writing great documentation.

When contributing to Cloudflare docs, make sure to follow best practices for good typography. Butterick’s Practical Typography is a great resource for technical writers, and especially the “type composition“ guidelines should be followed for these docs.

Specifically, please make sure to:


← Writing styleAccessibility →