Skip to content

Latest commit

 

History

History
205 lines (129 loc) · 9.87 KB

CONTRIBUTING_DOCS.md

File metadata and controls

205 lines (129 loc) · 9.87 KB

Contributing guidelines for writers

This page describes our guidelines on using Hugo to write documentation.

You will need git to interact with the repository and files: the content itself is written in Markdown.

Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes.

If you're an employee of F5/NGINX, also read For F5/NGINX Employees.

Setup

You will need to install Hugo or Docker to build and preview docs in your local development environment.

Read the Hugo installation instructions for more information.

If you have Docker installed, there are fallbacks for all requirements in the Makefile, meaning you don't need to install them.

The configuration files are as follows:

  • Hugo: config/default/config.toml
  • markdownlint-cli: .markdownlint.json
  • markdown-link-check md-linkcheck-config.json

Develop documentation locally

To build the documentation website locally, use the make command in the documentation folder.

First ensure you have the latest version of the Hugo theme with:

make hugo-update

Once you've updated the theme, you can use these targets:

Target Description
make watch Runs a local Hugo server, allowing for changes to be previewed in a browser.
make drafts Runs a local Hugo server, rendering documents marked with draft: true in their metadata.
make docs Builds the documentation in the local public/ directory.
make clean Removes the local public directory
make hugo-get Updates the go module file with the latest version of the theme.
make hugo-tidy Removes unnecessary dependencies from the go module file.
make hugo-update Runs the hugo-get and hugo-tidy targets in sequence.
make lint-markdown Runs markdownlint on the content folder.
make link-check Runs markdown-link-check on all Markdown files.

Add new documentation

We use Hugo archetypes to provide structure for new documentation pages.

Archetypes are how Hugo represents templates for content.

These archetypes include inline advice on Markdown formatting and our most common style guide conventions.

To create a new page, run the following command:

hugo new content <product/folder/filename.md>

This new page will be created with the default how-to archetype. To use a specific archetype, add the -k parameter and its name, such as:

hugo new content <product/folder/filename.md> -k <archetype>

Our archetypes currently include the following:

  • default (How-to instructions, general use)
  • concept(An explanation of one implementation detail and some use cases)
  • tutorial (An in-depth set of how-to instructions, referencing concepts)

These archetypes are adapted from some existing templates: please file an issue if you would like a new archetype.

How to format documentation

Basic Markdown formatting

There are multiple ways to format text: for consistency and clarity, these are our conventions:

  • Bold: Two asterisks on each side - **Bolded text**.
  • Italic: One underscore on each side - _Italicized text_.
  • Unordered lists: One dash - - Unordered list item.
  • Ordered lists: The 1 character followed by a stop - 1. Ordered list item.

Note: The ordered notation automatically enumerates lists when built by Hugo.

How to format internal links

Internal links should use the ref shortcode with absolute paths that start with a forward slash (for clarity).

Although file extensions (such as .md) are optional for Hugo, we include them for clarity and ease when targeting page anchors.

Here are two examples:

To install <software>, refer to the [installation instructions]({{< ref "/product/deploy/install.md" >}}).
To install <integation>, refer to the [integration instructions]({{< ref "/integration/thing.md#section" >}}).

How to use Hugo shortcodes

Hugo shortcodes are used to format callouts, add images, and reuse content across different pages.

For example, to use the note callout:

{{< note >}} Provide the text of the note here .{{< /note >}}

The callout shortcodes support multi-line blocks:

{{< caution >}}
You should probably never do this specific thing in a production environment.

If you do, and things break, don't say we didn't warn you.
{{< /caution >}}

Supported callouts:

  • note
  • tip
  • important
  • caution
  • warning

You can also create custom callouts using the call-out shortcode {{< call-out "type position" "header" "font-awesome icon >}}. For example:

{{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}

By default, all custom callouts are displayed inline, unless you add side-callout which places the callout to the right of the content.

Here are some other shortcodes:

  • fa: Inserts a Font Awesome icon
  • collapse: Make a section collapsible
  • tab: Create mutually exclusive tabbed window panes, useful for parallel instructions
  • table: Add scrollbars to wide tables for browsers with smaller viewports
  • link: Link to a file, prepending its path with the Hugo baseUrl
  • openapi: Loads an OpenAPI specification and render it as HTML using ReDoc
  • include: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory
  • raw-html: Include a block of raw HTML
  • readfile: Include the content of another file in the current file, which can be in an arbitrary location.
  • bootstrap-table: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. {{< bootstrap-table "table-bordered table-hover" }}

Add code to documentation pages

For command, binary, and process names, we sparingly use pairs of backticks (`<some-name>`): <some-name>.

Larger blocks of multi-line code text such as configuration files can be wrapped in triple backticks, with a language as a parameter for highlighted formatting.

You can also use the ghcode shortcode to embed a single file directly from GitHub:

{{< ghcode "<https://raw.githubusercontent.com/some-repository-file-link>" >}}

An example of this can be seen in /content/ngf/get-started.md, which embeds a YAML file.

Add images to documentation pages

Use the img shortcode to add images to documentation pages. It has the same parameters as the Hugo figure shortcode.

  1. Add the image to the /static/img directory.
  2. Add the img shortcode:
  • {{< img src="<img-file.png>" alt="<Alternative text>">}}
  • Do not include a forward slash at the beginning of the file path or it will break the image.

Important: We have strict guidelines for using images. Review them in our style guide.

How to use Hugo includes

Hugo includes are a custom shortcode that allows you to embed content stored in the /content/includes directory.

It allows for content to be defined once and display in multiple places without duplication, creating consistency and simplifying the maintenance of items such as reference tables.

For example, the licensing-and-reporting/apply-jwt.md file contains instructions for where to add a JWT license file to an NGINX instance.

To add it to a documentation page, use the path as a parameter for the include shortcode:

{{< include "licensing-and-reporting/apply-jwt.md" >}}

This particular include file is used in the following pages:

View the Guidelines for includes for instructions on how to write effective include files.

Linting

To use markdownlint to check content, run the following command:

markdownlint -c .markdownlint.yaml </content/path>

The content path can be an individual file or a folder.