NGINX Documentation

CONTRIBUTING

This file defines the conventions we use for material published at docs.nginx.com, concentrating on Markdown syntax.

Headings

To indicate a heading, place one or more hash symbols ( # ) at the start of the line, followed by one space and the title. The number of # symbols corresponds to the HTML `<hX’> tag:

  • One # = <h1> tag
  • Two ## = <h2> tag
  • Three ### = <h3> tag
  • Four #### = <h4> tag

It is generally pointless to use headings at level 5 or higher; their formatting cannot be distinguished from regular text.

Important Notes:

  • There can be only one <h1> level heading (single hash symbol) in a file, on the first line. This heading is the article title that appears in the left navigation bar on docs.nginx.com. If there is another # heading, the content below it is ignored.
  • Be sure to put a space between the hash symbols and the title:
    • Correct: ## Configuring High Availability
    • Incorrecr: ##Configuring High Availability
  • You can use bold and monospace formatting in a heading, though the former doesn’t always change the appearance.

HTML Comment

To wrap some text with HTML comment syntax use <!-- some text --> . The restriction is you are not allowed to use this comment syntax for multiline. If you need to comment out multiple lines then use separate comment tag for each line.

HTML Character Entities

HTML character entities were breaking the words and making new paragraph.

Now you can use html character entities like ,  , but do not use this in any heading tag. Heading tags start with #, ##, ### , ####.

You are allowed to use following entities. If you need any new item, tell the NGINX web team.

  •  
  • ÷
  • ©
  • ©
  • ®
  • ®
  • &
  • <
  • >
  • .
  • ´
  • ć
  • ã
  • °

HTML Tables

We are unable to use Markdown table syntax. We use reStructuredText (reST) syntax. To use rST in Markdown, use a code block with the eval_rst signifier.

Example: ```eval_rst

reST code here ```

rST table syntax:

There are several ways to format tables using rST. List table is the recommended format. See the docutils documentation for more information: http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table

Example:

.. list-table:: Frozen Delights!
    :widths: 15 10 30
    :header-rows: 1

    * - Treat
      - Quantity
      - Description
    * - Albatross
      - 2.99
      - On a stick!
    * - Crunchy Frog
      - 1.49
      - If we took the bones out, it wouldn't be
        crunchy, now would it?
    * - Gannet Ripple
      - 1.99
      - On a stick!

Resources

Code Block with Color Syntax Highlighting

  • See the RecommonMark Auto-Structify docs.
  • Put code inside two sets of triple backticks (/```)
  • After first backtick, write the name of code language. You can find all supported code language names here: http://pygments.org/docs/lexers/
  • For nginx configuration codes set nginx as the code block language. Example: ```nginx

Meta Tags

To add meta tags use rst syntax. Add code at the beginning of the markdown file just before the document title.

Example 1: Add meta description

```eval_rst .. meta:: :description: detail text here ```

# Document title here

The above code generates the following HTML output:

<meta name="description" content="detail text here" />

Example 2: Add meta keywords

```eval_rst .. meta:: :keywords: nginx, installing, open source,etc ``` # Document title here

The above code generates following HTML output:

<meta name="keywords" content="nginx, installing, open source,etc" />

Example 3: Multiple meta tags

```eval_rst .. meta:: :description: detail text here :keywords: nginx, installing, open source,etc ``` # Document title here

The above code generates following HTML output:

<meta name="description" content="detail text here" />
<meta name="keywords" content="nginx, installing, open source,etc" />