MDC components

Authoring reference for the canonical Ginko Docs prose components and their two appearances.

Ginko Docs exposes one canonical tag for each authored concept. Native Markdown remains the default for prose, headings, lists, links, images, code fences, and GFM alerts.

Use only static scalar props inline. Put arrays, objects, and booleans in YAML frontmatter inside the component. Dynamic bindings, events, directives, arbitrary styles, and bare boolean attributes are rejected.

Appearance

Surface components accept appearance="quiet" or appearance="tint". The component prop overrides its family setting, which overrides the global setting:

app/app.config.ts

export default defineAppConfig({
  ginkoDocs: {
    prose: {
      appearance: "quiet",
      components: {
        callout: "tint",
        aside: "tint",
        excerpt: "tint",
        tabs: "tint",
      },
    },
  },
});

Appearance-aware families are callouts, aside, excerpt, cards, read-more, accordion, tabs, code, files, API, figure, quiz, steps, and timeline.

Notices and supporting prose

Use GFM alerts when one of its five portable meanings fits:

content/docs/routes.md

> [!WARNING]
> Keep translated numeric identities aligned.

Tag	Props	Content
`note`, `info`, `success`, `warning`, `error`, `idea`	`title?`, `icon?`, `appearance?`	Prose
`aside`	`label?`, `appearance?`	Prose
`excerpt`	`label?`, `source?`, `appearance?`	Quoted prose
`dropcap`	`lines?: 2 \| 3 \| 4`	Prose
`kbd`	—	Inline key label

Use :kbd[⌘] for an inline key. Use ordinary > blockquotes for quotations without a notice meaning.

Tag	Props	Content
`accordion`	`type?`, `collapsible?`, `defaultValue?`, `appearance?`	`accordion-item` children
`accordion-item`	`value?`, `title?`, `content?`	Prose
`tabs`	`layout?: separate \| line`, `padded?`, `appearance?`	`tab` children
`tab`	`label?`, `icon?`	Prose
`read-more`	`title?`, `links: json`, `appearance?`	No prose slot
`toc`	`title?`, `depth?`, `open?`	No prose slot

Boolean values such as collapsible and padded belong in YAML.

Cards and layout

Tag	Props	Content
`cards`	`cols?: 1 \| 2 \| 3`, `appearance?`	`card` children
`card`	`title?`, `description?`, `footer?`, `to?`, `target?`, `icon?`, `iconColor?`, `img?`, `showLinkIcon?`, `horizontal?`, `appearance?`	Prose and named title, description, footer slots
`layout`	`type?`	`column` children
`column`	`size?: sm \| md \| lg`	Prose
`center`	`size?`, `max?`, `type?`	Prose

content/docs/choices.md

::cards{cols="2"}
:::card{title="Author" icon="lucide:file-pen-line" to="/docs/authoring"}
Write canonical Markdown.
:::
:::card{title="Publish" icon="lucide:rocket" to="/docs/deployment"}
Build reader and agent outputs.
:::
::

Sequences

Tag	Props	Content
`steps`	`mode?: icons \| numbered`, `appearance?`	Level-three headings followed by full Markdown
`timeline`	`appearance?`	`timeline-item` children
`timeline-item`	`date?`, `label?`, `title?`, `icon?`, `active?`	Prose

content/docs/install.md

::steps{mode="numbered"}
### Install

Add the packages.

### Configure

Extend the layer.
::

Put active: true for a timeline item in its YAML block.

Code and files

Tag	Props	Content
`code-group`	`appearance?`	Labeled fenced code blocks
`code-tree`	`defaultValue?`, `expandAll?`, `appearance?`	Labeled fenced code blocks
`collapse`	`appearance?`	A long prose or code block
`files`	`active?`, `annotations?`, `appearance?`	One nested Markdown list

content/docs/project-structure.md

::files
---
active: app/app.config.ts
annotations:
  app/app.config.ts: site identity
---
- `app`
  - `app.config.ts`
  - `components`
    - `FeaturePanel.vue`
::

Code fences use only the language, [filename], and line-highlight metadata. Use collapse, code-group, or code-tree for higher-level behavior.

API data

api accepts title?, icon?, method?, path?, groups?, and appearance?. Put the existing groups structure directly in component YAML:

content/docs/api.md

::api{title="figure" icon="lucide:image"}
---
groups:
  - label: Props
    entries:
      - name: src
        annotation: asset
        required: true
        description: Public image reference.
---
::

Images

Author ordinary images with Markdown. Use figure only when the image needs explicit caption, dimensions, bleed, aspect, fit, zoom, or appearance.

Tag	Props
`figure`	`src`, `alt`, `caption?`, `width?`, `height?`, `bleed?`, `aspect?`, `fit?`, `zoom?`, `appearance?`

Put boolean zoom values in YAML. Without an override, figures follow ginkoDocs.images.zoom.

Quiz

Tag	Props	Content
`quiz`	labels, title, description, `appearance?`	`quiz-question` children
`quiz-question`	`question`, `type?`, `options?`, optional interaction labels	Explanation prose

content/docs/check.md

::quiz{title="Check your understanding"}
:::quiz-question
---
question: Which package owns document identity?
options:
  - text: Ginko Content
    correct: true
  - text: Ginko Docs
    correct: false
---
Ginko Content owns canonical document identity and routes.
:::
::

Extend the tag map

Merge ginkoDocsComponentTags and ginkoDocsComponentPolicy from @lupinum/ginko-docs/components when adding an authored component. Register its Vue component globally and add an agent serializer when the default XML-style representation is insufficient.