---
title: 'Write guides for Video.js'
description: 'A guide on writing documentation, and a test bed for all our MDX components'
---
import FrameworkCase from '@/components/docs/FrameworkCase.astro';
import StyleCase from '@/components/docs/StyleCase.astro';
import MinimalFrame from '@/components/frames/Minimal.astro';
import ServerCode from '@/components/Code/ServerCode.astro';
import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs.tsx';
import DocsLink from '@/components/docs/DocsLink.astro';
import Aside from '@/components/Aside.astro';
What is a guide? In this context, it's a document in the docs that's not an API reference. For API references, see Write reference pages.
## 1. Understand our documentation structure
First, read and understand [Diátaxis](https://diataxis.fr/). We organize documentation into three modes:
1. **Concept pages** (`src/content/docs/concepts/`): Explain how and why things work. General understanding, spanning multiple APIs, can be applied to multiple outcomes. As we write guides, what are things we need people to understand in multiple places and don’t want to duplicate the content?
2. **How-to guides** (`src/content/docs/how-to/`): Spans multiple concepts in order to achieve a specific outcome with step-by-step instructions.
3. **Reference pages** (`src/content/docs/reference/`): Component API documentation. These are scaffolded using the `api-reference` skill and the api-docs-builder. Again, see Write reference pages for details.
When in doubt, you probably want a concept page.
## 2. Create a guide in the correct content folder
Our guides are [MDX](https://mdxjs.com) files placed in the matching directory:
- Concept pages go in `src/content/docs/concepts/[slug].mdx`
- How-to guides go in `src/content/docs/how-to/[slug].mdx`
## 3. Add that guide to the sidebar
Next, open `src/docs.config.ts` and add your guide to the appropriate section of the sidebar. For example, to add a how-to guide on "Writing guides", you would add:
```ts
{
slug: 'how-to/write-guides',
title: 'Writing guides'
}
```
If you want the guide to only apply to specific frameworks or styles, you can specify those as well:
```ts
{
slug: 'how-to/write-guides',
title: 'Writing guides',
frameworks: ['react'], // Only for React
styles: ['css'] // Only for CSS
}
```
## 4. Follow our writing style
Keep documentation clear, human, and useful. Here are the key rules:
- **Sentence case for headings** — capitalize only the first word and proper nouns (e.g., "Choose your JS framework", not "Choose Your JS Framework")
- **Active voice, second person** — speak directly to the reader with "you"
- **Collaborative pronouns** — use "we," "us," and "our" when talking about the project or team
- **Avoid gerunds in headings** — prefer "Write good headings" over "Writing good headings"
- **Oxford comma** — always use the serial comma in lists of three or more
- **Gender-neutral language** — use "they" or "their" instead of "his" or "her"
- **Cut filler words** — remove "In order to," "basically," "simply," "might," "could," "perhaps"
- **Be precise** — make claims as strong as possible without becoming false; avoid vague qualifiers like "somewhat" or "fairly"
- **Read it out loud** — if it sounds awkward, rewrite it
## 5. Understand MDX and our components
### `` and ``
First, understand that the guide you write will be rendered for every framework / style combination (e.g., HTML + CSS, React + CSS) unless you restrict it in the sidebar config as shown above.
Use the `` and `` components to conditionally show content to just one framework or style:
```mdx
React-only content
```
React-only content
Use the `` component to show content only for specific styling approaches. For example,
```mdx
CSS-only content
```
CSS-only content
## Use Github-Flavored Markdown
### Headings
Don't use H1 (or in markdown, `# H1`). We already have an H1 at the top of the page. Do, however, check out H2 (`## H2`) through H6 (`###### H6`).
## H2 with `code`
### H3 with `code`
#### H4 with `code`
##### H5 with `code`
###### H6 with `code`
### Paragraph
Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.
Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.
### Images
```mdx
```
### Blockquotes
The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a `footer` or `cite` element, and optionally with in-line changes such as annotations and abbreviations.
```markdown
> Tiam, ad mint andaepu dandae nostion secatur sequo quae.
> **Note** that you can use _Markdown syntax_ within a blockquote.
```
> Tiam, ad mint andaepu dandae nostion secatur sequo quae.
> **Note** that you can use _Markdown syntax_ within a blockquote.
### Footnotes
```markdown
> Don't communicate by sharing memory, share memory by communicating.
> — Rob Pike[^1]
```
> Don't communicate by sharing memory, share memory by communicating.
> — Rob Pike[^1]
[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
### Tables
```markdown
| Italics | Bold | Code |
| --------- | -------- | ------ |
| _italics_ | **bold** | `code` |
```
| Italics | Bold | Code |
| --------- | -------- | ------ |
| _italics_ | **bold** | `code` |
When a table is really wide, it overflows nicely on mobile
| A | Table | With | A | Lot | Of | Columns |
| --- | --- | --- | --- | --- | --- | --- |
| contentcontentcontent | contentcontentcontent | contentcontentcontent | contentcontentcontent | contentcontentcontent | contentcontentcontent | contentcontentcontent |
### Code blocks
we can use 3 backticks ``` in new line and write snippet and close with 3 backticks on new line and to highlight language specific syntax, write one word of language name after first 3 backticks, for eg. html, javascript, css, markdown, typescript, txt, bash
````markdown
```html
Example HTML5 Document
Test
```
````
```html
Example HTML5 Document
Test
```
### List types
#### Ordered list
```markdown
1. First item
2. Second item
3. Third item
```
1. First item
2. Second item
3. Third item
#### Unordered list
```markdown
- List item
- Another item
- And another item
```
- List item
- Another item
- And another item
#### Nested list
```markdown
- Fruit
- Apple
- Orange
- Banana
- Dairy
- Milk
- Cheese
```
Which looks like:
- Fruit
- Apple
- Orange
- Banana
- Dairy
- Milk
- Cheese
### HTML elements, like abbr, sub, sup, kbd, mark
You can also write raw HTML within your markdown. This is useful for elements like...
```markdown
GIF is a bitmap image format.
H2O
Xn + Yn = Zn
Press CTRL + ALT + Delete to end the session.
Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.
```
Which would output:
GIF is a bitmap image format.
H2O
Xn + Yn = Zn
Press CTRL + ALT + Delete to end the session.
Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.
## Other custom components
### Asides / Callouts / Admonitions
Use the `