Skip to main content

Contributing

Our docs supports standard Markdown and a few additional features. In order to contribute effectively we've created this little Markdown cheat sheet.

Basic Markdown Elements​

Here are some of the basic and most common Markdown elements. Markdown also supports writing any HTML element so if you know HTML you can include those as well.

Headers​

An H1 Header

# An H1 Header

An H2 Header​

## An H2 Header

An H3 Header​

### An H3 Header

An H4 Header​

#### An H4 Header
An H5 Header​
##### An H5 Header

Text Formatting​

This is some bold text.

This is some **bold** text.

This is some italic text.

This is some _italic_ text.

This is some strike through text.

This is some ~~strike through~~ text.

Quotes​

This is some quoted text.

> This is some quoted text.
tip

We also have special types of quotes called Admonitions. These aren't standard Markdown but are awesome. Please use them where appropriate.

Code Blocks​

Inline​

Here is an inline code block.

Here is an `inline code block`.

Multi-line​

A multi-line codeblock is done by add 3 backticks (```) followed by your multi-line content and then another 3 backticks (```).

{
  "type": "multi-line code block"
}
tip

You can also add syntax highlighting to multi-line code blocks by putting the file extension name like md or js or json after the firs 3 back ticks (```md).

Lists​

Unordered Lists​

  • Apples
    • red
    • green
  • Oranges
  • Bananas
- Apples
    - red
    - green
- Oranges
- Bananas

Ordered Lists​

  1. Apples
    1. red
    2. green
  2. Oranges
  3. Bananas
1. Apples
    1. red
    2. green
2. Oranges
3. Bananas

Task Lists​

  • Write the press release
  • Update the website
  • Contact the media
- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

Regular Markdown links are supported, using url paths or relative file paths. So you can link to other pages by their URL or their filename.

You can link to other pages by [their URL](/commerce-sdk/) or [their filename](./commerce-sdk/readme.md).
caution

Please link by filename whenever possible as that ensures that links in the raw Github format function correctly as well.

You can also link to external links, which will open in a new tab automatically. Visit Google

[Visit Google](https://google.com)

You can also link to a header section on the same page or even on a different page.

You can also link to a header section on [the same page](#admonitions) or even on [a different page](./commerce-sdk/readme.md#making-request).
caution

Links to header sections need to be all lowercase and -'s need to be replaced by spaces for them to work properly.

Images​

Regular Markdown images are supported.

Add an image at static/images/logo.png and display it in Markdown:

![Bidali logo](/images/logo.png)

Bidali logo

Code Blocks​

Markdown code blocks are supported with Syntax highlighting.

```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
    return (
        <h1>Hello, Docusaurus!</h1>
    )
}
```
src/components/HelloDocusaurus.js
function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}

Tables​

Column AColumn B
Apples2
Orange3
|  Column A  |  Column B  |
|: -------- :|: -------- :|
| Apples | 2 |
| Orange | 3 |

Footnotes​

Here's a sentence with a footnote. 1

Here's a sentence with a footnote. [^1]

[^1]: This is the footnote.

Horizontal Rule/Page Break​

---

Additional Components​

Front Matter​

Markdown documents have metadata at the top called Front Matter that is used by the build system to organize the documents and make them web friendly.

my-doc.md
---
id: my-doc-id                 -> file name
title: A title                -> a title used for SEO and bookmarks
description: A description    -> a description used for SEO
sidebar_position: 1           -> position in the side navigation
slug: /my-custom-url          -> allows you to customize the URL
---

## Markdown heading

Markdown text with [links](./hello.md)

Admonitions​

Admonitions should be used to bring special attention to things.

note

Some content with markdown syntax. Check this api.

tip

Some content with markdown syntax. Check this api.

info

Some content with markdown syntax. Check this api.

caution

Some content with markdown syntax. Check this api.

danger

Some content with markdown syntax. Check this api.

:::note
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::

:::tip
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::

:::info
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::

:::caution
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::

:::danger
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::

MDX and React Components​

MDX can make your documentation more interactive and allows using any React components inside Markdown:

This is a green highlight!

This is a blue highlight!

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !
  1. This is the footnote.↩