Built-in Features#

Ox Content keeps common documentation behavior on by default and keeps non-standard Markdown or HTML extensions opt-in.

The defaults below match @ox-content/vite-plugin. They are designed for a fast static baseline: parsing, static embeds, source docs, and search indexing run during transform or build, while extra syntax and runtime behavior must be enabled explicitly.

This documentation site is built with Ox Content, so the feature guides below do not just describe each feature — they enable it and render live examples inline.

Feature Guides#

Guide	Covers
Markdown Baseline	GFM, tables, task lists, footnotes, autolinks, frontmatter, TOC
Component Matrix	Authoring API, generated HTML, a11y, theme hooks, no/low-JS behavior
Heading Permalinks	Opt-in visible `#` links that reuse the generated heading id
Syntax Extensions	Emoji shortcodes, wiki links, attribute syntax, CJK emphasis
Cross References	Opt-in labeled links for sections, figures, and tables
Citations	Opt-in CSL JSON citations and generated bibliography entries
BudouX	Opt-in build-time phrase segmentation for Japanese line breaking
Custom Containers	Opt-in `::: tip` / `::: details` callout blocks
Conditional Blocks	Opt-in static `::: if` / `::: else` branches
Cards	Opt-in `::: card` / `::: link-card` / `::: card-grid` blocks
Step Lists	Opt-in `::: steps` tutorial lists
File Includes	Opt-in `<!-- @include -->` Markdown fragments
Markdown Partials	Opt-in parameterized `<!-- @partial -->` snippets
File Tree	Opt-in static `file-tree` directory diagrams
Data Tables	Opt-in static tables from `csv-table` / `json-table` fences
Inline Badges	Opt-in `{badge:tip}` status labels in headings or prose
NotByAI Badge	Opt-in static human-authorship disclosure (`<NotByAI />`)
Keyboard Keys	Opt-in `{kbd:Ctrl+K}` semantic shortcut markup
Abbreviations	Opt-in `*[TERM]:` glossary expansion into accessible `<abbr>`
Definition Lists	Opt-in `Term` / `: definition` glossary lists
Magic Links	Opt-in `{link:@user}` / alias / `label\|url` rich links with avatars
Images	Opt-in figures, captions, lazy loading, and safe dimensions
Page resources	Opt-in page-bundle assets with resize, crop, and format transforms
Code Blocks	Syntax highlighting, code annotations, code imports
Code Groups	Opt-in VitePress-style `::: code-group` fence tabs
Embeds	GitHub cards, OG cards, package-manager tabs, tabs, YouTube, social cards
Mermaid Diagrams	Diagram fences rendered to static SVG
Graphviz DOT Diagrams	DOT graph fences rendered to sanitized static SVG
Math	Opt-in $…$ / `$$…$$` typeset with optional KaTeX
Search	The static BM25 index and client search API
Collections	Query Markdown files with a SQL-like builder
Quality Checks	Code block lint, type checking, docs tests, HTML sanitizer
Typed Hover	Opt-in build-time TypeScript hover overlays for `twoslash` fences
Site Generation	SSG, OG images, edit links, collections, API docs, transformers
Custom host lifecycle	Vite loading, dev routing, invalidation, and writes for custom HTML hosts
Document assets	Typed script, style, link, manifest, and self-hosted asset tags
SSG output primitives	Resources, companions, feeds, sitemaps, and lastmod for `ssg: false` hosts
Component styles	Official CSS for `ssg: false` and `transformAllPlugins()` hosts
Page head	Build-time Unhead-compatible title / meta / link / JSON-LD API
SEO	Canonical, robots, hreflang, and head validation on that API
Previous / Next	Opt-in previous and next page links
Breadcrumbs	Opt-in trail from the site root through sidebar ancestors
JSON-LD	Opt-in TechArticle / WebSite / BreadcrumbList structured data
Reader Chrome	Opt-in copy, outbound-link icons, and back-to-top
Locale Switcher	Opt-in header control for configured locales
Accessibility	Opt-in skip link and print styles
Header chrome	Opt-in header nav, announcement bar, and per-page chrome
Sitemap / robots / llms.txt	Opt-in crawl manifests written next to generated HTML
Markdown source companions	Opt-in original Markdown written beside generated HTML
Draft / unlisted / scheduled	Opt-in frontmatter publish states for production output
Permalinks and Cascade	Opt-in frontmatter URLs and directory-level default frontmatter
Redirects and aliases	Opt-in static HTML redirects from aliases and a rewrite map
Custom 404	Opt-in themed 404 page with nav and search
RSS / Atom / JSON feeds	Opt-in collection feeds written next to generated HTML
Blog	Opt-in paginated index, authors, tags, archive, and optional external feeds
PWA manifest and service worker	Opt-in web app manifest and conservative offline cache (adds client JS)
Self-hosted Iconify CSS	Opt-in CSS masks for used Iconify icons (no api.iconify.design)
Taxonomies	Opt-in tag/category term pages and related-page lists
Documentation versioning	Opt-in prefixes, frozen snapshots, and a header version dropdown
Team / members page	Opt-in static member cards on `layout: team` pages
Git contributors	Opt-in unique git authors under each article
Section index pages	Opt-in generated listings for directories without `index.md`

Default vs Opt-in#

Area	Option	Default	Guide
Markdown base	`gfm`, `footnotes`, `tables`, `taskLists`, `strikethrough`, `autolinks`	`true`	Markdown Baseline
Semantic footnotes	`semanticFootnotes`	`false`	Markdown Baseline
Page metadata	`frontmatter`	`true`	Markdown Baseline
Navigation	`toc`, `tocMaxDepth`	`true`, `3`	Markdown Baseline
Heading links	`headingPermalinks` / `theme.headingPermalink`	`false`, `"hover"`	Heading Permalinks
Static site	`ssg`	`{ enabled }`	Site Generation
Custom HTML host	`oxContentCustomHost`	public API	Custom host lifecycle
Document assets	`renderDocumentAssets`	public API	Document assets
Custom SSG outputs	`planSsgOutputs`, `writeResourceFiles`, `writeMarkdownCompanions`, `renderFeedFiles`, `writeFeedFiles`, `writeSiteMapFiles`	public API	SSG output primitives
API docs	`docs`	`{ enabled }`	Site Generation
Search	`search`	`{ enabled }`	Search
Collections	`collections`	`content` collection	Collections
Static embeds	`embeds.github`, `embeds.openGraph`	`true`	Embeds
Opt-in embeds	`embeds.pm`, `embeds.twitter`, `embeds.reddit`, `embeds.bluesky`, `embeds.qiita`, `embeds.zenn`, `embeds.packageRegistry`, `embeds.spotify`, `embeds.appleMusic`, `embeds.speakerDeck`, `embeds.audio`, `embeds.video`, `embeds.stackBlitz`, `embeds.webContainer`	`false`	Embeds
Syntax highlight	`highlight`	`false`	Code Blocks
Code authoring	`codeAnnotations`, `codeImports`	`false`	Code Blocks
Code groups	`codeGroups`	`false`	Code Groups
Conditional blocks	`conditionalBlocks`	`false`	Conditional Blocks
Extra syntax	`wikiLinks`, `emojiShortcodes`, `attrs`, `crossReferences` / `xrefs`, `citations`, `budoux`, `cjkEmphasis`, `containers`, `badges`, `notByAi`, `keyboardKeys`, `abbreviations`, `definitionLists`, `magicLinks`	`false`	Syntax Extensions
File includes	`includes`	`false`	File Includes
Markdown partials	`partials`	`false`	Markdown Partials
Cards	`cards`	`false`	Cards
Step lists	`steps`	`false`	Step Lists
File tree	`fileTree`	`false`	File Tree
Data tables	`dataTables`	`false`	Data Tables
Images	`images`	`false`	Images
Page resources	`resources`	`false`	Page resources
Diagrams	`mermaid`, `graphviz`	`false`	Mermaid Diagrams, Graphviz DOT Diagrams
Math	`math`	`false`	Math
OG images	`ogImage`	`false`	Site Generation
HTML safety	`sanitize`	`false`	Quality Checks
Editing links	`editThisPage`	`false`	Site Generation
Page pager	`ssg.pagination`	`false`	Previous / Next
Breadcrumbs	`ssg.breadcrumbs` / `theme.breadcrumbs`	`false`	Breadcrumbs
Page head	`renderHead`	build-time	Page head
SEO tags	`ssg.siteUrl`, frontmatter `robots` / `canonical`	off unless set	SEO
Head validation	`ssg.headValidation`	`false`	SEO
Structured data	`ssg.jsonLd`	`false`	JSON-LD
Reader chrome	`ssg.readerChrome`	`false`	Reader Chrome
Theme bootstrap	`renderThemeBootstrapScript`	public API	Theme
Locale switcher	`ssg.localeSwitcher`	`false`	Locale Switcher
Accessibility	`ssg.a11y`	`false`	Accessibility
Header chrome	`theme.nav`, `theme.announcement`, `ssg.pageChrome`	off	Header chrome
Crawl manifests	`siteMaps`	`false`	Sitemap / robots / llms.txt
Markdown source	`ssg.markdownSource`	`false`	Markdown source companions
Publish states	`publishState`	`false`	Draft / unlisted / scheduled
Permalinks	`permalinks`	`false`	Permalinks and Cascade
Frontmatter tree	`cascade`	`false`	Permalinks and Cascade
Redirects	`redirects`	`false`	Redirects and aliases
Custom 404	`ssg.notFound`	`false`	Custom 404
Collection feeds	`feeds`	`false`	RSS / Atom / JSON feeds
Blog	`blog` / `ssg.blog`	`false`	Blog
PWA	`pwa`	`false`	PWA manifest and service worker
Self-hosted icons	`icons`	`false`	Self-hosted Iconify CSS
Taxonomies	`taxonomies`	`false`	Taxonomies
Versioning	`versions`	`false`	Documentation versioning
Team page	`ssg.team`	`false`	Team / members page
Git authors	`ssg.contributors`	`false`	Git contributors
Section indexes	`ssg.sectionIndex`	`false`	Section index pages
Code checks	`codeBlockLint`, `codeBlockTypecheck`, `docsTests`	`false`	Quality Checks
Typed hover	`typedHover`	`false`	Typed Hover
Custom pipeline	`transformers`	`[]`	Site Generation

Tab groups and YouTube embeds have no option: they are always processed for SSG output and dev preview. See Embeds.

Example Configuration#

Use explicit options when a site needs non-standard behavior:

import { defineConfig } from "vite-plus";
import { oxContent } from "@ox-content/vite-plugin";

export default defineConfig({
  plugins: [
    oxContent({
      highlight: true,
      emojiShortcodes: true,
      codeAnnotations: {
        notation: "both",
      },
      embeds: {
        pm: { sync: true },
        twitter: { fetch: true },
        bluesky: true,
      },
    }),
  ],
});

Every option follows the same convention: false disables the feature, true enables it with defaults, and an object enables it while overriding only the fields you set.

Copyable source snippets for the authoring forms live in examples/builtin-features/content/, and the pages under Examples show several features in runnable projects.