Writing Quickstart

Writing Content

Writing Quickstart

Learn how to write content

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.

Learn more about Page Meta options for TOC here.

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

While MDX is powerful, xyd makes writing docs much easier using markdown special symbols.

But you can still use pure MDX or both if you want.

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).
:::

You can also use MDX version of the same component.

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

Info

(tab=cli) means that &tab=cli is added to the URL.

TablesExperimental

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

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

You can still use GFM version of tables too.

Including Content

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

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

Tip

You can include .mdx files too, check out React Components guide.

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

Creating a reusable component:
my-component.mdx
Hello, this is my reusable component

Now, you can use it in your MDX files:

my-content.mdx

import MyComponent from './my-component'

<MyComponent />

Reusable variablesComing Soon

You can also use MDX for reusable variables, by exporting data from your MDX files:
reusable-variables.mdx
export const title = 'Getting Starte';

export const data = { category: "fantasy" };

Now, you can use it in your MDX files:

my-content.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

You can also add variables that can be filled in via props when you import the file:
component-variables.mdx
My favourite favurite book's category is {category}

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.

Edit page

Special Symbols Developer Content