Contributing to Docs
#
MarkdownAll 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 pageCreate the doc as a new markdown file (.md) into
/docs
, exampledocs/newly-created-doc.md
:The
id
will be the same name as the file, and thetitle
should follow the Pascal Case Structure (the first letter of each word will be uppercase). Thetitle
will be automatically converted to anh1
html element.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 pagesDocusaurus 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 sidebarThe 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 likedeveloper_menu
orhelp_menu
. Inside of each menu, you will see the sidebar menu structure with the items section titles and their menu items.To add a new item into an existing section, you just need to add the path for this item into the section items array.
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 barAdd links to docs, custom pages or external links by editing the
navbar/links
field ofdocusaurus.config.js
. For example, if you want to add a link to thedocs/newly-created-doc.md
:For more information about the navigation bar, check the Docusaurus NavBard Documentation
#
Editing an existing docs pageEdit docs by navigating to docs/ folder and editing the corresponding document. Example when editing docs/doc-to-be-edited.md
:
#
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 HeadersNormally 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'sid
will default to its file name (without the extension).title
: The title of your document. If this field is not present, the document'stitle
will default to itsid
.hide_title
: Whether to hide the title at the top of the doc. By default, it isfalse
.hide_table_of_contents
: Whether to hide the table of contents to the right. By default, it isfalse
.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'ssidebar_label
will default to itstitle
.custom_edit_url
: The URL for editing this document. If this field is not present, the document's edit URL will fall back toeditUrl
from options fields passed todocusaurus-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.
#
Embedding React ComponentsDocusaurus 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 ComponentsIf 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:
You can check which components are installed in the package.json file, under
dependencies
.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:Ant Design will always be available through
@iqmetrix/antd
. At this moment, the used version is theantd@4
.Now that you have imported the necessary components, you can use it inside of the content at any moment.
#
Storybook componentsTo 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:Storybook utility
The
Storybook
utility is located in theutil
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.Next, you just need to call the util with the storybook url (get it from the storybook page).
You can also set the height of the box for the storybook
If you want to align the storybook components to the left of your page (instead of centralized), use the
alignLeft
property.
@iqmetrix/style-tokens
#
Creating custom styles and using 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
.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: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/admonitionsIn 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:
Title
Content goes here