Markup

Important

This page will be deprecated once all documentation pages are transitioned over to AsciiDoc.

Avoid ad hoc markup (for example, follow the rules below).

Use hn (for example, h1) HTML for heading levels.

Mark UI element text in bold, nothing else.

When referring to a menu item that appears with a …​ suffix (meaning a panel will open), don’t include the …​ suffix in the reference.

Example

If the More menu has an Update access token…​ item → ", and then click More > Update access token in the Action bar."

Mark the following types of content in Monospace (text between back ticks `` in Markdown):

  • All code related elements such as a code line, commands, or function, method, class, and variable names.

  • Paths, filenames, and file extensions.

  • UI or error message text.

  • User input values.

  • Keyboard keys.

Don’t use monospace/backticks for HTTP methods in prose:

  • HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) should be written in ALL CAPS without code formatting when used in running text.

    Examples

    ✅ Correct: "Make a POST request to the endpoint"

    ✅ Correct: "The API accepts GET and POST requests"

    ✅ Correct: "Use the HTTP DELETE method to remove the resource"

    ❌ Incorrect: "Make a POST request to the endpoint"

    ❌ Incorrect: "The API accepts GET and POST requests"

    Rationale: HTTP methods in prose refer to concepts, not code. Reserve backticks for actual code elements like endpoints, parameters, and variables.

DO use monospace/backticks for code elements:

  • Use backticks for API endpoints, URLs, parameters, variables, header names, JSON keys, and other code elements.

    Examples

    ✅ Correct: "Send a POST request to `https://api.example.com/endpoint`"

    ✅ Correct: "Set the method parameter to `POST`"

    ✅ Correct: "Include the Content-Type: application/json header"

    ✅ Correct: "The documentId field is required"

    ✅ Correct: "Configure http_method: "POST" in your settings"

    ❌ Incorrect: "Send a POST request to https://api.example.com/endpoint" (missing backticks on URL)

    ❌ Incorrect: "Set the method parameter to POST" (missing backticks on parameter and value)

Avoid using italics, limiting its usage to a case where a word or expression needs to be highlighted such as when defining it in the glossary.

When using italics, punctuation following an italicized word should also be italicized.

Don’t use underline markup.

Don’t use color markup.

  • Exception: use red markup to highlight a section of a path/URL or what changes between elements (for example, query syntax operators).