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." %}

Step 5: Add to Site Navigation

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 headersarray 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.

©2018 Morningstar, Inc. All rights reserved. Terms of Use