Writing Quickstart

Learn how to write documentation content using Markdown, MDX, and xyd's built-in components.

Headers

You can define headers using markdown syntax like:

---
title: My Page Title
---

# My Header

with header subtitle:

---
title: My Page Title
---

# My Header {subtitle="Learn how to use headers"}

alternatively:

# My Header
:::subtitle
Learn how to use headers
:::

with header label:

---
title: My Page Title
---

# My Header {label="Coming Soon"}

Header Anchors

Headers get automatically anchor links applied. If you'd like to set a custom anchor, add an id sugar syntax prop to the heading:

## My custom anchors {#custom-anchors}

This sets the heading anchor to #custom-anchors instead of the default #my-custom-anchors.

ToC Anchors

The table of contents (TOC) will be generated based on headings, you can also customize that:

## Heading [!toc]
This heading will be **HIDDEN* from TOC.

## TOC Heading Only [toc]
This heading will **ONLY** be visible in TOC.
You can use it to add additional TOC items.

## TOC Changed [toc="toc changed"]
It display 'toc changed' in TOC section instead of 'TOC Changed'.
It's visible on the page too.

## TOC Force [+toc]
It adds heading to the TOC despite of `maxTocDepth`. 
It's visible on the page too.

Content

To write a content for your page, you can use the MDX or Markdown syntax. You can also leverage built in components or special symbols to enhance your content:

# Quickstart

This is a quickstart guide for the `xyd` project.

:::callout
Tip: You can use the React `<Callout>` component to render a callout too
:::

Markdown GFM

You can use GFM (GitHub Flavored Markdown) to write your content like this:

# Heading
 
## Heading
 
### Heading
 
#### Heading
 
Hello World, **Bold**, _Italic_, ~~Hidden~~
 
1. First
2. Second
3. Third
 
- Item 1
- Item 2
 
> Quote here
 
![alt](/image.png)
 
| Table | Description |
| ----- | ----------- |
| Hello | World       |

Component Directives

Use markdown directives (:::) to render components in markdown syntax. The full list of components you can find here.

For example you would render components like this:

:::callout
You can also use MDX version of the same [component](/docs/components).
:::

Steps

For creating steps you can use such us syntax:

:::steps
1. My First Steps

2. My Second Step

3. My Third Step
  ```ts
  console.log("You can also add code blocks in steps")
  ```
:::

Tabs

For creating tabs, you can use the following syntax:

:::tabs 
1. [CLI](tab=cli)
    Content for the CLI tab

2. [Code](tab=code)
    Content for the Code tab
:::

TablesExperimental

You can also use CSV-like version of declaring tables with some sugar-syntax:

:::table
```
[
    ["Syntax", "Description", "Markdown"],
    ["Header", "Title", "`#`"],
    ["Paragraph", "Text", "`*`"]
]
```
:::

Including Content

You can use @include function to include another content files in current content:

@include "./relative-to-current-file.md"

Emojis 🎉

For declaring just copy and paste the emoji you want to use in your markdown, for example:

🔥

MDXExperimental

MDX combines Markdown with JSX, letting you use React components in your docs.

Reusable componentsComing Soon

1. Creating a reusable component:
   my-component.mdx

   mdx

   Hello, this is my reusable component

   
   
2. Now, you can use it in your MDX files:
   my-content.mdx

   tsx

   import MyComponent from './my-component'
   
   <MyComponent />

Reusable variablesComing Soon

1. You can also use MDX for reusable variables, by exporting data from your MDX files:

   reusable-variables.mdx

   tsx

   export const title = 'Getting Starte';
   
   export const data = { category: "fantasy" };

   
   

2. Now, you can use it in your MDX files:

   my-content.mdx

   mdx

   ---
   title: My title
   description: My Description
   ---
   
   import { title, data } from './reusable-variables';
   
   Hello, my title is {title} and I like {data.category}.

Exporting component variablesComing Soon

1. You can also add variables that can be filled in via props when you import the file:
   component-variables.mdx

   mdx

   My favourite favurite book's category is {category}

   
   
2. And then pass variables as props:
   import MyComponent from './component-variables'
   
   <MyComponent category="fantasy" />

This creates a navigation component with two tabs: "CLI" and "Code", each with its own content. The content for each tab follows the tab definition.