Contributing to Docs

Markdown#

All of our documentation is written in markdown styling. Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.

For more information about how to write a markdown document, check this getting started guide

Adding Content#

Adding a new docs page#

  1. Create the doc as a new markdown file (.md) into /docs, example docs/newly-created-doc.md:

    ---
    id: newly-created-doc
    title: This Doc Needs To Be Edited
    ---
    My new content here..
    ## A heading
    More content with a [link](http://hub.iqmetrix.net)
    And creating a [relative link to another page](./help.md)
  2. The id will be the same name as the file, and the title should follow the Pascal Case Structure (the first letter of each word will be uppercase). The title will be automatically converted to an h1 html element.

  3. Internal links should link to the file and not the web link. This means the links will be relative (adding the ./ or ../ to navigate), and they will include the file extension (.md, for example. This is to avoid the issue when docusaurus cannot locate the link and also create a navigable repository (you can click through the link in the repository itself and not only in the docusaurus website)

Adding custom pages#

Docusaurus uses React components to build pages. The components are saved as .js files in src/pages: For more information about custom pages, check the docusaurus documentation.

Adding items to the navigation bar and to the sidebar#

Adding items to your site's sidebar#

  1. The site bar is configured in the sidebar.js file. It is an object with multiple items. Each item will represent a different sidebar. For example, you can find some items there like developer_menu or help_menu. Inside of each menu, you will see the sidebar menu structure with the items section titles and their menu items.

  2. To add a new item into an existing section, you just need to add the path for this item into the section items array.

    // Add newly-created-doc to the Getting Started category of docs
    {
    ...
    "help_menu": {
    "Getting Started": [
    "quick-start",
    "newly-created-doc" // new doc here
    ],
    ...
    },
    ...
    }
  3. You can add new categories or new sub-categories for your menu items. For more information about adding new entries into the sidebar, check the Docusaurus Sidebard Documentation

Adding items to your site's top navigation bar#

  1. Add links to docs, custom pages or external links by editing the navbar/links field of docusaurus.config.js. For example, if you want to add a link to the docs/newly-created-doc.md:

    // Add newly-created-doc to the Getting Started category of docs
    {
    themeConfig: {
    ...
    navbar: {
    ...
    links: [
    ...
    {
    to: "docs/newly-created-doc",
    label: "Any Text",
    position: "right"
    },
    ...
    ],
    ...
    }
    ...
    }
  2. For more information about the navigation bar, check the Docusaurus NavBard Documentation

Editing an existing docs page#

Edit docs by navigating to docs/ folder and editing the corresponding document. Example when editing docs/doc-to-be-edited.md:

```markdown
---
id: doc-to-be-edited
title: This Doc Needs To Be Edited
---
Edit this doc...
```

Static Assets (images, javascript, and others)#

In general, every website needs assets: images, stylesheets, favicons, etc. In such cases, you will use the directory named static at the root of the repository. Every file you put into that directory will be copied into the root of the generated build folder (website/github pages) with the directory hierarchy preserved. E.g. if you add a file named sun.jpg to the static folder, it’ll be copied to build/sun.jpg.

This means that if the site's baseUrl is /, an image in /static/img/docusaurus_keytar.svg is available at /img/docusaurus_keytar.svg..

For more information, check the Docusaurus Static Assets Documentation.

Markdown Headers#

Normally we will use only id and title. However, there are other options that you can embed inside of the --- wrap.

  • id: A unique document id. If this field is not present, the document's id will default to its file name (without the extension).

  • title: The title of your document. If this field is not present, the document's title will default to its id.

  • hide_title: Whether to hide the title at the top of the doc. By default, it is false.

  • hide_table_of_contents: Whether to hide the table of contents to the right. By default, it is false.

  • sidebar_label: The text is shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's sidebar_label will default to its title.

  • custom_edit_url: The URL for editing this document. If this field is not present, the document's edit URL will fall back to editUrl from options fields passed to docusaurus-plugin-content-docs.

  • keywords: Keywords meta tag for the document page, for search engines.

  • description: The description of your document, which will become the <meta name="description" content="..."/> and <meta property="og:description" content="..."/> in <head>, used by search engines. If this field is not present, it will default to the first line of the contents.

  • image: Cover or thumbnail image that will be used when displaying the link to your post.

    ---
    id: doc-markdown
    title: Markdown Features
    hide_title: false
    hide_table_of_contents: false
    sidebar_label: Markdown :)
    custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
    description: How do I find you when I cannot solve this problem
    keywords:
    - docs
    - docusaurus
    image: https://i.imgur.com/mErPwqL.png
    ---

Embedding React Components#

Docusaurus has built-in support for MDX, which allows you to write JSX within your Markdown files and render them as React components.

Note 1: While both .md and .mdx files are parsed using MDX, some of the syntaxes are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the .mdx extension for files containing MDX syntax. Let's rename the previous file to greeting.mdx.

Note 2: Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavour and provide style objects.

For more information, check the Docusaurus Embedding React Component Documentation.

Using Ant Design components and Storybooks into documentation#

Ant Design Components#

  1. If you want to use a component that is not yet installed into the iQ.design.system.docs, you will need to run the following command:

    yarn add @iqmetrix/component-name

    You can check which components are installed in the package.json file, under dependencies.

  2. Once you are sure that your component is installed, you just need to add the import statement for the components that you need at the beginning of the document, right after the --- wrap. Example:

    ---
    id: example-page
    title: Example Page
    ---
    import { Card, Button } from "@iqmetrix/antd";
    Your content...

    Ant Design will always be available through @iqmetrix/antd. At this moment, the used version is the antd@4.

  3. Now that you have imported the necessary components, you can use it inside of the content at any moment.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    <Card>
    <Button type='Primary'>Button Primary</Button>
    </Card>
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.

Storybook components#

  1. To embed a storybook component, you will need to use the storybook util though the import statement at the beginning of the document, right after the --- wrap. Example:

    ---
    id: example-page
    title: Example Page
    ---
    import { Storybook } from "@site/util";
    Your content...
    Storybook utility

    The Storybook utility is located in the util folder, at the repository root. To be able to import it successfully, you need to navigate until the root using ../ as many times it is necessary based in the folder structure of the file that you are editing.

  2. Next, you just need to call the util with the storybook url (get it from the storybook page).

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    <Storybook path="/story/iqmetrix-result-result-default-errors--401-403-errors" />
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
  3. You can also set the height of the box for the storybook

    <Storybook height="500px" path="/story/iqmetrix-antd-feedback-result-default-errors--error-403" />
  4. If you want to align the storybook components to the left of your page (instead of centralized), use the alignLeft property.

<Storybook height="300px" alignLeft path="/story/iqmetrix-antd-data-entry--checkbox" />

Creating custom styles and using @iqmetrix/style-tokens#

  1. If you want to use a custom styling or the styling from @iqmetrix/style-tokens, first, you will need to create the CSS file into the /static/css folder. For example, colors.css.

    @import "~@iqmetrix/style-tokens/dist/css/tokens.css";
    .my-class {
    color: var(--color-base-green-darker);
    }
  2. Now, you can embed the CSS created using link as you would do in an html file at the beginning of the document, right after the --- wrap. Example:

    ---
    id: colors
    title: Colors
    ---
    <link rel="stylesheet" type="text/css" href="/css/colors.css" />
    ## Color Palette
    Content...
    <div class="my-class">Your green text</div>
    More content...
    Static Folder

    Remember that all files created under the static folder will be avaliable under the website root. Check the information in the previous documentation.

Callouts/admonitions#

In addition to the basic Markdown syntax, we use remark-admonitions alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons. Example:

:::important Title
Content goes here
:::
Title

Content goes here

Last updated on by Paulo Andrade