Components

Use Nuxt UI prose components, Mermaid diagrams, and interactive embeds inside your Markdown pages.

Beyond plain Markdown, pages can use Vue components through the MDC syntax: a block component is written as ::component-name, closed with ::, and nested components add one colon per level (:::child).

Three kinds of components are available in docs pages:

Nuxt UI prose components — callouts, tabs, steps, and code widgets, available without any prefix.
Nuxt UI components — any Nuxt UI component, with the u- prefix (::u-button).
Layer components — Mermaid, CodeExplorer, and Browser, injected by the docs page.

Prose components

The layer enables Nuxt UI typography, so every prose component works out of the box. The ones you'll reach for most:

Callouts

Bodies are parsed lazily on get().

This feature is experimental.

::note
Bodies are parsed lazily on `get()`.
::
::warning
This feature is experimental.
::

Variants: ::note, ::tip, ::warning, ::caution, and a generic ::callout{icon="i-lucide-info" to="/some/page"}.

Code groups

One fenced block per tab, labeled with [...]:

pnpm add comark-docs@github:comarkdown/comark-docs

npm install comark-docs@github:comarkdown/comark-docs

::code-group
```bash [pnpm]
pnpm add comark-docs@github:comarkdown/comark-docs
```
```bash [npm]
npm install comark-docs@github:comarkdown/comark-docs
```
::

Cards

Fast

Parses on demand, caches by commit.

Versioned

Preview any branch or commit.

::card-group
  ::card{icon="i-lucide-rocket" title="Fast" to="/concepts/architecture"}
  Parses on demand, caches by commit.
  ::

  ::card{icon="i-lucide-git-branch" title="Versioned"}
  Preview any branch or commit.
  ::
::

Steps

Wrap a sequence of ### headings to render a numbered procedure:

Install the layer

This is the first step.

Extend your config

This is the second step.

Write a page

This is the third step.

::steps{level="3"}
### Install the layer

This is the first step.

### Extend your config

This is the second step.

### Write a page

This is the third step.
::

Other useful ones: ::tabs with :::tabs-item{label="..."} children, ::collapsible, ::accordion, ::code-preview (rendered output next to its source), and ::code-collapse. See the Nuxt UI typography docs for the full list and props.

Nuxt UI components

Any Nuxt UI component works with the u- prefix. The landing page uses this for its hero:

Get started

::u-button
---
to: /getting-started/introduction
trailing-icon: i-lucide-arrow-right
---
Get started
::

Mermaid diagrams

Write a ```mermaid code fence and it renders as a diagram, themed for both color modes:

```mermaid
flowchart LR
  A[Markdown push] --> B[GitHub webhook]
  B --> C[ISR purge]
```

CodeExplorer

::code-explorer embeds a browsable file tree from a GitHub repository, with syntax-highlighted file contents — useful for walking readers through an example project:

index.md

---
title: A Nuxt layer for content-driven documentation
description: "comark-docs is a Nuxt layer for documentation sites powered by comark-content: Markdown served at request time, ISR-cached, revalidated on push."
navigation: false
---

::u-page-hero
---
orientation: horizontal
---
#title
Docs that ship without a redeploy.

#description
The first Markdown-driven docs site where content goes live on `git push`. No rebuild, no redeploy. Served at request time through [Comark Content](https://content.comark.dev), cached at the edge, revalidated by a webhook. And every branch or commit is already a live preview.

#links
  :::u-button
  ---
  to: /getting-started/introduction
  size: lg
  trailing-icon: i-lucide-arrow-right
  ---
  Get started
  :::

  :::u-button
  ---
  to: /concepts/architecture
  size: lg
  color: neutral
  variant: outline
  ---
  How it works
  :::

#default
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['comark-docs'],
  site: {
    url: 'https://docs.example.com',
    name: 'My Project',
  },
})
```
::

::landing-features
#headline
Features

#title
Everything a docs site needs

#default
  :::landing-feature-card{icon="i-lucide-zap" to="/concepts/architecture"}
  #title
  Instant content

  #description
  Push Markdown to your production branch and it's live in seconds. A webhook purges exactly the pages that changed.
  :::

  :::landing-feature-card{icon="i-lucide-git-branch" to="/concepts/versioned-previews"}
  #title
  Versioned previews

  #description
  Every branch renders at `/tree/branch`, every commit at `/blob/sha` with full navigation and search, skip new deploys.
  :::

  :::landing-feature-card{icon="i-lucide-panels-top-left" to="/writing/components"}
  #title
  Docs UI included

  #description
  Sidebar navigation, search (`⌘K`), table of contents, prev/next links, and a version history panel — built with Nuxt UI.
  :::

  :::landing-feature-card{icon="i-lucide-search" to="/writing/navigation"}
  #title
  SEO out of the box

  #description
  Sitemap, canonical URLs, OG images, and JSON-LD structured data, all generated from your content tree.
  :::

  :::landing-feature-card{icon="i-lucide-bot" to="/getting-started/introduction"}
  #title
  AI-native

  #description
  `llms.txt`, raw Markdown mirrors, an MCP server, Agent Skills discovery, and an optional "Ask AI" assistant.
  :::

  :::landing-feature-card{icon="i-lucide-message-square-text" to="/deployment/pr-preview-comments"}
  #title
  Review-friendly

  #description
  A GitHub Action comments on content PRs with instant preview links for every changed page.
  :::
::

::landing-faq
---
items:
  - label: Do I need to redeploy when content changes?
    content: No. Content is fetched from GitHub at request time and cached. A push to the production branch triggers a webhook that purges the changed pages — they're live within seconds, and the build is skipped entirely.
  - label: How do I preview a branch or a pull request?
    content: Any branch renders live at `/tree/branch-name`, any commit at `/blob/sha`, with that version's own navigation and search. An optional GitHub Action posts the links on pull requests.
  - label: Is it slow to parse Markdown on every request?
    content: Pages are parsed once per commit, not per request. Rendered HTML is ISR-cached at the edge and parsed content is cached by commit SHA, so warm pages are served without touching GitHub at all.
  - label: How do I install it?
    content: "It isn't on npm yet — install it from GitHub with `pnpm add comark-docs@github:comarkdown/comark-docs` and add `extends: ['comark-docs']` to your Nuxt config."
---
#headline
FAQ

#title
Frequently asked questions
::

::landing-cta
#title
Ready to ship docs faster?

#description
Install the layer, write Markdown in `content/`, and push. This site is the playground — everything you see here is built with it.

#links
  :::u-button
  ---
  to: /getting-started/installation
  size: lg
  trailing-icon: i-lucide-arrow-right
  ---
  Install comark-docs
  :::

  :::u-button
  ---
  to: https://github.com/comarkdown/comark-docs
  size: lg
  color: neutral
  variant: outline
  icon: i-simple-icons-github
  target: _blank
  ---
  Star on GitHub
  :::
::

::code-explorer
---
org: comarkdown
repo: comark-docs
path: playground/content
default-value: index.md
---
::

Prop	Type	Default	Purpose
`org`	`string`	required	GitHub organization or user.
`repo`	`string`	required	Repository name.
`path`	`string`	required	Directory to explore, relative to the repository root.
`branch`	`string`	`'main'`	Branch to read from.
`default-value`	`string`	first file	Path of the file selected on load.

The server only fetches from your own content repository by default. To embed another repository, add it to comarkDocs.codeExplorer.allowRepos.

Browser

::browser frames a live site in browser chrome — traffic lights, a URL bar, and an open-in-new-tab button around a lazy-loaded <iframe>:

https://docs-template.comark.dev

::browser{src="https://docs-template.comark.dev"}
::

Prop	Type	Default	Purpose
`src`	`string`	required	URL loaded in the iframe and shown in the address bar.

Next steps

Landing page — the hero, feature grids, FAQ, and CTA components for index.md.

Markdown

Comark supports all standard CommonMark and GitHub Flavored Markdown (GFM) features including headings, formatting, lists, tables, code blocks, and more.

Landing page

Build your home page in content/index.md with the hero, feature grid, FAQ, and CTA components.