Markdown

Docgo accepts both .md and .mdx files. The pipeline supports standard Markdown, MDX components, GitHub-Flavored Markdown, Docgo authoring shortcuts and Shiki syntax highlighting.

#Frontmatter

Use YAML frontmatter at the top of a page.

---
title: Getting Started
description: Set up your first Docgo site.
navTitle: Start
order: 2
layout: ''
image: /og/getting-started.png
noindex: false
---

Supported page fields:

#MDX components

MDX lets you render React components inside documentation.

import { Button } from 'bmates-ui';

<Button>Start</Button>

You can also register shared components from config with mdxComponents.

export default defineConfig({
  mdxComponents: {
    Callout({ children }) {
      return <aside>{children}</aside>;
    },
  },
});

#GitHub-Flavored Markdown

Docgo supports GFM tables, strikethrough, task lists, autolinks, and footnotes.

• Task lists
• Remaining work

removed

https://example.com

Footnote reference.¹

| Feature | Status    |
| ------- | --------- |
| Tables  | Supported |

- [x] Task lists
- [ ] Remaining work

~~removed~~

https://example.com

Footnote reference.[^gfm]

[^gfm]: Footnote content.

#Emoji shortcodes

GitHub-style emoji shortcodes are supported.

🚀 🎉 💯

:rocket: :tada: :100:

#Table of contents marker

Use [[toc]] to render an inline table of contents for the current page.

[[toc]]

The inline TOC includes h2 and h3 headings.

The right-side article TOC is configured with docs.tocHeadings.

#Custom containers

::: info
Useful information.
:::

::: tip Custom title
Helpful advice.
:::

::: warning
Be careful.
:::

::: danger
This action is destructive.
:::

::: details Click to expand
Hidden details.
:::

Available containers:

• info
• tip
• warning
• danger
• details

#Numbered steps

Use ::: steps for short ordered instructions with a numbered marker beside each step. Each heading inside the container starts a new step.

npx @kyechan99/docgo init

npx docgo dev

npx docgo build

::: steps

### Run the CLI

Create the starter files for a Docgo project.

```bash
npx @kyechan99/docgo init
```

### Start the dev server

Preview the docs while editing Markdown and config files.

```bash
npx docgo dev
```

### Build the site

Generate the static output for deployment.

```bash
npx docgo build
```

:::

#GitHub alerts

GitHub blockquote alerts are supported.

> [!NOTE]
> Useful information.

> [!TIP]
> Helpful advice.

> [!IMPORTANT]
> Key information.

> [!WARNING]
> Urgent warning.

> [!CAUTION]
> Risk or negative outcome.

#Syntax highlighting

Code blocks are highlighted with Shiki using separate light and dark themes.

const message: string = 'Hello, Docgo';
console.log(message);

```ts
const message: string = 'Hello, Docgo';
console.log(message);
```

Common languages are preloaded, including JavaScript, TypeScript, JSX, TSX, JSON, HTML, CSS, Vue, Svelte, Markdown, Bash, Python, Go, Rust, Java, C/C++, C#, PHP, Ruby, SQL, YAML, TOML, Docker, GraphQL, Diff, HTTP, and XML.

#Line highlighting

Highlight specific lines with Shiki meta ranges.

const a = 1;
const b = 2;
const c = 3;
const d = 4;

```js {1,3-4}
const a = 1;
const b = 2;
const c = 3;
const d = 4;
```

#Inline code notations

Use Shiki notation comments for line-level emphasis.

const highlighted = true; 
const focused = true; 
const removed = false; 
const added = true; 
const error = null; 
const warning = undefined; 

```js
const highlighted = true; // [!code highlight]
const focused = true; // [!code focus]
const removed = false; // [!code --]
const added = true; // [!code ++]
const error = null; // [!code error]
const warning = undefined; // [!code warning]
```

#Line numbers

Enable line numbers with :line-numbers.

function add(a: number, b: number) {
  return a + b;
}

```ts:line-numbers
function add(a: number, b: number) {
  return a + b;
}
```

Start from a custom number:

export const value = 1;

```ts:line-numbers=10
export const value = 1;
```

#Code block titles

Put a title in square brackets.

export default defineConfig({
  title: 'My Docs',
});

```js [docgo.config.mjs]
export default defineConfig({
  title: 'My Docs',
});
```

#Code groups

Wrap titled code blocks in ::: code-group.

npm install @kyechan99/docgo

pnpm add @kyechan99/docgo

::: code-group

```js [npm]
npm install @kyechan99/docgo
```

```bash [pnpm]
pnpm add @kyechan99/docgo
```

:::

The client script turns the titled blocks into tabs.

#Playgrounds

Use ::: playground when a page needs to show a live MDX example beside the source code for that example. Non-code children become the Preview tab. Fenced code blocks become the Code tab.

The first label after playground is the title shown in the toolbar. The title can be written as plain text or as a directive label:

:::: playground Button

:::: playground [Button]

Preview content is isolated by default so Docgo prose styles do not change the example UI.

<Button>Sample</Button>

import { Button } from 'bmates-ui';

:::: playground Button

<Button>Sample</Button>

```tsx [preview source]
<Button>Sample</Button>
```

::::

For browser-only previews, multiple code snippets, iframe behavior, shared providers, and registered preview components, see Preview.

#File includes

The following code blocks show the authoring syntax. When written outside a code block, @include pulls another markdown file into the current page.

<!--@include: ./path/to/intro.md-->

Use line ranges:

<!--@include: ./path/to/intro.md{1,10}-->

Use named regions:

<!--@include: ./path/to/intro.md#install-->

Includes can nest up to eight levels.

#Code snippet imports

The following code blocks show the authoring syntax. When written outside a code block, <<< imports a source file and renders it as a highlighted fenced code block.

<<< ./path/to/config.js

Use the docs root alias:

<<< @/path/to/config.js

Use named regions:

<<< ./path/to/config.js#basic

Add meta after the path:

<<< ./path/to/config.js {1,4} line-numbers

Docgo infers the language from the file extension unless a language is provided in the meta string.

#Custom heading anchors

Add a stable heading ID with {#id}.

## Install Docgo {#install}

Link to it normally:

[Install](#install)

#API lists

Use api-item containers inside api-list to create an API reference layout. Use the :property:, :type:, and :default: fields for metadata. Their values support inline Markdown, while the item body can contain multiple paragraphs, lists, links, and code.

:::: api-list
::: api-item
:tags: web, native
:property: variant
:type: `default` | `primary`
:default: `primary`
Selects the visual emphasis for the action.

- Use `primary` for the primary action in a view.
- Use `default` when the action should be visually neutral.
:::
::::

Supported API metadata fields:

• :property:
• :type:
• :default:

Use the tags (or platforms) attribute for comma- or pipe-separated badges. The descriptive content belongs in the item body. This avoids Markdown-table escaping issues and allows each union option to be formatted independently.

#Lazy images and tables

Images are rendered with lazy loading where possible. Markdown tables are wrapped so wide tables remain usable on small screens.

#Raw markdown output

Frontmatter is stripped from generated .md mirror files. The markdown mirror keeps the readable source content for "View as Markdown" and AI-reader links.