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 "doc_templates/toc.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.

/src
  /doc
    /about
    /components
    /resources
    /ux-patterns
    /visual-language

For example, to publish a page titled Publishing Documentation in the Resources section, save the publishing-documentation.njk file in the src/doc/resources/ folder.

Step 2: Choose a Template

The system offers a limited number of preset layouts to include navigation, style, and at times custom scripting. Identify the template near the top of the text file using the extends tag:

{% extends "doc_templates/toc.njk" %}
Template Use when

doc.template.njk

Rendering a basic layout wrapped in the site’s shell and main navigation.

toc.doc.template.njk

Rendering a page with local navigation on the right to serve as a table of contents of the individual page.

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 src/doc/data/content.json file.

To add a page to the navigation, add an entry 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 src/doc/assets/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/assets/images/visual-language/color/ directory, and reference that image within markdown as:

![Example alt text](/assets/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.

/src/doc/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.

/src/doc/components/buttons.njk

HTML example list

Displaying 1+ examples rendered in HTML without any corresponding code snippet(s).

/src/doc/visual-language/space.njk

For Guidelines

Component Use when Example

Do & don’t

Displaying 1+ blocks of image & Do or Don’t text paired together and styled green or red, respectively.

/src/doc/components/buttons.njk

Reference table

Displaying multi-column tables of code references and examples. For custom column headers, include a headersarray as a parameter.

/src/doc/components/buttons.njk

Constants table

Displaying all constants at a node of the constants hierarchy. Include sub-nodes by setting include_subconstants=true.

/src/doc/visual-language/constants.njk

For Visual Style

Component Use when Example

Hex

Displaying a hex value in a code pill with an associated color swatch.

/src/doc/visual-language/constants.njk

Icon swatch

Displaying an icon in a grid.

/src/doc/visual-language/iconography.njk

Tint stack

Displaying a stack of related color tints.

/src/doc/visual-language/color.njk

Type swatch

Displaying a stack of related type specimens.

/src/doc/visual-language/typography.njk

Documentation Components to Avoid

Component Rationale

Long Form Text

Intended for laying out text within the documentation site wrapped in {% filter markdown %}{% endfilter %} tags.

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 src/doc/assets/styles/ folder and subfolders. If you add a new .scss file to this folder, include an @import reference to that file within the src/doc/assets/styles/mds_doc.scss file to ensure the result is included in the compiled /assets/styles/mds_doc.css file.

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