If you're here to contribute do check out our Contributing Guidelines & our Code of Conduct
π₯ Blazing Fast 100ms Docs
To run locally
git clone https://github.com/100mslive/100ms-docs.git
yarn
ornpm install
yarn dev
ornpm 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.
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
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.
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.
So you don't have to copy paste common content multiple times.
- 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.gcommon/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). - Import it at the top of the mdx file as a component in PascalCase e.g
import Test from '@/common/test.md'
- Use the component anywhere within the MDX document e.g
<Test />
Components is what makes this docs standout All Components mentioned are auto imported.
Here's some of them:
- You can easily use this by using
> blockquote
it will have a default type ofwhite
- 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
by default all <code></code>
will wrapped around <Code />
component this gives us Copy to Clipboard feature.
<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.
Super easy just get the id
<Codesandbox id="ue1k4" />
- 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 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
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.
- 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
- To view the updated release version on local after adding changelog, run the following command before starting the local server:
yarn updatereleases
yarn dev
- Nextjs
- Preact
- Mdx
- next-mdx-remote
- rehype