From 841d30975c381218cac250187083cb36aee539df Mon Sep 17 00:00:00 2001
From: Ilya Rodin <ilya@rodin.dev>
Date: Wed, 10 Jun 2026 18:03:13 +0700
Subject: [PATCH] docs: merge readme positioning and drop em-dashes

---
 CONTRIBUTING.md                    | 12 ++++++------
 README.md                          | 30 ++++++++++++------------------
 docs/api/mock/index.md             |  2 +-
 docs/api/petstore/index.md         |  6 +++---
 docs/guide/authentication.md       | 20 ++++++++++----------
 docs/guide/comparison.md           |  8 ++++----
 docs/guide/composing-endpoints.md  | 16 ++++++++--------
 docs/guide/existing-site.md        |  2 +-
 docs/guide/multiple-apis.md        |  2 +-
 docs/guide/theming.md              | 12 ++++++------
 docs/index.md                      |  6 +++---
 docs/reference/components.md       | 20 ++++++++++----------
 docs/reference/configuration.md    |  8 ++++----
 docs/troubleshooting.md            | 14 +++++++-------
 packages/create/template/README.md | 10 +++++-----
 15 files changed, 81 insertions(+), 87 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5b2f0a3..56ad21c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,8 +4,8 @@
 
 ```
 packages/
-  core/       # vitepress-openapi-docs — Vue components + VitePress plugin
-  create/     # create-vitepress-openapi-docs — scaffolder CLI
+  core/       # vitepress-openapi-docs: Vue components + VitePress plugin
+  create/     # create-vitepress-openapi-docs: scaffolder CLI
 docs/         # VitePress dogfood site
 e2e/          # Playwright tests (a11y + happy-path)
 scripts/      # Release helpers
@@ -64,14 +64,14 @@ npm run test:a11y
 
 ## Commit conventions
 
-- **Conventional commits** — `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, `refactor:`, `perf:`
+- **Conventional commits**: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, `refactor:`, `perf:`
 - Keep commits focused: one concern per commit
 - No `Co-Authored-By` trailers
 
 ## Release flow
 
-1. `node scripts/sync-versions.js <version>` — sync all packages
-2. Update `CHANGELOG.md` — rename the `Unreleased` heading to `## <version>`
+1. `node scripts/sync-versions.js <version>` to sync all packages
+2. Update `CHANGELOG.md`: rename the `Unreleased` heading to `## <version>`
 3. Commit: `chore(release): v<version>`
 4. Tag: `git tag v<version>`
 5. Push: `git push origin main --tags`
@@ -79,7 +79,7 @@ npm run test:a11y
 
 ## Code style
 
-- TypeScript strict — no `any`
+- TypeScript strict, no `any`
 - Single quotes, no semicolons (Prettier)
 - Vue SFC order: `<template>`, `<script setup lang="ts">`
 - CSS classes: BEM with `vod-` prefix
diff --git a/README.md b/README.md
index 8661ee8..4441eea 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,9 @@ A Vue-native VitePress plugin that composes OpenAPI endpoints inline with your m
 
 ## Why this exists
 
-Scalar, RapiDoc, Stoplight Elements — they render API docs inside web components or iframes. They work, but you can't put a paragraph between two endpoints. You can't style them with your VitePress CSS variables. They're embedded apps, not documentation.
+Swagger UI, Scalar, RapiDoc, Stoplight Elements all render API docs inside a web component or iframe. They work, but the output is a standalone widget: you can't put a paragraph between two endpoints, and you can't style it with your VitePress CSS variables.
 
-This plugin is different:
+This plugin renders endpoints as Vue components in light DOM, so they compose inline with your markdown prose:
 
 ```md
 # Authentication
@@ -24,7 +24,7 @@ Then use the token on subsequent calls:
 <OpenApiEndpoint id="users.list" auth="bearer" />
 ```
 
-Endpoints render natively in VitePress — light DOM, Vue components, same theme.
+On top of that you get a full docs site, not just a widget: auto-generated pages, Cmd+K search, schema cross-links, a git-driven changelog, and multi-API support with independent sidebars. SDK snippets refresh as you change the auth token, and auth persists across pages.
 
 ## Install
 
@@ -39,26 +39,20 @@ Or add to an existing VitePress site:
 npm i vitepress-openapi-docs vue-api-playground
 ```
 
-Two files to wire up — [full guide](https://rodindev.github.io/vitepress-openapi-docs/guide/existing-site).
+Two files to wire up. See the [full guide](https://rodindev.github.io/vitepress-openapi-docs/guide/existing-site).
 
 ## What's included
 
-- **`<OpenApiEndpoint>`** — one operation inline in any markdown page: params, request/response types, SDK snippets, try-it panel, auth
-- **`<OpenApiSpec>`** — full spec grouped by tag
-- **`<OpenApiSchema>`** — property table with clickable `$ref` links
-- **`<OpenApiChangelog>`** — git-history-driven spec diff (added/removed/renamed operations per commit)
-- **Cmd+K jumper** — fuzzy search across all operations and schemas
-- **Multi-API** — N specs, one config, independent sidebar per spec, one jumper
-- **Auth** — bearer / basic / apikey / OAuth2 passthrough, stored in sessionStorage
-- **Syntax highlighting** - SDK snippets and response JSON share a VS Code Default palette via vue-api-playground tokens; no Prism or Shiki dependency
+- **`<OpenApiEndpoint>`**: one operation inline in any markdown page: params, request/response types, SDK snippets, try-it panel, auth
+- **`<OpenApiSpec>`**: full spec grouped by tag
+- **`<OpenApiSchema>`**: property table with clickable `$ref` links
+- **`<OpenApiChangelog>`**: git-history-driven spec diff (added/removed/renamed operations per commit)
+- **Cmd+K jumper**: fuzzy search across all operations and schemas
+- **Multi-API**: N specs, one config, independent sidebar per spec, one jumper
+- **Auth**: bearer / basic / apikey / OAuth2 passthrough, stored in sessionStorage
+- **Syntax highlighting**: SDK snippets and response JSON share a VS Code Default palette via vue-api-playground tokens; no Prism or Shiki dependency
 - **< 14 KB** client bundle (peer deps excluded), enforced in CI
 
-## Why this over Swagger UI or Scalar
-
-Swagger UI is heavy and looks dated. Scalar is modern but renders inside a web component — a black box you can't mix with your own content. Both give you a standalone widget, not documentation.
-
-This gives you a full docs site: auto-generated pages, Cmd+K search, schema cross-links, git-driven changelog, multi-API with independent sidebars. SDK snippets that update with your auth token. Auth that persists across pages. And one thing no other tool does: endpoints that compose inline with your markdown prose.
-
 ## Requirements
 
 - Node.js >= 20
diff --git a/docs/api/mock/index.md b/docs/api/mock/index.md
index 8be6059..d1fdd0b 100644
--- a/docs/api/mock/index.md
+++ b/docs/api/mock/index.md
@@ -8,6 +8,6 @@ aside: false
 
 The live reference demo for `vitepress-openapi-docs`, backed by a mock server at [api.rodin.dev/mock](https://api.rodin.dev/mock/). OpenAPI 3.1, 107 operations across 15 tags, 34 webhooks, bearer auth, callbacks, `oneOf`, rich examples: everything the plugin renders, rendered here.
 
-Pick any operation from the sidebar and hit **Try-It** — the request goes to the real origin, CORS is open, you get real JSON back. The spec is fetched at build time so this page mirrors the live contract.
+Pick any operation from the sidebar and hit **Try-It**: the request goes to the real origin, CORS is open, you get real JSON back. The spec is fetched at build time so this page mirrors the live contract.
 
 <OpenApiSpec name="mock" :show-header="false" />
diff --git a/docs/api/petstore/index.md b/docs/api/petstore/index.md
index 3035a60..9436d69 100644
--- a/docs/api/petstore/index.md
+++ b/docs/api/petstore/index.md
@@ -1,13 +1,13 @@
 ---
 title: Petstore API
-description: The classic Swagger Petstore rendered by vitepress-openapi-docs — 19 operations, three tags, full interactivity.
+description: The classic Swagger Petstore rendered by vitepress-openapi-docs. 19 operations, three tags, full interactivity.
 aside: false
 ---
 
 # Petstore API
 
-The canonical [Swagger Petstore](https://petstore3.swagger.io/) spec rendered as a second API alongside the [Mock API](/api/mock/). Demonstrates multi-API support — each spec gets its own sidebar, search index, and URL prefix.
+The canonical [Swagger Petstore](https://petstore3.swagger.io/) spec rendered as a second API alongside the [Mock API](/api/mock/). Demonstrates multi-API support: each spec gets its own sidebar, search index, and URL prefix.
 
-Pick any operation from the sidebar and hit **Try-It** — requests go to `petstore3.swagger.io`, CORS is open.
+Pick any operation from the sidebar and hit **Try-It**: requests go to `petstore3.swagger.io`, CORS is open.
 
 <OpenApiSpec name="petstore" :show-header="false" />
diff --git a/docs/guide/authentication.md b/docs/guide/authentication.md
index 336ef83..6076c23 100644
--- a/docs/guide/authentication.md
+++ b/docs/guide/authentication.md
@@ -1,5 +1,5 @@
 ---
-description: How authentication works in vitepress-openapi-docs — bearer, basic, API key, and OAuth2.
+description: How authentication works in vitepress-openapi-docs with bearer, basic, API key, and OAuth2.
 ---
 
 # Authentication
@@ -20,10 +20,10 @@ description: How authentication works in vitepress-openapi-docs — bearer, basi
 1. The parser reads `components.securitySchemes` from your spec
 2. Each operation's `security` array references a scheme by name
 3. `<OpenApiEndpoint>` resolves the scheme type and renders `<AuthControls>`
-4. The user enters a credential — stored in `sessionStorage` under `vod:auth:{specName}`
+4. The user enters a credential, stored in `sessionStorage` under `vod:auth:{specName}`
 5. The credential auto-injects into:
-   - **SDK snippets** (curl, fetch, Python) — visible and copy-pasteable
-   - **Try-It panel** — via the `before-send` hook
+   - **SDK snippets** (curl, fetch, Python): visible and copy-pasteable
+   - **Try-It panel**: via the `before-send` hook
 
 ## Session storage
 
@@ -33,7 +33,7 @@ Credentials persist across SPA navigation within the same tab. They clear when:
 - The browser tab is closed
 - `sessionStorage` is cleared
 
-Each spec has its own credential store — setting auth on one API doesn't affect another.
+Each spec has its own credential store; setting auth on one API doesn't affect another.
 
 ## Override per endpoint
 
@@ -82,12 +82,12 @@ The scheme's `in` field decides where the key goes:
 
 For `oauth2` schemes, the plugin renders:
 
-- **Authorization URL** — clickable link
-- **Token URL** — shown for reference
-- **Scopes** — collapsible list with descriptions
-- **Token paste input** — paste the token obtained from the OAuth2 flow
+- **Authorization URL**: clickable link
+- **Token URL**: shown for reference
+- **Scopes**: collapsible list with descriptions
+- **Token paste input**: paste the token obtained from the OAuth2 flow
 
-The pasted token is injected as a `Bearer` token in snippets and Try-It. This is a passthrough — the plugin does not perform the OAuth2 redirect flow itself.
+The pasted token is injected as a `Bearer` token in snippets and Try-It. This is a passthrough; the plugin does not perform the OAuth2 redirect flow itself.
 
 ```yaml
 components:
diff --git a/docs/guide/comparison.md b/docs/guide/comparison.md
index eedeb00..9f5674c 100644
--- a/docs/guide/comparison.md
+++ b/docs/guide/comparison.md
@@ -8,7 +8,7 @@ How `vitepress-openapi-docs` differs from other OpenAPI documentation tools.
 
 ## vs. vitepress-openapi
 
-`vitepress-openapi` is the closest peer — also Vue-native, also a VitePress plugin. The data model is similar; the composition story and scope are what differ.
+`vitepress-openapi` is the closest peer: also Vue-native, also a VitePress plugin. The data model is similar; the composition story and scope are what differ.
 
 ### Config
 
@@ -47,8 +47,8 @@ export default defineConfig({
 | `<OASpec />`                        | `<OpenApiSpec name="..." />`                                          |
 | (per-spec sidebar helper)           | auto-generated via `openApiDocs()`                                    |
 | (schemas shown inline)              | `<OpenApiSchema name="..." spec-name="..." />` + auto-generated pages |
-| —                                   | `<OpenApiChangelog name="..." />`                                     |
-| —                                   | Cmd+K search via `<OperationJumper />`                                |
+| (not included)                      | `<OpenApiChangelog name="..." />`                                     |
+| (not included)                      | Cmd+K search via `<OperationJumper />`                                |
 
 ### What's different
 
@@ -76,7 +76,7 @@ Scalar gives you a self-contained widget that works anywhere. `vitepress-openapi
 If you're moving from either tool:
 
 1. Install: `npm i vitepress-openapi-docs vue-api-playground`
-2. Set up config and theme — see [existing site guide](/guide/existing-site)
+2. Set up config and theme; see [existing site guide](/guide/existing-site)
 3. Replace component tags: `<OAOperation>` / `<ApiReference>` → `<OpenApiEndpoint>` / `<OpenApiSpec>`
 4. Add `docs/_openapi/` to `.gitignore`
 5. Run `npm run dev`
diff --git a/docs/guide/composing-endpoints.md b/docs/guide/composing-endpoints.md
index 80a88f9..4997d29 100644
--- a/docs/guide/composing-endpoints.md
+++ b/docs/guide/composing-endpoints.md
@@ -4,7 +4,7 @@ description: Embed interactive API endpoints inline with your markdown prose.
 
 # Composing endpoints
 
-The plugin registers components globally — use them directly in any markdown file.
+The plugin registers components globally; use them directly in any markdown file.
 
 ## Inline endpoints
 
@@ -22,7 +22,7 @@ Use the token on subsequent calls:
 <OpenApiEndpoint id="api.users.list" />
 ```
 
-The endpoint renders natively in the page — light DOM, Vue components, VitePress routing.
+The endpoint renders natively in the page: light DOM, Vue components, VitePress routing.
 
 ## The `id` format
 
@@ -79,13 +79,13 @@ Render a component schema with property table, required badges, and clickable `$
 
 ## Changelog
 
-Show a git-history-driven spec diff — added, removed, and renamed operations per commit:
+Show a git-history-driven spec diff of added, removed, and renamed operations per commit:
 
 ```md
 <OpenApiChangelog name="public" />
 ```
 
-The changelog needs at least two commits touching the spec file. In CI, set `fetch-depth: 0` — shallow clones have no history. Remote URL specs don't support changelog.
+The changelog needs at least two commits touching the spec file. In CI, set `fetch-depth: 0` (shallow clones have no history). Remote URL specs don't support changelog.
 
 ## Webhooks
 
@@ -122,8 +122,8 @@ See [Components reference](/reference/components#searchtrigger) for props.
 
 For each spec, the plugin generates:
 
-- `/{prefix}/{operationId}` — one page per operation
-- `/schemas/{specName}/{typeName}` — one page per named component schema
-- `/changelog/{specName}` — spec change history
+- `/{prefix}/{operationId}` for one page per operation
+- `/schemas/{specName}/{typeName}` for one page per named component schema
+- `/changelog/{specName}` for spec change history
 
-Hand-written landing pages (`/{prefix}/index.md`) coexist — the generator only writes to `docs/_openapi/`.
+Hand-written landing pages (`/{prefix}/index.md`) coexist; the generator only writes to `docs/_openapi/`.
diff --git a/docs/guide/existing-site.md b/docs/guide/existing-site.md
index 93e5faa..fddad58 100644
--- a/docs/guide/existing-site.md
+++ b/docs/guide/existing-site.md
@@ -73,7 +73,7 @@ title: API Reference
 <OpenApiSpec name="api" />
 ```
 
-`<OpenApiSpec>` renders every operation from the spec in a single scrollable page — a good default for the landing. You can also hand-write prose around individual `<OpenApiEndpoint>` embeds instead; see [Composing endpoints](/guide/composing-endpoints).
+`<OpenApiSpec>` renders every operation from the spec in a single scrollable page, a good default for the landing. You can also hand-write prose around individual `<OpenApiEndpoint>` embeds instead; see [Composing endpoints](/guide/composing-endpoints).
 
 ::: tip
 The scaffolder (`npm create vitepress-openapi-docs@latest`) creates this file automatically. This step only applies when integrating into an existing site.
diff --git a/docs/guide/multiple-apis.md b/docs/guide/multiple-apis.md
index c475098..0b3e836 100644
--- a/docs/guide/multiple-apis.md
+++ b/docs/guide/multiple-apis.md
@@ -53,7 +53,7 @@ Always prefix the `operationId` with the spec name:
 
 ## Landing pages
 
-The plugin doesn't generate landing pages — write them yourself:
+The plugin doesn't generate landing pages; write them yourself:
 
 ```md
 <!-- docs/api/public/index.md -->
diff --git a/docs/guide/theming.md b/docs/guide/theming.md
index 24c299e..43d74cf 100644
--- a/docs/guide/theming.md
+++ b/docs/guide/theming.md
@@ -4,7 +4,7 @@ description: Customize the look of vitepress-openapi-docs with CSS variables.
 
 # Theming
 
-`vitepress-openapi-docs` themes through a three-layer CSS variable cascade. Override at any level — lower layers stay as fallbacks.
+`vitepress-openapi-docs` themes through a three-layer CSS variable cascade. Override at any level; lower layers stay as fallbacks.
 
 ## The cascade
 
@@ -16,9 +16,9 @@ description: Customize the look of vitepress-openapi-docs with CSS variables.
 
 Each layer falls back to the next. Override whichever layer you want; everything below stays as a default.
 
-- **`--vod-*`** — the public surface. Override these to restyle the plugin's UI.
-- **`--vap-*`** — shipped by `vue-api-playground`. Inherited so both packages stay in sync.
-- **`--vp-c-*`** — VitePress's standard tokens. Most sites already theme through these.
+- **`--vod-*`** - the public surface. Override these to restyle the plugin's UI.
+- **`--vap-*`** - shipped by `vue-api-playground`. Inherited so both packages stay in sync.
+- **`--vp-c-*`** - VitePress's standard tokens. Most sites already theme through these.
 - The hex fallback is only reached outside a VitePress host.
 
 Not every token chains. The method badge `-bg` / `-text` tokens (`--vod-method-get-bg`, `--vod-method-delete-text`, and the rest) are flat hex by design: each light and dark pair is tuned for AA contrast, so they do not fall through `--vap-*` or `--vp-c-*`. Override the pair directly if you need to retint a badge.
@@ -29,14 +29,14 @@ Drop these into a stylesheet imported after the plugin styles in your [theme set
 
 ```css
 :root {
-  /* Method accents — borders, tab indicators, text highlights */
+  /* Method accents: borders, tab indicators, text highlights */
   --vod-method-get: #2563eb;
   --vod-method-post: #16a34a;
   --vod-method-put: #d97706;
   --vod-method-patch: #8b5cf6;
   --vod-method-delete: #dc2626;
 
-  /* Method badges — the pill-shaped labels (e.g. GET, POST) */
+  /* Method badges: the pill-shaped labels (e.g. GET, POST) */
   --vod-method-get-bg: #dcfce7;
   --vod-method-get-text: #166534;
   --vod-method-post-bg: #dbeafe;
diff --git a/docs/index.md b/docs/index.md
index 55c92fe..ac0d52d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,7 +2,7 @@
 layout: home
 title: VitePress OpenAPI Docs
 titleTemplate: Interactive OpenAPI docs for VitePress
-description: Drop interactive OpenAPI 3.x endpoints anywhere in your markdown. Vue-native VitePress plugin — no shadow DOM, no iframes. Multi-API, SDK snippets, auth, git-driven changelog.
+description: Drop interactive OpenAPI 3.x endpoints anywhere in your markdown. Vue-native VitePress plugin with no shadow DOM and no iframes. Multi-API, SDK snippets, auth, git-driven changelog.
 
 hero:
   text: VitePress OpenAPI Docs
@@ -35,7 +35,7 @@ Or [add to an existing VitePress site](/guide/existing-site).
 
 ## What you get
 
-- **Inline composition** — endpoints render as Vue components in light DOM. Weave them into tutorials, drop them between paragraphs, theme them with VitePress CSS variables.
-- **Multiple APIs** — array of specs, each with its own sidebar, URL prefix, and search index.
+- **Inline composition** - endpoints render as Vue components in light DOM. Weave them into tutorials, drop them between paragraphs, theme them with VitePress CSS variables.
+- **Multiple APIs** - array of specs, each with its own sidebar, URL prefix, and search index.
 - **Auth and SDK snippets** - bearer / basic / API key / OAuth2 with session persistence. curl / fetch / Python snippets with syntax highlighting, refreshed live as credentials change.
 - **< {{ $facts.bundleBudget }} client bundle** - peer dependencies (Vue, VitePress, vue-api-playground) excluded.
diff --git a/docs/reference/components.md b/docs/reference/components.md
index db48d56..2f4e1b9 100644
--- a/docs/reference/components.md
+++ b/docs/reference/components.md
@@ -4,7 +4,7 @@ description: Props, events, and types for every component in vitepress-openapi-d
 
 # Components
 
-All components are globally registered by `enhanceAppWithOpenApi()` — use them directly in any markdown file. See [Composing endpoints](/guide/composing-endpoints) for usage patterns.
+All components are globally registered by `enhanceAppWithOpenApi()`; use them directly in any markdown file. See [Composing endpoints](/guide/composing-endpoints) for usage patterns.
 
 ## `<OpenApiEndpoint>`
 
@@ -19,7 +19,7 @@ Renders one operation inline with prose.
 | Prop               | Type                                                    | Default         | Description                                                                                                                                              |
 | ------------------ | ------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `id`               | `string`                                                | (required)      | `{specName}.{operationId}` for multi-spec, or bare `{operationId}` with one spec.                                                                        |
-| `operation`        | `ParsedOperation`                                       | —               | Pass a parsed operation directly to bypass the registry. Pair with `specName` to resolve auth and schema links; without it the spec reports as `inline`. |
+| `operation`        | `ParsedOperation`                                       | none            | Pass a parsed operation directly to bypass the registry. Pair with `specName` to resolve auth and schema links; without it the spec reports as `inline`. |
 | `servers`          | `string[]`                                              | `[]`            | Server URL list to draw from when `operation` is supplied directly.                                                                                      |
 | `auth`             | `'none' \| 'bearer' \| 'apikey' \| 'basic' \| 'oauth2'` | auto from spec  | Override the auth scheme.                                                                                                                                |
 | `server`           | `string`                                                | first from spec | Single-server URL override.                                                                                                                              |
@@ -31,7 +31,7 @@ Renders one operation inline with prose.
 
 **Section names:** `summary`, `description`, `params`, `request`, `response`, `auth`, `snippets`, `try`.
 
-**Layout note:** In `columns` (default) the aside lives inside the endpoint container. On pages where VitePress renders a right-side TOC (`aside` frontmatter is not `false`), the aside stacks below the card instead — set `aside: false` in the page's frontmatter so the endpoint aside has room. Viewports at 1279px and below automatically fall back to the `stacked` layout regardless of the `layout` setting.
+**Layout note:** In `columns` (default) the aside lives inside the endpoint container. On pages where VitePress renders a right-side TOC (`aside` frontmatter is not `false`), the aside stacks below the card instead, so set `aside: false` in the page's frontmatter to give the endpoint aside room. Viewports at 1279px and below automatically fall back to the `stacked` layout regardless of the `layout` setting.
 
 **Stacked layout collapsing:** In `stacked`, Parameters and Response examples are wrapped in `<details>` collapsed by default. Code examples and Authentication are `<details>` in the Try-It panel in both layouts (in `columns` they sit in the aside). The Try-It panel itself stays open as the primary call to action.
 
@@ -53,11 +53,11 @@ Renders every operation in a spec, grouped by tag.
 <OpenApiSpec name="public" />
 ```
 
-| Prop          | Type                     | Default | Description                                                                                 |
-| ------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
-| `name`        | `string`                 | —       | Spec name from your config.                                                                 |
-| `show-header` | `boolean`                | `true`  | Render the spec title and description block.                                                |
-| `layout`      | `'columns' \| 'stacked'` | inherit | Card layout forwarded to every rendered endpoint. Defaults to the plugin `defaults.layout`. |
+| Prop          | Type                     | Default    | Description                                                                                 |
+| ------------- | ------------------------ | ---------- | ------------------------------------------------------------------------------------------- |
+| `name`        | `string`                 | (required) | Spec name from your config.                                                                 |
+| `show-header` | `boolean`                | `true`     | Render the spec title and description block.                                                |
+| `layout`      | `'columns' \| 'stacked'` | inherit    | Card layout forwarded to every rendered endpoint. Defaults to the plugin `defaults.layout`. |
 
 ## `<OpenApiSchema>`
 
@@ -94,7 +94,7 @@ The changelog needs real git history. Add `fetch-depth: 0` to your CI checkout s
 
 ## `<AuthControls>`
 
-Auth input for a single spec. Normally rendered by `<OpenApiEndpoint>` — use standalone when building custom layouts.
+Auth input for a single spec. Normally rendered by `<OpenApiEndpoint>`; use standalone when building custom layouts.
 
 ```md
 <AuthControls spec-name="public" scheme="bearer" />
@@ -184,7 +184,7 @@ interface SnippetRequest {
 
 ### `useAuthState()`
 
-Reactive auth state for a spec (advanced — for custom layouts):
+Reactive auth state for a spec (advanced, for custom layouts):
 
 ```ts
 import { useAuthState, readStoredCredential } from 'vitepress-openapi-docs'
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 44e7045..1a1e8dc 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -63,7 +63,7 @@ openApiDocs({
 | -------------- | ------------------------------------------------------------------ | ----------------------------------- |
 | `methodColors` | `Partial<Record<'get'\|'post'\|'put'\|'patch'\|'delete', string>>` | Override HTTP method badge colours. |
 
-For full theming, use CSS variables — see [Theming](/guide/theming).
+For full theming, use CSS variables (see [Theming](/guide/theming)).
 
 ### `defaults`
 
@@ -83,9 +83,9 @@ openApiDocs({
 | Field              | Type                                                                                                     | Default     | Description                                                                                                                 |
 | ------------------ | -------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `show`             | `('summary' \| 'description' \| 'params' \| 'request' \| 'response' \| 'auth' \| 'snippets' \| 'try')[]` | all         | Sections to render.                                                                                                         |
-| `auth`             | `'none' \| 'bearer' \| 'apikey' \| 'basic' \| 'oauth2'`                                                  | —           | Default auth scheme.                                                                                                        |
-| `server`           | `string`                                                                                                 | —           | Default server URL override.                                                                                                |
-| `apiKeyHeaderName` | `string`                                                                                                 | —           | Default header name for `apikey` schemes.                                                                                   |
+| `auth`             | `'none' \| 'bearer' \| 'apikey' \| 'basic' \| 'oauth2'`                                                  | auto        | Default auth scheme.                                                                                                        |
+| `server`           | `string`                                                                                                 | auto        | Default server URL override.                                                                                                |
+| `apiKeyHeaderName` | `string`                                                                                                 | auto        | Default header name for `apikey` schemes.                                                                                   |
 | `bodyInputs`       | `boolean`                                                                                                | `false`     | Render request body properties as individual inputs instead of a JSON textarea.                                             |
 | `layout`           | `'columns' \| 'stacked'`                                                                                 | `'columns'` | Default card layout. `columns` renders the Try-It panel as a sticky aside; `stacked` keeps everything in one vertical card. |
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index e6629f5..062c1ad 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -8,7 +8,7 @@ description: Common issues and solutions when using vitepress-openapi-docs.
 
 ```
 vitepress-openapi-docs: 1 broken <OpenApiEndpoint> embed(s):
-  - guide.md:12 — id="api.nonexistent"
+  - guide.md:12 id="api.nonexistent"
 ```
 
 **Cause:** A markdown page references an `operationId` that doesn't exist in any registered spec.
@@ -33,9 +33,9 @@ extends: await openApiDocs(config, { verbose: true })
 
 Check the console output for operation counts. Common causes:
 
-- Spec path is wrong — check the `spec` field in your config
-- Spec has no `paths` — verify your YAML/JSON has operations defined
-- The spec fails to parse — look for `[vitepress-openapi-docs]` error messages
+- Spec path is wrong: check the `spec` field in your config
+- Spec has no `paths`: verify your YAML/JSON has operations defined
+- The spec fails to parse: look for `[vitepress-openapi-docs]` error messages
 
 ## Empty changelog
 
@@ -106,12 +106,12 @@ Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
 **Fix:** The `spec` path is relative to the project root (where `package.json` is), not the docs directory.
 
 ```ts
-// Correct — relative to project root
+// Correct: relative to project root
 {
   spec: 'docs/openapi/api.yaml'
 }
 
-// Wrong — this looks for docs/docs/openapi/api.yaml
+// Wrong: this looks for docs/docs/openapi/api.yaml
 {
   spec: 'openapi/api.yaml'
 }
@@ -162,6 +162,6 @@ POST/PUT/PATCH endpoints show an empty body textarea.
 
 **Check:**
 
-- `OperationJumper` must be mounted in the `layout-top` slot — see [theme setup](/guide/existing-site#3-theme-setup)
+- `OperationJumper` must be mounted in the `layout-top` slot; see [theme setup](/guide/existing-site#3-theme-setup)
 - The specs virtual module must be imported and passed to `enhanceAppWithOpenApi`
 - Add `SearchTrigger` to `nav-bar-content-after` for a visible trigger button
diff --git a/packages/create/template/README.md b/packages/create/template/README.md
index 93dfc12..b65b09b 100644
--- a/packages/create/template/README.md
+++ b/packages/create/template/README.md
@@ -11,8 +11,8 @@ The scaffold ships with a snapshot of our full-featured mock spec at `docs/opena
 
 ## Layout
 
-- `docs/.vitepress/config.ts` — VitePress + the OpenAPI plugin
-- `docs/.vitepress/theme/index.ts` — registers the OpenAPI components
-- `docs/openapi/mock.json` — your OpenAPI spec (swap in your own)
-- `docs/api/mock/index.md` — landing page that renders the whole spec
-- `docs/index.md` — your home page
+- `docs/.vitepress/config.ts`: VitePress + the OpenAPI plugin
+- `docs/.vitepress/theme/index.ts`: registers the OpenAPI components
+- `docs/openapi/mock.json`: your OpenAPI spec (swap in your own)
+- `docs/api/mock/index.md`: landing page that renders the whole spec
+- `docs/index.md`: your home page