Skip to content

Commit 0e720ab

Browse files
ubugeeeiclaude
ubugeeei
and
claude
authored
docs: expand built-in features into per-feature guides with live examples (#527)
* docs: expand built-in features into per-feature guides with live examples Split the single built-in-features page into eight detailed guides (markdown baseline, syntax extensions, code blocks, embeds, mermaid, search, quality checks, site generation) under docs/content/built-in/, each with configuration examples, accurate option/default tables, and rendered examples embedded live on the page. Enable emojiShortcodes, cjkEmphasis, codeImports, and the twitter and bluesky embeds on the docs site so the guides can dogfood them inline (wikiLinks and attrs stay off: both also rewrite [[...]]/{...} inside raw HTML <code> emitted by the generated API reference). Add search modal / OG viewer screenshots and this site's own generated OG image as figures, a snippets/ file backing the code-import demos, and a nested sidebar group for the new pages. Also rework the code-imports example page to stop authoring <<< inside fences (the reference resolves there too, now that codeImports is on) and correct details the old page got wrong: tabs/youtube have no embeds option and are always processed for SSG/dev, editThisPage requires repoUrl, and the default embeds are github + openGraph. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: apply vp fmt to the built-in feature guides Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 99ef4de commit 0e720ab

16 files changed

Lines changed: 1521 additions & 178 deletions

‎docs/content/built-in-features.md‎

Lines changed: 48 additions & 168 deletions
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,50 @@ fast static baseline: parsing, static embeds, source docs, and search indexing
1313
run during transform or build, while extra syntax and runtime behavior must be
1414
enabled explicitly.
1515

16+
This documentation site is built with Ox Content, so the feature guides below
17+
do not just describe each feature — they enable it and **render live examples
18+
inline**.
19+
20+
## Feature Guides
21+
22+
| Guide | Covers |
23+
| ---------------------------------------------------- | ------------------------------------------------------------------------- |
24+
| [Markdown Baseline](./built-in/markdown.md) | GFM, tables, task lists, footnotes, autolinks, frontmatter, TOC |
25+
| [Syntax Extensions](./built-in/syntax-extensions.md) | Emoji shortcodes, wiki links, attribute syntax, CJK emphasis |
26+
| [Code Blocks](./built-in/code-blocks.md) | Syntax highlighting, code annotations, code imports |
27+
| [Embeds](./built-in/embeds.md) | GitHub cards, OG cards, package-manager tabs, tabs, YouTube, social cards |
28+
| [Mermaid Diagrams](./built-in/mermaid.md) | Diagram fences rendered to static SVG |
29+
| [Search](./built-in/search.md) | The static BM25 index and client search API |
30+
| [Quality Checks](./built-in/quality-checks.md) | Code block lint, type checking, docs tests, HTML sanitizer |
31+
| [Site Generation](./built-in/site-generation.md) | SSG, OG images, edit links, collections, API docs, transformers |
32+
1633
## Default vs Opt-in
1734

18-
| Area | Option | Default | Notes |
19-
| ---------------- | ----------------------------------------------------------------------- | ------------- | --------------------------------------------------- |
20-
| Markdown base | `gfm`, `footnotes`, `tables`, `taskLists`, `strikethrough`, `autolinks` | `true` | Common GitHub-flavored Markdown behavior. |
21-
| Page metadata | `frontmatter` | `true` | Parses YAML frontmatter before rendering. |
22-
| Navigation | `toc`, `tocMaxDepth` | `true`, `3` | Builds a page table of contents from headings. |
23-
| Static site | `ssg` | `{ enabled }` | Generates static HTML pages during build. |
24-
| API docs | `docs` | `{ enabled }` | Generates package API docs unless set to `false`. |
25-
| Search | `search` | `{ enabled }` | Builds a static BM25 index for client-side search. |
26-
| Collections | `collections` | `{ content }` | Rust-native lazy query manifest for Markdown files. |
27-
| Syntax highlight | `highlight` | `false` | Opt in when the site needs highlighted code blocks. |
28-
| OG images | `ogImage` | `false` | Opt in because image rendering adds build work. |
29-
| Extra syntax | `wikiLinks`, `emojiShortcodes`, `attrs`, `codeImports`, `cjkEmphasis` | `false` | Non-standard authoring features are opt-in. |
30-
| HTML safety | `sanitize` | `false` | Opt in when rendering untrusted or mixed HTML. |
31-
| Editing links | `editThisPage` | `false` | Opt in with a repository URL. |
32-
| Code checks | `codeAnnotations`, `codeBlockLint`, `codeBlockTypecheck`, `docsTests` | `false` | Opt in per documentation workflow. |
33-
| Diagrams | `mermaid` | `false` | Opt in for diagram rendering. |
34-
| Custom pipeline | `transformers` | `[]` | Add project-specific Markdown AST transforms. |
35+
| Area | Option | Default | Guide |
36+
| ---------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------- |
37+
| Markdown base | `gfm`, `footnotes`, `tables`, `taskLists`, `strikethrough`, `autolinks` | `true` | [Markdown Baseline](./built-in/markdown.md) |
38+
| Page metadata | `frontmatter` | `true` | [Markdown Baseline](./built-in/markdown.md) |
39+
| Navigation | `toc`, `tocMaxDepth` | `true`, `3` | [Markdown Baseline](./built-in/markdown.md) |
40+
| Static site | `ssg` | `{ enabled }` | [Site Generation](./built-in/site-generation.md) |
41+
| API docs | `docs` | `{ enabled }` | [Site Generation](./built-in/site-generation.md) |
42+
| Search | `search` | `{ enabled }` | [Search](./built-in/search.md) |
43+
| Collections | `collections` | `content` collection | [Site Generation](./built-in/site-generation.md) |
44+
| Static embeds | `embeds.github`, `embeds.openGraph` | `true` | [Embeds](./built-in/embeds.md) |
45+
| Opt-in embeds | `embeds.pm`, `embeds.twitter`, `embeds.bluesky`, `embeds.spotify`, `embeds.stackBlitz`, `embeds.webContainer` | `false` | [Embeds](./built-in/embeds.md) |
46+
| Syntax highlight | `highlight` | `false` | [Code Blocks](./built-in/code-blocks.md) |
47+
| Code authoring | `codeAnnotations`, `codeImports` | `false` | [Code Blocks](./built-in/code-blocks.md) |
48+
| Extra syntax | `wikiLinks`, `emojiShortcodes`, `attrs`, `cjkEmphasis` | `false` | [Syntax Extensions](./built-in/syntax-extensions.md) |
49+
| Diagrams | `mermaid` | `false` | [Mermaid Diagrams](./built-in/mermaid.md) |
50+
| OG images | `ogImage` | `false` | [Site Generation](./built-in/site-generation.md) |
51+
| HTML safety | `sanitize` | `false` | [Quality Checks](./built-in/quality-checks.md) |
52+
| Editing links | `editThisPage` | `false` | [Site Generation](./built-in/site-generation.md) |
53+
| Code checks | `codeBlockLint`, `codeBlockTypecheck`, `docsTests` | `false` | [Quality Checks](./built-in/quality-checks.md) |
54+
| Custom pipeline | `transformers` | `[]` | [Site Generation](./built-in/site-generation.md) |
55+
56+
Tab groups and YouTube embeds have no option: they are always processed for
57+
SSG output and dev preview. See [Embeds](./built-in/embeds.md#tabs).
58+
59+
## Example Configuration
3560

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

@@ -57,155 +82,10 @@ export default defineConfig({
5782
});
5883
```
5984

60-
## Emoji Shortcodes
61-
62-
Emoji shortcode expansion is opt-in:
63-
64-
```ts
65-
oxContent({
66-
emojiShortcodes: true,
67-
});
68-
```
69-
70-
The built-in table covers hundreds of common GitHub-style aliases such as
71-
`:rocket:`, `:white_check_mark:`, `:warning:`, `:smile:`, and `:thinking:`.
72-
Shortcodes expand outside fenced and inline code. Unknown shortcodes are left
73-
unchanged.
74-
75-
Custom values override the built-in table:
76-
77-
```ts
78-
oxContent({
79-
emojiShortcodes: {
80-
custom: {
81-
shipit: "ship it",
82-
},
83-
},
84-
});
85-
```
86-
87-
See [Emoji Shortcodes](./examples/emoji-shortcodes.md) for a rendered example.
88-
89-
## Code Annotations
90-
91-
Code annotations are opt-in so ordinary code fences stay literal unless a site
92-
chooses annotation syntax:
93-
94-
```ts
95-
oxContent({
96-
highlight: true,
97-
codeAnnotations: {
98-
notation: "both",
99-
},
100-
});
101-
```
102-
103-
The default notation is the configurable attribute syntax:
104-
105-
````md
106-
```ts annotate="highlight:1,3;warning:5;error:8"
107-
const value = load();
108-
console.warn(value);
109-
throw new Error("stop");
110-
```
111-
````
112-
113-
`notation: "vitepress"` enables VitePress-compatible fence metadata and inline
114-
comments. `notation: "both"` enables both syntaxes.
115-
116-
Use a standalone escape comment when the next line should render literally even
117-
if it contains annotation-looking text:
118-
119-
````md
120-
```ts
121-
// [!code escape]
122-
console.warn("literal"); // [!code warning]
123-
console.warn("annotated"); // [!code warning]
124-
```
125-
````
126-
127-
The escape directive is removed from the rendered block, and only the next line
128-
is escaped.
129-
130-
See [Code Annotations](./examples/code-annotations.md) for the complete syntax.
131-
132-
## Built-in Embeds
133-
134-
`embeds.github` and `embeds.openGraph` are enabled by default because they render
135-
static HTML at transform time. Non-standard or runtime-heavy embeds are opt-in.
136-
137-
| Embed | Default | Authoring form | Runtime behavior |
138-
| ----------------------------- | ------- | ---------------------------------- | ----------------------------------------- |
139-
| GitHub repository/source card | `true` | `<GitHub repo="owner/name" />` | Static HTML generated during transform. |
140-
| Open Graph link card | `true` | `<OgCard url="https://..." />` | Static HTML generated during transform. |
141-
| Package manager tabs | `false` | `<pm>npm install package</pm>` | Static HTML; sync mode adds small JS. |
142-
| Spotify | `false` | `<Spotify url="https://..." />` | Iframe embed. |
143-
| StackBlitz | `false` | `<StackBlitz url="https://..." />` | Iframe embed. |
144-
| Twitter/X | `false` | `<Tweet />` or `<XPost />` | Static privacy-conscious card. |
145-
| Bluesky | `false` | `<Bluesky />` | Static card. |
146-
| WebContainer | `false` | `<WebContainer />` | Lazy placeholder with isolation metadata. |
147-
148-
Disable every built-in embed with `embeds: false`, or configure only the embeds
149-
your site needs:
150-
151-
```ts
152-
oxContent({
153-
embeds: {
154-
github: {
155-
token: process.env.GITHUB_TOKEN,
156-
maxSourceLines: 120,
157-
},
158-
openGraph: {
159-
timeout: 5000,
160-
},
161-
pm: true,
162-
},
163-
});
164-
```
165-
166-
Copyable source snippets for these forms live in
167-
`examples/builtin-features/content/`.
168-
169-
## Mermaid Diagrams
170-
171-
Mermaid rendering is opt-in:
172-
173-
```ts
174-
oxContent({
175-
mermaid: true,
176-
});
177-
```
178-
179-
See `examples/builtin-features/content/mermaid-diagram.md` for a small diagram
180-
source.
181-
182-
## Search Index
183-
184-
Search is enabled by default for SSG builds. Configure or disable it explicitly:
185-
186-
```ts
187-
oxContent({
188-
search: {
189-
limit: 8,
190-
hotkey: "/",
191-
},
192-
});
193-
```
194-
195-
See `examples/builtin-features/client/search.ts` for the virtual module import.
196-
197-
## Code Quality Hooks
198-
199-
Documentation-specific checks are also opt-in:
200-
201-
| Option | Default | Use when... |
202-
| -------------------- | ------- | -------------------------------------------------------------- |
203-
| `codeBlockLint` | `false` | Code fences should require languages or reject trailing space. |
204-
| `codeBlockTypecheck` | `false` | TypeScript or TSX fences should be checked with `tsgo`. |
205-
| `docsTests` | `false` | Runnable fences should be extracted for a Vitest harness. |
206-
| `sanitize` | `false` | Raw or third-party HTML should be cleaned before rendering. |
207-
| `codeImports` | `false` | Markdown should import checked source snippets from files. |
85+
Every option follows the same convention: `false` disables the feature, `true`
86+
enables it with defaults, and an object enables it while overriding only the
87+
fields you set.
20888

209-
The feature pages under [Examples](./examples/index.md) and the snippets under
210-
`examples/builtin-features/` show each hook in isolation, so a site can enable
211-
only the pieces it actually uses.
89+
Copyable source snippets for the authoring forms live in
90+
`examples/builtin-features/content/`, and the pages under
91+
[Examples](./examples/index.md) show several features in runnable projects.

0 commit comments

Comments
 (0)