Skip to main content

Contributing to Documentation

In this section, we will learn how to contribute to the documentation website (atlas.adjust.com) of the Atlas design system.

Make sure that you are familiar with Markdown and the concepts of version control systems (specifically Git).

If you are not familiar with Git command-line interface (CLI), you can also use GitHub user interface for editing documentation files. Follow the Hello World guide from GitHub to learn how this can be done (skip the first step "Create a Repository").

Markdown + React​

For documenting the Atlas design system we use MDX. MDX provides an integration of React components (using JSX) with Markdown for a better collaboration between designers and developers. If you want to read more about MDX go to https://mdxjs.com/

All of the documentation pages are located in packages/docusaurus/docs and currently consist of four sections: Foundation, Components, Design Tokens, Patterns and Contributing.

Markdown headers​

Every documentation file should contain markdown headers:

---
id: design_principles
title: Principles
---

These are markdown headers used by Docusaurus. Every header serves a special function for Docusaurus. Find more info on the headers here.

tip

If the sidebar label is different from the page title you can use the sidebar_label markdown header to specify the label in the sidebar.

To make the documentantion file available in the sidebar you need to edit atlas/packages/docusaurus/sidebars.js. It contains configuration info for the sidebars.

module.exports = {
  foundation: [
    'foundation/introduction',
    {
      type: 'category',
      label: 'Design Language',
      collapsed: false,
      items: [
        'foundation/design-language/introduction',
        'foundation/design-principles'
      ]
    }
  ]
  components: [
    {
      type: 'doc',
      id: 'components/introduction'
    }
  ]
};

The above configuration would result in a following sidebar for the category foundation:

Docusaurus Sidebar

Choose the appropriate category in the sidebar object depending on what section in the sidebar your file should appear. To learn more about sidebar items check out docusaurus documentation.

Importing an image into documents​

To show an image in your documentation file you should put it to the packages/docusaurus/static/img folder.

Once the image is available you can reference it in your markdown files like this:

Your wonderful markdown content.

![image title that's shown on hover](/img/your_image_name.png)

Have a nice day!

Advanced markdown features​

Docusarus provides an extensive list of markdown features for our disposal. Make sure to check them out: Docusaurus markdown features.