Quickstart Guide to Creating Component Documentation

Creating the markdown file (filename.md)#

The following steps use the Component Template as a base to start from but can be edited to use for any file (e.g. Global Pattern documentation or a Design Decision).

Steps#

  1. Select the pen tool and copy the component template and paste into a markdown editor like https://typora.io/.

    For more information about how to write markdown here are some useful links:

  2. Enter in your content following the template format.

    • If you want to use live demos from Storybook, leave import { Storybook} from "@site/util"; at the top of the file, delete if not.

  3. Adding Storybook Demos (links) to Your File (using empty component as an example)

    • Storybook Story Link - Size

      <Storybook height="XXXpx" path="/story/iqmetrix-antd-data-display-empty--empty-component-on-a-page" />

    Figure out your height by clicking the “Preview tab” at the top of your file and adjust accordingly.

    • Storybook Story Link - Address

    Link to a Storybook story by copy & pasting the storybook URL after storybook?path=, for example: path="/story/iqmetrix-antd-data-display-empty--empty-component-on-a-page".

    • Storybook No Story

    Use the markdown link syntax with relevant URL address: [Preview example in Storybook](/storybook?path="/story/iqmetrix-antd-data-display-empty--empty-component-on-a-page").

  4. Adding Links to Your File

    • Use square brackets [] for the title of the link.
    • Round brackets () for the relative link location:
      Within the same folder `(./file.md)`. Eg. from docs>components>alert to docs>components>status = (./alert.md)
    • For other folders, it depends on which folder your current doc is in - a relative path refers to a location that is relative to a current directory. Relative paths make use of two special symbols, a dot (.) and a double-dot (..), which translate into the current directory and the parent directory. Double dots are used for moving up in the hierarchy. A single dot represents the current directory itself.
    • When trouble-shooting relative link errors, review resolved as to see where path corrections are needed. See example below.
      -> linking to ../../empty.md (resolved as: /docs/empty.md) the path should be: /docs/components/empty.md, therefore should be written as: ../../components/empty.md
    • Use # if you wish to link to a specific heading within the same document - eg. [example](#specific-heading).

Add a New File to a Page in GitHub (open a pull request)#

Using the markdown (md) file you just created, add it to the page you want in Design System Docs using GitHub. The following steps will result in the creation of a Pull Request(PR).

Steps#

  1. In the Code tab on the master branch:

    • Click docs folder > folder name (these folders refer to what appears on the design system navigation).
    • Click Create new file tab (first tab, upper right side of the folder page).
    • Click on input field and name your file, e.g. empty-state.md file. * note name can’t have spaces, use a dash for spaces. If you are creating a file.md before you have created the navigation (sidebar.js) it is possible to add the path with a / e.g. /new-folder/new-file.md.
    • Paste md file and preview.

  2. Commit the new file

    • This will create your branch which you should rename to make sense for you and others.
    • Make sure to write a short summary or name the commit appropriately and open a pull request.

  3. Add a list of the actions you are adding to this PR

    • In the text box under description for your Open Pull Request.
    • Include a link to relevent work items eg. devops tickets, github issues, design decisions etc.

  4. Add any related files before clicking create pull request button

    • Add files for this pull request only. Otherwise, automated tests may fail.
    • Select only if you are ready to publish your file and have your work reviewed.

A related file can be anything from a whole file (e.g. /sidebar.js or /create.md) to minor changes within a file (/update.md).

Examples of related files are:

  • Sidebar (navigation) folders Create a Sidebar Category/Item - use when a category or item (ids) don't exist yet.
  • Updating links or or content within a file/page - [Changing a File](#Changing a File).

  1. To add new files to your OPEN PR:

    • Ensure that you have selected the branch that is associated with the open PR.
    • Select the folder for the new file.
    • Click Create new file.
    • Add file-name.md and content (don’t forget to add .md to your file name).
    • Click Commit new file and your related file will be added as a commit to your open PR.

  2. Click Create pull request

    • This means you are ready to publish and have your work reviewed.

Deleting a Pull Request#

You've just created a Pull Request and it's all wrong or you created a test PR, don't be scared, you can always delete PR's and branches but only delete the branch if you are sure you don't need it, e.g. a test branch/PR.

Steps#

  1. On your created pull request scroll down and click Close pull request.
  2. Then clickDelete branch.

Changing a File#

If you wish to make a change on a merged or open PR here are the steps:

Steps#

  1. For a merged PR skip to step two; for an open PR, select the appropriate branch from the home page.
  2. Go to the folder>page you wish to make changes to e.g. iQ.design.system.docs/docs/language-and-design/data-entry.md.
  3. Click the pen to edit and
  4. If you have an open PR then make sure you have selected the same branch for which to Commit the changes (don’t create a new branch).
  5. Don't forget to test your links (see Checklist items under [Add a New File to a Page in GitHub](#Add a New File to a Page in GitHub (open a pull request))) .
  6. Click Create pull request - this will add this as a commit to the branch and open PR if you have specified.
Edit this page
Last updated on by Larissa Hsia