If you're here to contribute do check out our Contributing Guidelines & our Code of Conduct

🚀 Getting Started

🔥 Blazing Fast 100ms Docs

To run locally

• git clone https://github.com/100mslive/100ms-docs.git
• yarn or npm install
• yarn dev or npm run dev

All docs are written in MDX. This allows usage of React components along with the flavor of Markdown Syntax.

All docs reside in the /docs folder.

📒 Adding Docs

1. To an existing Doc

Suppose you want to add a new section VUE SDK in /v2 docs:

• Create a Folder inside /v2/vue-sdk
• Folder name would be capitalised and "-" would be replaced with space for the section header

To add docs in the section:

• Create .mdx files in v2/vue-sdk/file-name.mdx
• Avoid decimal numbers (For example v-1.3.2.mdx) in filename (doesn't cause any loss)
• Avoid adding ampersand / & in filenames as it breaks Sitemaps generation
• It's important to add FrontMatter to the MDX File on top

FrontMatter

Every .mdx file would need this

---
title: Getting started in Vue JS // this will be SEO Title
nav: 14 // Ranking of Item in the Sidebar
---

By default Nav is given the value of Infinity it's important to add nav value to order the Sidebar.

But suppose you want to update the order of a doc , then you don't need to change the nav values for all of them. Simply make the nav value in between the preceding and next doc. It can be a decimal value too.

2. To a new Docs (for v3 and soo on)

Suppose we now need a v3 docs

• Create a folder /docs/v3
• Create a file in /pages/v3/index.tsx

in the file add the following

import redirect from '@/lib/redirect';

export default redirect('/v3/100ms-v3/basics');

This is needed because we need it to route somewhere if someone hits /v3 this would redirect it to /v3/100ms-v3/basics i.e the MDX file /v3/100ms-v3/basics.mdx

Then follow the steps in 1 to add docs to it.

3. Aliasing Repeating Content

So you don't have to copy paste common content multiple times.

1. Create a new file with a .md extension e.g common/test.md and add your Markdown content or a file with .mdx extension e.g common/test.mdx if you want to embed JSX inside it (make sure to escape these characters <>{} with backslash or use backtick if it's a code snippet if you don't want it to be parsed as JSX).
2. Import it at the top of the mdx file as a component in PascalCase e.g import Test from '@/common/test.md'
3. Use the component anywhere within the MDX document e.g <Test />

🥵 Components

Components is what makes this docs standout All Components mentioned are auto imported.

Here's some of them:

1. Note Component

• You can easily use this by using > blockquote it will have a default type of white
• To use other types write in this way

> This will be Success Note Component

<Note type='error'>
  Hello this is Error Note Component
</Note>

// or you can use `warning` type

<Note type='warning'>
  Hello this is Warning Note Component
</Note>

Types available: success,warning,error, white

---

2. Code

by default all <code></code> will wrapped around <Code /> component this gives us Copy to Clipboard feature.

---

3. Tabs

<Tabs id="quality-level" items={['Java', 'Kotlin']} />

<Tab id='quality-level-0'>

// Code Block for Java

</Tab>

<Tab id='quality-level-1'>

// Code Block for Kotlin

</Tab>

using the same id as in <Tabs> in the <Tab> component with index is important or it won't work.

---

4. Codesandbox

Super easy just get the id

<Codesandbox id="ue1k4" />

---

✅ Do's

• Use Emojis 😅😂🚀✅🙂🎉😇🌟
• Maintain the Header Order (H1 , H2 , H3 ...)
• Use Language Attributes in Code Blocks for Syntax Highlight
• Use https://tableconvert.com/ to create Markdown Tables

❌ Don't

• Don't use Bold in Header (For example ** ## Don't ** )
• Dont't Keep the File Names with Decimals (For example Don't android-v2.0.0.mdx) instead keep it as title in frontMatter

🎨 Customization

Every style of docs is fully customizable and is fully built with CSS Variables.

All CSS Tokens , Baseline , Reset can be found in theme.css

All CSS Variables prefixed with token control the Syntax Highlighting.

📇 Linting

• Vale testing
  • brew install vale
  • vale sync
  • vale docs/*
• Add tokens in .github/workflows/styles/Vocab/HMSVocab/accept.txt which you want to whitelist during the linting.
• code blocks are already whitelisted. reference: https://www.regextester.com/65535
• Vale extensions
  • VSCode : Vale
  • Android Studio/IntelliJ : Vale-CLI

#️⃣ Viewing updated release versions on local before pushing changes

• To view the updated release version on local after adding changelog, run the following command before starting the local server:
  • yarn updatereleases
  • yarn dev

🙏🏽 Acknowledgement

• Nextjs
• Preact
• Mdx
• next-mdx-remote
• rehype