Publishing Documentation

MDS publishes documentation pages using templates intended for creation and use by many authors, not just engineers.

You don’t need to write code to publish a page. You can create a text file from a template, save it in a relevant folder location, add content through an easy-to-learn markdown syntax, and complete a few simple tags for template, title, and optional introduction.

Create a Page

For example, the template file markup to start this page would be:

{% set title = "Publishing Documentation" %}
{% set intro = "MDS publishes documentation pages using templates intended for creation and use by many authors, not just engineers." %}
{% extends "templates/doc.njk" %}

{% block doc_body %}
    {% filter markdown %}

    You don’t need to write code to publish a page.  You can create  a text file from a template, save it in a relevant folder location, add content through an easy-to-learn markdown syntax,  and complete a few simple tags for template, title, and optional introduction.
    ## Create a Page
    For example, the template file markup to start this page would be:

    {% endfilter %}
{% endblock %}

Step 1: Create a File

Once you have set up your local environment, you can get started with adding a new page. Documentation pages are stored within the src/doc/ across a range of subfolders corresponding to sections displayed in the site’s primary navigation.

/doc-site
  /docs
    /about
    /charts
    /components
    /editorial
    /page-examples
    /ux-patterns
    /visual-language

For example, to publish a page titled Publishing Documentation in the About section, save the publishing-documentation.njk file in the doc-site/docs/about/ folder.

Step 2: Configure the Template

The System offers features to configure the navigation, layout, and an automated table of contents of each page. At the top of the file, configure the template’s settings to adjust any defaults, and then identify the template using the extends tag. For example, set the following configuration to turn off the use of utility links and apply the correct template:

{% set page_nav_utility_links = false %}
{% extends 'templates/doc.njk' %}

Or, if you need to add a class to the body, use the body class property:

{% set body_class = "my-body-class" %}

Available Configurations

Property	Default	Result
`body_class`		When not empty, adds value as class(es) to the `<body>` element.
`full_bleed_row_enabled`	`false`	Adds a row to the main layout between the page title and main body content. The row content is included by enclosing it in a `full_bleed_row` block of the page.
`page_intro_enabled`	`true`	Includes the `title` and `intro` within a page `<header>` displayed above the main content.
`page_nav_additional_targets`	`false`	Include comma-separated CSS class selectors for content elements to be included in the page navigation.
`page_nav_enabled`	`true`	Display an autogenerated set of links on the right side of the layout based on second-level (`##`) and third-level (`###`) headings in the main content.
`page_nav_targets`	Default container	Defines the default element(s) to match via class lookup as `.mds-doc__content-inner > .mds-doc-long-form-text`. Avoid customizing this value, instead add additional classes to target using `page_nav_additional_targets`.
`page_nav_utility_links`	`true`	Includes a set of navigation links at the base of the page navigation on the right side of the layout.

Step 3: Specify a Title

Specify the page’s title by setting the title variable so that the same page title is rendered both within the viewport and as the page’s <title> tag:

{% set title = "Publishing Documentation" %}

Step 4: Include an Introduction

Optionally display a page’s lead introduction in larger font size using the intro variable:

{% set intro = "MDS publishes documentation pages using templates intended for creation and use by many authors, not just engineers." %}

Most pages are accessible from the site’s primary navigation. This navigation structure is produced dynamically from items organized in the doc-site/data/content.json file.

To add a page to the navigation, add an entry to the site_nav object that includes the page’s label and href, such as:

{
    "label": "Publishing Documentation",
    "href": "/resources/publishing-documentation.html"
},

Add Content

All page content exists within a doc_body block that contains mostly a mixture of markdown copy and custom documentation components, as well as – only when absolutely necessary – raw HTML.

Markdown

Markdown is a simple syntax for authors to create headers, lists, links and other elements in an otherwise clean text file. When publishing documentation, you’ll markup copy using simple syntax of headers, lists, and links bound by a markdown filter.

{% block doc_body %}
    {% filter markdown %}

      ## Second Level Header

      A paragraph.

      * A list item
      * Another list item

      ### Third Level Header

      Another paragraph.

    {% endfilter %}
{% endblock %}

While markdown offers a bevy of features, most content requires the following element types:

Type	Syntax
Headings	`## Second Level Header`
Paragraph	`paragraphs require no markup`
Unordered list	`* List item`
Ordered list	`1. Item 1`
Italic	`_italicized_ text`
Bold	`bold text`
Link	`[Google Homepage](http://www.google.com/)`
Image	`![Image alt text](relative image url)`
Code pill	Include a `$system-variable` inline or in a table.

You can find more detailed markdown documentation on sites such as Daring Fireball and Adam P’s Markdown Cheatsheet.

Images

To add an image to a documentation page, save it at 2x resolution PNG (or similar format) and store it in a commensurate subfolder of the doc-site/images/ directory. Those subfolders include:

/src
  /doc
    /assets
      /images
        /about
        /components
        /visual-language

For example, to include a new example.png image within the src/doc/visual-language/color.njk page, add example.png to the src/doc/images/visual-language/color/ directory, and reference that image within markdown as:

![Example alt text](/images/visual-language/color/example.png)

Add Documentation Components

For Code

Component	Use when	Example
Code Snippet	Displaying a code snippet without an associated example rendered in HTML.	`/doc-site/docs/visual-language/space.njk`
Example Code Pair	Displaying a code snippet following a stack of 1+ rendered examples, where the code snippet corresponds to the first rendered example.	`/doc-site/docs/components/buttons.njk`
HTML Example List	Displaying 1+ examples rendered in HTML without any corresponding code snippet(s).	`/doc-site/docs/visual-language/space.njk`

For Guidelines

Component	Use when	Example
Constants Table	Displaying all constants at a node of the constants hierarchy. Include sub-nodes by setting `include_subconstants=true`.	`/doc-site/docs/visual-language/constants.njk`
Do & Don’t	Displaying 1+ blocks of image & Do or Don’t text paired together and styled green or red, respectively.	`/doc-site/docs/components/buttons.njk`
Image Text Pair	Displaying an image and guidelines side-by-side.	`/doc-site/docs/components/buttons.njk`
Reference Table	Displaying multi-column tables of code references and examples. For custom column headers, include a `headers`array as a parameter.	`/doc-site/docs/components/buttons.njk`

For Visual Style

Component	Use when	Example
Hex	Displaying a hex value in a code pill with an associated color swatch.	`/doc-site/docs/visual-language/constants.njk`
Icon Swatch	Displaying an icon in a grid.	`/doc-site/docs/visual-language/iconography.njk`
Tint Stack	Displaying a stack of related color tints.	`/doc-site/docs/visual-language/color.njk`
Type Swatch	Displaying a stack of related type specimens.	`/doc-site/docs/visual-language/typography.njk`

Documentation Components to Avoid

Component	Rationale
Long Form Text
Site Navigation	Intended just for use with the MDS site.
Hero	Intended just for the site’s homepage.
Page Navigation	Intended just for the right rail navigation within a documentation page.

Customize CSS Styles

In rare cases, you may need to create CSS classes for custom displays within a documentation page. For example, you may want to render the outcome of a mixin changing text color within the browser or highlight padding and margins resulting from applying a token.

The system’s build process compiles SCSS files from within the doc-site/styles folder and subfolders. If you add a new .scss file to this folder, include an @import reference to that file within the doc-site/styles/mds_doc.scss file to ensure the result is included in the compiled _site/latest/styles/mds_doc.css file.

Link Template