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

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
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`
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`
Image Text Pair	Displaying an image and guidelines side-by-side.	`/src/doc/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.	`/src/doc/components/buttons.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.

Link Template