Formatting Guide

The pfSense® software documentation is built using Sphinx/reStructuredText. The formatting is similar in some ways to Markdown, but has significant differences. To get a feel for the formatting, and read through this document.

Tip

Test out how different markup is rendered using the Online reStructuredText editor. Additional information can be found at A primer on reStructuredText and reST/Sphinx cheat sheet.

Filenames

When adding new pages or images use all lowercase letters and hyphens instead of spaces for the filename. This is commonly referred to as a slug, or a slugified version of the text. For example, this file is named formatting-guide.rst. When possible, try to find a meaningful single word for the filename instead of using lengthy names.

Tip

Use an online slug generator.

Text

In general try to keep text in logical paragraphs wrapped at 80 characters. This ensures the source is easy for everyone to read no matter where it is being edited. For long pages with several sections that may only be relevant to some users, split the page into several smaller documents.

Basic Inline Formatting

Add basic inline formatting to the text as follows:

  • one asterisk: *text* for emphasis (italics),

  • two asterisks: **text** for strong emphasis (boldface), and

  • backquotes: ``text`` for code samples.

  • To start a block of literal formatted text such as code, console input/output, log data, etc., use .. code-block:: followed by a blank line. Prefix each line inside the block with three spaces:

    .. code-block::

   code

These can be applied to text in various ways within the documentation:

  • Menu references use bold text and “>” with spaces in between to separate menus from menu items: System > General

    • Navigation that also refers to a tab name should be formatted like so: System > Advanced, Miscellaneous tab.

  • GUI text references and option names use bold text: Description

  • Text to be entered or replaced by the user uses backquotes: Enter 192.168.1.1 for the IPv4 Address.

  • Options selected by the user from a list or drop-down are italic: Select WAN for the Interface.

  • File names and paths use backquotes: /root

  • Commands names inline with other text use backquotes, “The sudo command …”.

  • Shell commands being demonstrated or directed use code blocks. Start a code block as usual and then use # followed by a space to simulate a command prompt:

    # ls -l /root

  • Program output also uses code blocks. Blank lines in output can either be blank so that a line does not contain only whitespace:

    # someprogram
Output:

Foo

  • Do not leave any trailing whitespace on lines or any lines containing only whitespace.

  • Lines should be indented with spaces, not tabs. Tabs may be used inside literal blocks.

  • Use UTF-8 encoding.

Headings

Headings consist of text and a line of characters underneath (“underline”) the same length as the text. The specific characters must be consistent to denote sections of the same depth in a single file. Parts and chapters also use a similar row of characters above the text (“overline”).

  • #### with overline, for parts

  • **** with overline, for chapters

  • ====, for sections

  • ----, for subsections

  • ~~~~, for subsubsections

  • ````, for paragraphs

Example:

This is a Section Heading
=========================

The specific characters are not as important as being consistent. The parser considers each file separately so there is no need to track and be consistent across multiple files even if they are in the same chapter/section/etc.

Note

The headings are also how the “On This Page” section is generated. When possible, use headings that create an outline of the content, making it easy for the reader to scan.

Lists

Sphinx supports several types of item lists suitable for various purposes.

Unordered Lists

Place an asterisk followed by a space at the start of a paragraph and indent two additional spaces for any lines that wrap.

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

Which renders as:

  • This is a bulleted list.

  • It has two items, the second item uses two lines.

Ordered lists

Ordered lists are auto-numbered by prefixing a line with #. followed by a space. Indent lines that wrap with three additional spaces:

#. This is a numbered list.
#. It has two items too.
   This second item has two lines, too.

Which renders as:

  1. This is a numbered list.

  2. It has two items too. This second item has two lines, too.

Nested lists

Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Which renders as:

  • this is

  • a list

    • with a nested list

    • and some subitems

  • and here the parent list continues

Definition lists

Definition lists are created as follows:

term (up to a line of text)
  Definition of the term, which must be indented

  and can even consist of multiple paragraphs

next term
  Description.

Note

The term itself cannot have more than one line of text.

Which renders as:

term (up to a line of text)

Definition of the term, which must be indented

and can even consist of multiple paragraphs

next term

Description.

Warning

These lists cannot be nested more than three levels deep in ordered, unordered, definition, or field lists or it breaks PDF building.

Field Lists

Field lists are perfect for lists of options. They start with the field name starting and ending with a colon, followed by text describing the field. The content should start on a new line under the field name and should be indented two space. Though starting on a new line is optional in the parser, starting on a blank line makes the formatting cleaner and easier to follow.

:Option Name:
  What it does.
:Option 2:
  Another option. This is a long description that wraps to the next line,
  with two spaces indentation.
:Third Option:
  Something else.

Which renders as:

Option Name:

What it does.

Option 2:

Another option. This is a long description that wraps to the next line, with two spaces indentation.

Third Option:

Something else.

Warning

These lists cannot be nested more than three levels deep in ordered, unordered, definition, or field lists or it breaks PDF building.

Images

Images

Place images in the source/_static directory in the same folder structure as the page that the image is going to be posted on. For example, an image within source/references/fomatting-guide.rst would go in source/_static/references/image.png.

.. image::
   /_static/filename.*
   :align:
     center
   :alt:
     Alternative text that describes the image
   :target:
     /_static/filename.png

Note

:target: is optional and only necessary if it is a large image.

Figures

Place figures in the source/_static directory in the same folder structure as the page that the image is going to be posted on. For example, an image within source/references/fomatting-guide.rst would go in source/_static/references/image.png.

Figures are similar to images, but need a unique label and a caption for proper in-text references.

.. _figure-my-stuff:
.. figure::
   /_static/stuff.*
   :figclass:
     align-center
   :target:
     /_static/stuff.png

   This is the caption

Note

:target: is optional and only necessary if it is a large image.

Which can be referred to using the following:

An example is shown in Figure :ref:`figure-my-stuff`.

Warning

The indention is important! The caption must be aligned properly with the other attributes!

Inline Images

Inline images (no breaks above or below, aka inline with the text) require using a substitution. Since inline images are typically inserted on many pages, inline image files can be placed in the root of source/_static or an appropriate subdirectory.

Many common icon substitutions are available in a common substitutions file which is automatically included in all source files and usable as follows:

To add a blah, click |fa-plus|.

To do this in a one-off fashion, use a substitution within the same file:

Click |image_icon_edit| to edit the entry
<rest of page>
.. |image_icon_edit| image:: _static/icons/fa-pencil.*

Tables

Grid Tables

The grid must be “painted”, they look like this example:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Simple Tables

These are easier to write, but are limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Table of Contents

Every file has to a part of a toctree or Table of Contents tree, as this is how the side navigation is built.

Reference RST files by their filenames without their .rst extension. It is also possible to link to external resources if necessary, as shown with the YouTube link:

.. toctree::
   :maxdepth:
     2

   filename1
   filename2
   sub-directory/index
   Example YouTube Video <https://youtu.be/Cwz7vWu_KO0>

Local Table of Contents

Sometimes it is useful to add the table of contents of the current page:

.. contents::
   :depth:
     2

Admonitions (Colored Boxes)

Admonitions are text, distinguished in formatted boxes, that bring attention to important items.

Admonitions are similar to other directives, starting with two periods and a space followed by the admonition name and then two colons, e.g. .. note::.

Though the parser allows the text to start after the directive, the best practice is to start the text content on a line under the admonition which makes the formatting easier to follow and wrap consistently.

The most common example is a “Note” box:

.. note::
   This is a note, it will be surrounded by a note box when it is built.

Which renders as:

Note

This is a note, it will be surrounded by a note box when it is built.

Admonitions are available for a wide variety of types, including:

  • note

  • tip

  • warning

  • attention

  • caution

  • danger

  • error

  • hint

  • important

  • seealso

Substitutions

reST substitutions are pieces of text and/or markup which the parser will replace with another (usually longer) string or element. Substitutions are referred to in the text by |name|.

Substitutions are useful for inline images, links or references to be used in many documents, or even commonly repeated strings which may need to change over time. Rather than finding and replacing every reference so such items manually, they can be managed from a shared source.

Substitutions are defined like footnotes with explicit markup blocks, for example:

.. |name| replace:: replacement *text*

or this:

.. |caution| image:: warning.png
             :alt:
               Warning!

To use substitutions for multiple documents, put them into a separate file and include it into all documents where they will be used, using the include directive. Give the include file a file name extension differing from that of other source files, such as .rsti, to avoid Sphinx finding it as a standalone document.

Note

The common substitutions file is automatically included in all documents. Check that file before adding more substitutions in other files. Substitutions which will be widely used in many documents should be placed there.

Literal (code) Blocks

Briefly described earlier, literal or “code” blocks allow for pre-formatted text, most commonly used for source code, shell commands, command output, and so on.

A code block for general use, such as for log data, shell input/output, or command examples should be started with .. code-block:: followed by a blank line. Prefix each non-blank line inside the block with three spaces.

.. code-block::

   code

The lines inside the code block must be indented to the same level, usually three spaces.

For an blank line inside the code block, use a completely empty line, not a line containing only whitespace.

For more complex examples, syntax highlighting can be used for source code using the code-block directive followed by the type of content inside the block:

.. code-block::
   html
   :linenos:

   <b>some html</b>

Which renders as:

1<b>some html</b>