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.
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 %}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-languageFor example, to publish a page titled Publishing Documentation in the Resources section, save the publishing-documentation.njk file in the src/doc/resources/ folder.
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 |
|---|---|
|
|
Rendering a basic layout wrapped in the site’s shell and main navigation. |
|
|
Rendering a page with local navigation on the right to serve as a table of contents of the individual page. |
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" %}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"
},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 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 |
|
|
Paragraph |
|
|
Unordered list |
|
|
Ordered list |
|
|
Italic |
|
|
Bold |
|
|
Link |
|
|
Image |
|
|
Code pill |
|
You can find more detailed markdown documentation on sites such as Daring Fireball and Adam P’s Markdown Cheatsheet.
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-languageFor 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:
| Component | Use when | Example |
|---|---|---|
|
Code snippet |
Displaying a code snippet without an associated example rendered in HTML. |
|
|
Example code pair |
Displaying a code snippet following a stack of 1+ rendered examples, where the code snippet corresponds to the first rendered example. |
|
|
HTML example list |
Displaying 1+ examples rendered in HTML without any corresponding code snippet(s). |
|
| 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. |
|
|
Reference table |
Displaying multi-column tables of code references and examples. For custom column headers, include a |
|
|
Constants table |
Displaying all constants at a node of the constants hierarchy. Include sub-nodes by setting |
|
| Component | Use when | Example |
|---|---|---|
|
Hex |
Displaying a hex value in a code pill with an associated color swatch. |
|
|
Icon swatch |
Displaying an icon in a grid. |
|
|
Tint stack |
Displaying a stack of related color tints. |
|
|
Type swatch |
Displaying a stack of related type specimens. |
|
| 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. |
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.