Docs Component Showcase

This page is a living reference for every component, formatting primitive, and automatic-numbering feature available in this MDX documentation system. Use it to validate rendering and as a copy-paste starting point.

Each section below demonstrates one category of functionality. The section numbers, figure labels, equation numbers, and reference citations are all generated automatically. No manual counters required.

Callouts

Four semantic variants give you visual hierarchy for alerts and annotations.

Use note for neutral information that supplements the main text.

Use tip to highlight a best practice, shortcut, or pro move.

Use warning when something can go wrong: configuration pitfalls, deprecations, etc.

Use danger for destructive or irreversible operations only.

Code Blocks

Syntax-highlighted via Shiki with dual theming (dark/light). Line numbers and titles are supported.

JavaScript

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}
 
console.log(fibonacci(10)); // 55

TypeScript with line highlights

interface Project {
  slug: string;
  title: string;       // highlighted
  publishedAt: string; // highlighted
  tags: string[];      // highlighted
}

Shell

npm install
npm run dev
npm run build

Inline code: use backticks in prose for variable names, function() calls, or --cli-flags.

Mathematics

Block-level equations are wrapped in <Equation> for auto-numbering. Raw $$...$$ works too.

Euler's identity

$e^{i\pi} + 1 = 0$

Discrete PID controller

$u[k] = K_p \, e[k] + K_i \sum_{j=0}^{k} e[j]\,\Delta t + K_d \frac{e[k] - e[k-1]}{\Delta t}$

Fourier transform

$\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\, e^{-2\pi i x \xi}\, dx$

Inline math also works: the quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ .

Diagrams

Mermaid diagrams render server-side with no client JS.

System architecture

Sequence diagram

Tabs

Group related variant content under named tabs.

npm install next-mdx-remote
npm install rehype-pretty-code shiki
npm install remark-gfm rehype-katex katex

pnpm add next-mdx-remote
pnpm add rehype-pretty-code shiki
pnpm add remark-gfm rehype-katex katex

yarn add next-mdx-remote
yarn add rehype-pretty-code shiki
yarn add remark-gfm rehype-katex katex

Steps

Numbered procedural sequences with visual connectors.

Install dependencies

Run npm install to install all required packages.

Configure MDX options

Set up rehypePlugins and remarkPlugins in your mdxOptions config.

Add custom components

Pass docsComponents to <MDXRemote components={docsComponents} />.

Write your first MDX file

Create a .mdx file in the projects/ folder and add frontmatter.

Cards

Card grid

MDX Engine

next-mdx-remote/rsc compiled at build time with zero runtime overhead, full React component support inside .mdx files.

🎨

Syntax Highlighting

Shiki dual-theme (github-dark-default / github-light-default) with precise token-level CSS variable output.

∑

Math Rendering

KaTeX via rehype-katex with server-side rendering, no flicker, full LaTeX math support including display and inline modes.

Auto Numbering

CSS counters on .docs-article automatically label headings, figures, tables, and equations by section. No manual tracking.

Link cards

next-mdx-remote docs

Official docs for the MDX processing library used here.

→

Shiki documentation

Syntax highlighter powering all code blocks on this site.

→

Tables

Auto-numbering with caption

Library	SSR	Bundle size	Custom components
`next-mdx-remote`	✓	~40 kB	✓
`@mdx-js/react`	✓	~25 kB	✓
`contentlayer`	✓	~120 kB	✓
`mdx-bundler`	✓	~30 kB	✓

Comparison of MDX processing libraries

Plain GFM table (no caption, no auto-number)

Prop	Type	Default	Description
`type`	`string`	`"note"`	Callout variant
`title`	`string`	—	Optional heading
`children`	`ReactNode`	—	Content

Figures

Images wrapped in <Figure> receive automatic section-scoped labels.

Keyboard & inline UI

Use Ctrl + K to open the command palette. Press ⌘ Shift P on macOS.

Badges classify content at a glance:

Stable Beta Deprecated New

Collapsible details

▶How do CSS counters work in this system?

Every .docs-article element carries counter-reset for all six counter families: docs-h2, docs-h3, docs-h4, docs-fig, docs-tab, and docs-eq. When a .docs-h2 heading is encountered, it increments docs-h2 and resets all subsection counters. Figures, tables, and equations then read both the current H2 counter and their own local counter to produce the X.Y label via ::before / ::after pseudo-elements.

▶Can I mix <Equation> with bare $$ math?

Yes. Bare $$...$$ paragraphs produce a .katex-display block which is styled but not auto-numbered. Wrap in <Equation> when you want the (X.Y) label to appear on the right.

Aside

Highlight & Prose Utilities

You can highlight a span of text inline, or use a custom colour: accent gold.

The GFM extensions are also active:

remark-gfm enabled
Task list checkboxes render
Strikethrough ~~works~~
Tables supported natively

Props Table

Property	Type	Default	Description
`type`	`"note" \| "tip" \| "warning" \| "danger" \| "info"`	`"note"`	Visual variant of the callout
`title`	`string`	`—`	Optional heading displayed in bold above content
`children`	`ReactNode`	`—`	The callout body content

Timeline

Vertical timeline for changelogs, milestones, or version history. Each item takes date, title, and an optional badge.

JS-driven heading counters, figure/table/equation auto-labels, IEEE reference components, and 4 new layout primitives.

Rebuilt left sidebar with current-project card, numbered nav, progress bar. Right TOC with scroll-spy and section numbers.

Bootstrapped next-mdx-remote pipeline with Shiki dual-theme, KaTeX math, Mermaid diagrams, and first component library.

Metrics

Stat cards for benchmarks, performance numbers, or any quantitative summary. Supports value, label, unit, delta, and trend (up / down / neutral).

1.2ms

avg response time

↑ −18% vs v2

98%

Lighthouse score

↑ +4 pts

static pages

client JS (docs)

↑ fully static

8.5s

build time

72ch

content width

Quote

Academic-style pull quote with author and optional source attribution. Great for referencing influential ideas or standards.

Premature optimization is the root of all evil.
Donald KnuthThe Art of Computer Programming

Simplicity is a great virtue but it requires hard work to achieve it and education to appreciate it. And to make matters worse: complexity sells better.
Edsger W. Dijkstra

Gallery

Responsive image grid. Pass an images array and optional cols (2 / 3 / 4, default 3).

Claude

ChatGPT

Gemini

Copilot

DeepSeek

Grok

HuggingFace

Qwen

Citations & References

This showcase references key standards ^[1] and tooling documentation ^{[2, 3]} used in the MDX pipeline design. The KaTeX rendering engine ^[4] allows full LaTeX math, while Shiki ^[5] provides fine-grained syntax highlighting.

References

[1]IEEE Std 830-1998, IEEE Recommended Practice for Software Requirements Specifications. IEEE, 1998.
[2]J. Bayer and contributors. "next-mdx-remote: Load MDX content from anywhere." GitHub, 2024. [Online]. Available: https://github.com/hashicorp/next-mdx-remote
[3]A. Thomas and contributors. "Shiki — A beautiful syntax highlighter." shiki.style, 2024. [Online]. Available: https://shiki.style
[4]KaTeX contributors. "KaTeX: Fast math typesetting for the web." katex.org, 2024. [Online]. Available: https://katex.org
[5]rehype-pretty-code contributors. "rehype-pretty-code." GitHub, 2024. [Online]. Available: https://rehype-pretty-code.netlify.app

Advanced Components

Columns & Progress

Layout content flexibly and track status with ProgressBar.

You can now make callouts collapsible! This is great for keeping long code snippets or auxiliary information hidden until the user explicitly wants to read it.

Interactive Displays

Hover over the term Docs System to see the tooltip in action.

Iskandar Putra

Software Engineer

Rich Task Lists (GFM)

Create advanced components
Update stylings
Write integration tests

Embeds & Bookmarks

Enhance external links with <Bookmark> for automated OpenGraph-style previews.

Shiki: A beautiful yet powerful syntax highlighter

Shiki is a beautiful and powerful syntax highlighter based on TextMate grammar. It powers the robust codeblock highlighting on this page.

https://shiki.style/

Kanban Board

A static kanban board primitive to demonstrate project workflows.

To Do

Review MDX plugins

Update documentation

In Progress

Implementing Kanban

Done

System Design

Initial Layout

Image Comparison

An interactive <ImageCompare> slider to showcase before/after scenarios in your docs.

Original

Grayscale Filter

Docs Component Showcase

Callouts

Four semantic variants give you visual hierarchy for alerts and annotations.

Use note for neutral information that supplements the main text.

Use tip to highlight a best practice, shortcut, or pro move.

Use warning when something can go wrong: configuration pitfalls, deprecations, etc.

Use danger for destructive or irreversible operations only.

Code Blocks

Syntax-highlighted via Shiki with dual theming (dark/light). Line numbers and titles are supported.

JavaScript

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}
 
console.log(fibonacci(10)); // 55

TypeScript with line highlights

interface Project {
  slug: string;
  title: string;       // highlighted
  publishedAt: string; // highlighted
  tags: string[];      // highlighted
}

Shell

npm install
npm run dev
npm run build

Inline code: use backticks in prose for variable names, function() calls, or --cli-flags.

Mathematics

Block-level equations are wrapped in <Equation> for auto-numbering. Raw $$...$$ works too.

Euler's identity

$e^{i\pi} + 1 = 0$

Discrete PID controller

$u[k] = K_p \, e[k] + K_i \sum_{j=0}^{k} e[j]\,\Delta t + K_d \frac{e[k] - e[k-1]}{\Delta t}$

Fourier transform

$\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\, e^{-2\pi i x \xi}\, dx$

Inline math also works: the quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ .

Diagrams

Mermaid diagrams render server-side with no client JS.

System architecture

Sequence diagram

Tabs

Group related variant content under named tabs.

npm install next-mdx-remote
npm install rehype-pretty-code shiki
npm install remark-gfm rehype-katex katex

pnpm add next-mdx-remote
pnpm add rehype-pretty-code shiki
pnpm add remark-gfm rehype-katex katex

yarn add next-mdx-remote
yarn add rehype-pretty-code shiki
yarn add remark-gfm rehype-katex katex

Steps

Numbered procedural sequences with visual connectors.

Install dependencies

Run npm install to install all required packages.

Configure MDX options

Set up rehypePlugins and remarkPlugins in your mdxOptions config.

Add custom components

Pass docsComponents to <MDXRemote components={docsComponents} />.

Write your first MDX file

Create a .mdx file in the projects/ folder and add frontmatter.

Cards

Card grid

MDX Engine

next-mdx-remote/rsc compiled at build time with zero runtime overhead, full React component support inside .mdx files.

🎨

Syntax Highlighting

Shiki dual-theme (github-dark-default / github-light-default) with precise token-level CSS variable output.

∑

Math Rendering

KaTeX via rehype-katex with server-side rendering, no flicker, full LaTeX math support including display and inline modes.

Auto Numbering

CSS counters on .docs-article automatically label headings, figures, tables, and equations by section. No manual tracking.

Link cards

next-mdx-remote docs

Official docs for the MDX processing library used here.

→

Shiki documentation

Syntax highlighter powering all code blocks on this site.

→

Tables

Auto-numbering with caption

Library	SSR	Bundle size	Custom components
`next-mdx-remote`	✓	~40 kB	✓
`@mdx-js/react`	✓	~25 kB	✓
`contentlayer`	✓	~120 kB	✓
`mdx-bundler`	✓	~30 kB	✓

Comparison of MDX processing libraries

Plain GFM table (no caption, no auto-number)

Prop	Type	Default	Description
`type`	`string`	`"note"`	Callout variant
`title`	`string`	—	Optional heading
`children`	`ReactNode`	—	Content

Figures

Images wrapped in <Figure> receive automatic section-scoped labels.

Keyboard & inline UI

Use Ctrl + K to open the command palette. Press ⌘ Shift P on macOS.

Badges classify content at a glance:

Stable Beta Deprecated New

Collapsible details

▶How do CSS counters work in this system?

▶Can I mix <Equation> with bare $$ math?

Yes. Bare $$...$$ paragraphs produce a .katex-display block which is styled but not auto-numbered. Wrap in <Equation> when you want the (X.Y) label to appear on the right.

Aside

Highlight & Prose Utilities

You can highlight a span of text inline, or use a custom colour: accent gold.

The GFM extensions are also active:

remark-gfm enabled
Task list checkboxes render
Strikethrough ~~works~~
Tables supported natively

Props Table

Property	Type	Default	Description
`type`	`"note" \| "tip" \| "warning" \| "danger" \| "info"`	`"note"`	Visual variant of the callout
`title`	`string`	`—`	Optional heading displayed in bold above content
`children`	`ReactNode`	`—`	The callout body content

Timeline

Vertical timeline for changelogs, milestones, or version history. Each item takes date, title, and an optional badge.

JS-driven heading counters, figure/table/equation auto-labels, IEEE reference components, and 4 new layout primitives.

Rebuilt left sidebar with current-project card, numbered nav, progress bar. Right TOC with scroll-spy and section numbers.

Bootstrapped next-mdx-remote pipeline with Shiki dual-theme, KaTeX math, Mermaid diagrams, and first component library.

Metrics

Stat cards for benchmarks, performance numbers, or any quantitative summary. Supports value, label, unit, delta, and trend (up / down / neutral).

1.2ms

avg response time

↑ −18% vs v2

98%

Lighthouse score

↑ +4 pts

static pages

client JS (docs)

↑ fully static

8.5s

build time

72ch

content width

Quote

Academic-style pull quote with author and optional source attribution. Great for referencing influential ideas or standards.

Premature optimization is the root of all evil.
Donald KnuthThe Art of Computer Programming

Simplicity is a great virtue but it requires hard work to achieve it and education to appreciate it. And to make matters worse: complexity sells better.
Edsger W. Dijkstra

Gallery

Responsive image grid. Pass an images array and optional cols (2 / 3 / 4, default 3).

Claude

ChatGPT

Gemini

Copilot

DeepSeek

Grok

HuggingFace

Qwen

Citations & References

References

[1]IEEE Std 830-1998, IEEE Recommended Practice for Software Requirements Specifications. IEEE, 1998.
[2]J. Bayer and contributors. "next-mdx-remote: Load MDX content from anywhere." GitHub, 2024. [Online]. Available: https://github.com/hashicorp/next-mdx-remote
[3]A. Thomas and contributors. "Shiki — A beautiful syntax highlighter." shiki.style, 2024. [Online]. Available: https://shiki.style
[4]KaTeX contributors. "KaTeX: Fast math typesetting for the web." katex.org, 2024. [Online]. Available: https://katex.org
[5]rehype-pretty-code contributors. "rehype-pretty-code." GitHub, 2024. [Online]. Available: https://rehype-pretty-code.netlify.app

Software Engineer

Rich Task Lists (GFM)

Create advanced components
Update stylings
Write integration tests

Embeds & Bookmarks

Enhance external links with <Bookmark> for automated OpenGraph-style previews.

Shiki: A beautiful yet powerful syntax highlighter

Shiki is a beautiful and powerful syntax highlighter based on TextMate grammar. It powers the robust codeblock highlighting on this page.

https://shiki.style/

Kanban Board

A static kanban board primitive to demonstrate project workflows.

To Do

Review MDX plugins

Update documentation

In Progress

Implementing Kanban

Done

System Design

Initial Layout

Image Comparison

An interactive <ImageCompare> slider to showcase before/after scenarios in your docs.

Original

Grayscale Filter