Markdown guidelines for Axway-Open-Docs

5 minute read

This docs-as-code implementation uses the Hugo static site generator and the Google Docsy theme to build this website from the Markdown content files. Hugo uses Goldmark to parse Markdown, which is CommonMark compliant.

If you are contributing using GitHub or Git CLI, use these guidelines to ensure that your Markdown renders correctly. You do not need to use these guidelines if you are contributing using Netlify CMS.

Editor recommendations

If you are editing Markdown locally, we recommend using VSCode with the markdownlint extension.

The custom configuration for markdownlint is contained in the file .markdownlint.json at the root of the Axway-Open-Docs repository. To load this configuration by default, always open the root folder (axway-open-docs) in VSCode.

Tips and tricks

Follow these tips when sending contributions using Markdown. If there is no explicit rule detailed here, use the recommendations in Markdown guide - Basic syntax.

Headings

Use hash characters (#) for headings. The number of hash characters determines the heading level.

For example:

## This is a H2

This is some text

### This is a H3

This is more text

## This is another H2

This is more text

Best practices:

• Do not use H1 headings (##) in your Markdown, as the title of the page becomes the H1.
• Do not skip heading levels, that is, do not follow a H2 with a H4.
• Do not use bold or other formatting for headings.

Emphasis

Surround a word with single underscores (_) to apply italics for emphasis.

Surround a word with double asterisks (**) to apply bold for emphasis.

Best practices:

• Do not overuse emphasis.
• In general, use bold only for UI buttons and fields.
• Use italics only when introducing a new term or to draw extra attention to a word or phrase.

Blockquotes

Although Markdown supports blockquotes, we generally don’t use blockquotes in technical documentation.

Lists

To create a numbered list add list items with numbers followed by periods. The numbers must be in numerical order.

To create a bulleted list add list items with asterisks (*).

To create a nested list, indent the list items by 4 spaces.

Definition lists

Use definition lists only for listing terms and associated definitions, such as in a glossary of terms. Do not use definition lists for UI fields and descriptions.

Inline code

Use single backticks (`) to apply code or monospace formatting to a word or phrase within a sentence (inline code). For example, this command is inline.

Code blocks

Use three or more backticks (`) to open and close a code sample block.

Specify a programming language after the first set of backticks to apply syntax highlighting. See the supported languages in List of Chroma Highlighting Languages.

Here’s an example of a code sample with java syntax highlighting:

    ```java
    public class MyClass {
        public static void main(String[] args) {
            System.out.println("Hello World");
        }
    }
    ```

This renders as:

public class MyClass {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

Best practices:

• Do use code block styling for single and multiple-line code blocks.
• Do not use inline code styling for single line code blocks.

Links

To create a link, enclose the link text in square brackets and follow it with the URL in parentheses.

For example, [contribution guidelines](/docs/contribution_guidelines/) is rendered as contribution guidelines.

Use relative paths for all internal links.

Images

To add an image, use an exclamation mark (!), followed by alt text in square brackets, and the path to the image in parentheses, for example ![Image alt text](/Images/MyFolder/MyImage.png).

Add new images to the static/Images folder in the project, but note that the path to these images in the rendered site is just Images. For example, to add an image stored in static/Images/MyImage.png the correct image reference is ![My image alt text](/Images/MyImage.png) and not ![My image alt text](/static/Images/MyImage.png)

HTML

We do not allow any HTML tags within Markdown contributions, as HTML tags can be used in security attacks.

Tables

Markdown has limited support for tables. We support only pipe tables as described in Tables.

Table cells cannot contain multiple paragraphs, or code blocks, or lists. If you require a more complex table, consider using lists or alternative formatting instead.

If you have a simple table from another source (for example, Microsoft Excel) that you want to use in Markdown format, we recommend the Markdown Tables Generator.

Markdown extensions

Hugo and Docsy provide some useful extensions to standard Markdown that you can use to simplify editing and formatting.

Notes or alerts

Use an alert shortcode to draw the reader’s attention to something. For example:

For example:

{{% alert title="Note" %}}
This is a note.
{{% /alert %}}

This renders to:

See Docsy alert shortcode for more details.

Best practices:

• Do not use any other styling to highlight information, such as bold, bullet lists, and so on. To draw attention to something, always use an alert.

YouTube video links

To display a YouTube video preview on a page, use the following Hugo shortcode. You only need to specify the ID of the video.

For example:

{{< youtube Dq7GwLvRhLg >}}

This renders to:

See Hugo YouTube shortcode for more details.

Learn more

• The Markdown Guide

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.