Syntax Guide

A practical reference to core Markdown syntax for writing docs.

Basic Formatting

Text Formatting

• Bold text using **bold text**
• Italic text using *italic text*
• Inline code using backticks
• Strikethrough using ~~strikethrough~~

Headers

Lists

Unordered

Ordered

Links and Images

Links

Images

Code

Inline Code

Use single backticks for inline code.

Basic Code Blocks

Use triple backticks with language specification:

console.log('Hello, world!')

Custom MDX Components

Custom MDX components supported by this repo

Tip: Components can be nested (e.g., a callout inside a card, code fences inside tabs).

Code Blocks with options

export function getToken() {
  return process.env.TOKEN
}

export function isLoggedIn() {
  return Boolean(getToken())
}

Callouts

Supported types: info, warning, error, success, tip, danger.

Callouts with Rich Content

console.log('Hello from inside a callout!');

Cards

Basic Card Examples

Card Layout Options

Clickable Cards

Cards with Rich Content

function greetUser(name) {
  return `Hello, ${name}! Welcome to our app.`;
}

const message = greetUser('Alice');
console.log(message);

CardGroups

Basic CardGroup Examples

CardGroup with Different Column Layouts

Single Column Layout

// Example: Full-width content
const fullWidthComponent = () => {
  return <div className="full-width">Content here</div>;
};

Three Column Layout

CardGroup with Mixed Content

curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer your-token"

import { APIClient } from '@our-platform/sdk';
const client = new APIClient('your-api-key');

Accordions

Accordion Groups

Basic Accordion Group

Exclusive Accordion Group

mkdir my-project && cd my-project && npm init -y

Expand

Steps

Basic Steps

npm install @markdoc/markdoc react

export default { nodes: {}, tags: {} }

# Welcome to Markdoc
<Callout type="info">Hello from Markdoc!</Callout>

Advanced Steps with Rich Content

CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  tag VARCHAR(100),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

import express from 'express'
const router = express.Router()

router.get('/documents', async (req, res) => {
  const documents = await db.query('SELECT * FROM documents')
  res.json(documents)
})

router.post('/documents', async (req, res) => {
  const { name, tag } = req.body
  const result = await db.query('INSERT INTO documents(name, tag) VALUES($1,$2) RETURNING *', [name, tag])
  res.status(201).json(result.rows[0])
})

export default router

npm run test && npm run build && npm run deploy

CodeGroups

curl --request POST https://api.example.com/v1/documents \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{"name":"Aloe","tag":"succulent"}'

export async function listDocuments() {
  const res = await fetch('/v1/documents')
  if (!res.ok) throw new Error('Failed to load')
  return res.json()
}

Fields

Tooltips

Tabs

function greetUser(name) {
  return `Hello, ${name}!`;
}

curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"jane@example.com"}'