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).
#
StepsSelect 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:
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.
- If you want to use live demos from Storybook, leave
Adding Storybook Demos (links) to Your File (using empty component as an example)
Storybook Story Link - Size
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")
.Adding Links to Your File
- Use square brackets
[]
for the title of the link. - Round brackets
()
for the relative link location: - 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. - Use
#
if you wish to link to a specific heading within the same document - eg.[example](#specific-heading)
.
- Use square brackets
#
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)
.
#
StepsIn the
Code
tab on themaster 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 afile.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.
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.
- This will create your
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.
Add
any related files before clickingcreate 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).
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 yourrelated
file will be added as acommit
to your open PR.
Click
Create pull request
- This means you are ready to publish and have your work reviewed.
#
Deleting a Pull RequestYou'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- On your
created
pull request scroll down andclick
Close pull request. - Then
click
Delete branch.
#
Changing a FileIf you wish to make a change on a merged or open PR here are the steps:
#
Steps- For a merged PR skip to step two; for an open PR, select the appropriate branch from the home page.
- Go to the folder>page you wish to make changes to e.g. iQ.design.system.docs/docs/language-and-design/data-entry.md.
- Click the
pen
to edit and - 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). - 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))) .
- Click
Create pull request
- this will add this as acommit
to the branch and open PR if you have specified.