v10/site/src/content/docs/how-to/write-guides.mdx

---
title: 'Writing guides for Video.js'
description: 'A guide on writing documentation for the Video.js project, and a test bed for all our MDX components'
---

import FrameworkCase from '@/components/docs/FrameworkCase.astro';
import StyleCase from '@/components/docs/StyleCase.astro';
import Minimal 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 kind of guide are you writing?
I haven't written this section yet, but when I do, it'll rehash [Diátaxis](https://diataxis.fr/).

## Framework-Specific Content

Use the `<FrameworkCase>` component to show content only for specific frameworks. For example,
```mdx
<FrameworkCase frameworks={["react"]}>
  React-only content
</FrameworkCase>
```

will render:

<FrameworkCase frameworks={["react"]}>
  React-only content
</FrameworkCase>


## Style-Specific Content

Use the `<StyleCase>` component to show content only for specific styling approaches. For example,

```mdx
<StyleCase styles={["css"]}>
  Css-only content
</StyleCase>  
``` 

will render:

<StyleCase styles={["css"]}>
  Css-only content
</StyleCase>

## 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

We don't actually support images yet, lol.

### 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.

#### Blockquote without attribution

##### Syntax

```markdown
> Tiam, ad mint andaepu dandae nostion secatur sequo quae.
> **Note** that you can use _Markdown syntax_ within a blockquote.
```

##### Output

> Tiam, ad mint andaepu dandae nostion secatur sequo quae.
> **Note** that you can use _Markdown syntax_ within a blockquote.

#### Blockquote with attribution

##### Syntax

```markdown
> Don't communicate by sharing memory, share memory by communicating.<br/>
> — <cite>Rob Pike[^1]</cite>
```

##### Output

> Don't communicate by sharing memory, share memory by communicating.<br/>
> — <cite>Rob Pike[^1]</cite>

[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.

### Tables

#### Syntax

```markdown
| Italics   | Bold     | Code   |
| --------- | -------- | ------ |
| _italics_ | **bold** | `code` |
```

#### Output

| Italics   | Bold     | Code   |
| --------- | -------- | ------ |
| _italics_ | **bold** | `code` |

### Code Blocks

#### Syntax

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
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example HTML5 Document</title>
  </head>
  <body>
    <p>Test</p>
  </body>
</html>
```
````

#### Output

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example HTML5 Document</title>
  </head>
  <body>
    <p>Test</p>
  </body>
</html>
```

### List Types

#### Ordered List

##### Syntax

```markdown
1. First item
2. Second item
3. Third item
```

##### Output

1. First item
2. Second item
3. Third item

#### Unordered List

##### Syntax

```markdown
- List item
- Another item
- And another item
```

##### Output

- List item
- Another item
- And another item

#### Nested list

##### Syntax

```markdown
- Fruit
  - Apple
  - Orange
  - Banana
- Dairy
  - Milk
  - Cheese
```

##### Output

- Fruit
  - Apple
  - Orange
  - Banana
- Dairy
  - Milk
  - Cheese

### Other Elements — abbr, sub, sup, kbd, mark

#### Syntax

```markdown
<abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.

H<sub>2</sub>O

X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>

Press <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> to end the session.

Most <mark>salamanders</mark> are nocturnal, and hunt for insects, worms, and other small creatures.
```

#### Output

<abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.

H<sub>2</sub>O

X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>

Press <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> to end the session.

Most <mark>salamanders</mark> are nocturnal, and hunt for insects, worms, and other small creatures.

## Asides / Callouts / Admonitions

Use the `<Aside>` component to highlight important information. It supports four types: `note`, `tip`, `caution`, and `danger`.

```mdx
{/* or type="tip" or "caution" or "danger" */}
<Aside type="note" title="Custom Title">
Your content. You can use **markdown** in here, too.
</Aside>
```

Which will give you...

<Aside type="note" title="Custom Title">
Your content. You can use **markdown** in here, too.
</Aside>

<Aside type="tip">
Your content. You can use **markdown** in here, too.
</Aside>

<Aside type="caution">
Your content. You can use **markdown** in here, too.
</Aside>

<Aside type="danger">
Of course it works with longer content as well. Even things that have multiple elements!

The elements have a gross Tailwind class that manages their margins which makes them tighter in this context. Neat!
</Aside>

## Code and Code Frames

### Default frame

Regular markdown code blocks automatically get wrapped in tabs with a copy button:

````markdown
```ts
console.log('Hello, TypeScript!');
```
````
Renders
```ts
console.log('Hello, TypeScript!');
```

### Tabs

Use `<TabsRoot>`, `<Tab>`, and `<TabsPanel>` to show multiple code examples side-by-side:

````mdx
<TabsRoot client:load>
  <TabsList client:load label="Code examples">
    <Tab client:load value="typescript" initial>TypeScript</Tab>
    <Tab client:load value="javascript">JavaScript</Tab>
  </TabsList>
  <TabsPanel client:load value="typescript" initial>
    ```ts
    console.log('Hello, TypeScript!');
    ```
  </TabsPanel>
  <TabsPanel client:load value="javascript">
    ```js
    console.log('Hello, JavaScript!');
    ```
  </TabsPanel>
</TabsRoot>
````
Which renders
<TabsRoot client:load>
  <TabsList client:load label="Code examples">
    <Tab client:load value="typescript" initial>TypeScript</Tab>
    <Tab client:load value="javascript">JavaScript</Tab>
  </TabsList>
  <TabsPanel client:load value="typescript" initial>
    ```ts
    console.log('Hello, TypeScript!');
    ```
  </TabsPanel>
  <TabsPanel client:load value="javascript">
    ```js
    console.log('Hello, JavaScript!');
    ```
  </TabsPanel>
</TabsRoot>

**Important notes:**
- Use `<TabsList>` to wrap Tab components, and place TabsPanel components directly as children of TabsRoot
- Set `initial` on the first Tab and first TabsPanel to make them active by default
- All child components (`TabsList`, `Tab`, `TabsPanel`) require `client:load` directive in MDX
- Use descriptive `label` prop on TabsList for accessibility


## Displaying Code from Files

Use the `<ServerCode>` component to display code imported from source files with syntax highlighting. Supports any language that [Shiki supports](https://shiki.style/languages).

**Important:** Unlike regular markdown code blocks, `<ServerCode>` does **not** automatically get wrapped in a frame. You should use `TabsRoot` with a single `TabPanel` to make it look pretty

```mdx
import componentCode from '@/examples/react/Component.tsx?raw';
import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs';
import ServerCode from '@/components/Code/ServerCode.astro';

<TabsRoot client:load>
  <TabsList client:load label="Component implementation">
    <Tab client:load value="component" initial>Component</Tab>
  </TabsList>
  <TabsPanel client:load value="component" initial>
    <ServerCode code={componentCode} lang="tsx" />
  </TabsPanel>
</TabsRoot>
```

Which will happily render

<TabsRoot client:load>
  <TabsList client:load label="Component implementation">
    <Tab client:load value="component" initial>Component</Tab>
  </TabsList>
  <TabsPanel client:load value="component" initial>
    <ServerCode code={`import React from 'react';

function Component() {
  return <div>Hello, world!</div>;
}`} lang="tsx" />
  </TabsPanel>
</TabsRoot>

## Wrapping Live Demos

There are two main patterns for displaying live demos, depending on whether you want to show code alongside the demo.

### Option 1: Standalone Demo with Minimal Frame

Use the `<MinimalFrame>` frame component to wrap standalone demos with a styled border and background:

```mdx
import { MyDemo } from '@/examples/react/MyDemo';
import MinimalFrame from '@/components/frames/Minimal.astro';
<MinimalFrame>
  <MyDemo client:load />
</MinimalFrame>
```

This is best for demos that don't need accompanying code, or when the code is shown separately elsewhere on the page.

### Option 2: Demo with Code in TabsRoot

Place the demo directly inside the `tabs-panels` Fragment (as a sibling to `<TabsPanel>` elements) to keep code and demo together:

```mdx
import { MyDemo } from '@/examples/react/MyDemo';
import componentCode from '@/examples/react/MyDemo.tsx?raw';
import cssCode from '@/examples/react/MyDemo.module.css?raw';
import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs';
import ServerCode from '@/components/Code/ServerCode.astro';

<TabsRoot client:load>
  <TabsList client:load label="MyDemo implementation">
    <Tab client:load value="component" initial>Component</Tab>
    <Tab client:load value="css">CSS Module</Tab>
  </TabsList>
  <TabsPanel client:load value="component" initial>
    <ServerCode code={componentCode} lang="tsx" />
  </TabsPanel>
  <TabsPanel client:load value="css">
    <ServerCode code={cssCode} lang="css" />
  </TabsPanel>
  <MyDemo client:load />
</TabsRoot>
```

The demo will appear at the bottom of the tabs component, creating a cohesive unit of code and preview. This pattern is used throughout our resource documentation (see <DocsLink slug="reference/play-button">PlayButton</DocsLink> for an example).