From 84989514e078449ea55266ef068d3a0d07067bf3 Mon Sep 17 00:00:00 2001 From: Rishabh Date: Wed, 13 May 2026 14:04:25 +0530 Subject: [PATCH] docs: add features overview and update getting started guide - features.mdx: full feature overview, config reference, meta.json guide, markdown URLs, API reference page documentation - getting-started.mdx: updated with project structure, chronicle.yaml, meta.json, API reference, Docker setup Co-Authored-By: Claude Opus 4.6 (1M context) --- examples/basic/content/docs/features.mdx | 188 ++++++++++++++++++ .../basic/content/docs/getting-started.mdx | 113 ++++++++++- 2 files changed, 291 insertions(+), 10 deletions(-) create mode 100644 examples/basic/content/docs/features.mdx diff --git a/examples/basic/content/docs/features.mdx b/examples/basic/content/docs/features.mdx new file mode 100644 index 00000000..72bde9c2 --- /dev/null +++ b/examples/basic/content/docs/features.mdx @@ -0,0 +1,188 @@ +--- +title: Features +description: Overview of Chronicle features +order: 2 +--- + +# Features + +Chronicle is a self-hosted documentation platform built with Vite + Nitro. Here's what it offers. + +## Content + +- **MDX support** — write documentation in MDX with React component embedding +- **Frontmatter** — `title`, `description`, `order`, `icon`, `lastModified` +- **Directory metadata** — `meta.json` for folder titles, ordering, and sidebar config +- **Remark plugins** — directives, admonitions, image resolution, link resolution, mermaid, reading time +- **Syntax highlighting** — powered by Shiki via Apsara CodeBlock +- **Versioning** — multiple documentation versions with URL-based routing + +## API Reference + +- **OpenAPI / Swagger support** — auto-generates API reference pages from specs (OpenAPI 3.x and Swagger 2.0) +- **Read-only overview** — field names, types, required badges, examples, response schemas +- **Playground dialog** — test requests with editable fields, JSON body editor, auth switching +- **Auth types** — API Key, Bearer Token, Basic Auth (auto-detected from spec `securitySchemes`) +- **Code snippets** — cURL, Python, Go, TypeScript with language switcher +- **Response panel** — status code tabs with JSON syntax highlighting +- **`.md` export** — every API endpoint has a `.md` URL with full documentation + +## Navigation + +- **Sidebar** — auto-generated from file structure, configurable via `meta.json` +- **Breadcrumbs** — shows path hierarchy for docs and API pages +- **Prev/Next** — arrow navigation between pages and API endpoints +- **Search** — keyword search across all documentation +- **Folder sorting** — via `order` in `meta.json` or frontmatter + +## Themes + +- **Default theme** — sidebar + content layout with sub-navigation bar +- **Paper theme** — book-style single-column with reading progress +- **Dark/light mode** — system preference or manual toggle + +## SEO & AI + +- **Meta tags** — auto-generated title, description, Open Graph, Twitter Card +- **Sitemap** — auto-generated `sitemap.xml` +- **robots.txt** — auto-generated +- **llms.txt** — AI-discoverable documentation index +- **`.md` URLs** — every page (docs and API) has a markdown URL for AI tools +- **Open in AI** — copy as markdown, open in ChatGPT or Claude + +## Developer Experience + +- **CLI** — `chronicle dev`, `chronicle build`, `chronicle start` +- **Hot reload** — instant updates during development +- **Monorepo support** — works as a package in monorepos +- **Docker support** — containerized deployment +- **Zod-validated config** — `chronicle.yaml` with schema validation + +--- + +## Configuration + +### chronicle.yaml + +```yaml +site: + title: My Documentation + description: Documentation powered by Chronicle + +content: + - dir: docs + label: Docs + index_page: getting-started # redirect /docs to this page + +theme: + name: default + +search: + enabled: true + +api: + - name: Petstore + spec: ./petstore.json + basePath: /apis + server: + url: https://petstore.swagger.io/v2 + auth: + type: apiKey + header: api_key + placeholder: "Enter your API key" +``` + +### meta.json + +Place `meta.json` in any folder to control sidebar behavior: + +```json +{ + "title": "Getting Started", + "order": 1, + "pages": ["introduction", "installation", "quick-start"], + "defaultOpen": true +} +``` + +| Field | Description | +|---|---| +| `title` | Folder display name in sidebar and breadcrumbs | +| `order` | Sort order (lower = first) | +| `pages` | Explicit page ordering within folder | +| `root` | Mark as content root boundary | +| `defaultOpen` | Sidebar folder open by default | +| `icon` | Folder icon | + +### Page Frontmatter + +```mdx +--- +title: My Page +description: Page description for SEO +order: 1 +icon: book +lastModified: 2024-01-15 +--- +``` + +--- + +## Markdown URLs + +Every page has a `.md` URL that returns raw markdown: + +- **Docs pages**: `/{slug}.md` — returns the raw MDX content +- **API endpoints**: `/apis/{spec}/{operationId}.md` — generates markdown with: + - Authorization headers + - Path, query, body parameters with types and descriptions + - Request body example JSON + - Response schemas per status code + - cURL example + +### Usage + +```bash +# Get markdown for a docs page +curl https://docs.example.com/docs/getting-started.md + +# Get markdown for an API endpoint +curl https://docs.example.com/apis/petstore/findPetsByStatus.md +``` + +The "Open in AI" dropdown in the navbar uses these URLs to: +- **Copy as MD** — copies markdown to clipboard +- **View MD** — opens markdown in new tab +- **Open in ChatGPT** — sends the `.md` URL to ChatGPT +- **Open in Claude** — sends the `.md` URL to Claude + +--- + +## API Reference Page + +### Overview Page + +The API overview shows: +- Endpoint title and description +- HTTP method badge + path with copy button +- **Authorisations** — auth header fields +- **Path/Query Parameters** — field name, type, required badge, description, example +- **Request Body** — fields with nested object support +- **Response** — status code selector, field definitions, "Show child attributes" for nested objects + +Right column: +- Code snippet with language selector (cURL, Python, Go, TypeScript) +- Response JSON panel with status code tabs + +### Playground Dialog + +Click **Test request** in the navbar to open the playground: +- **Auth switching** — select between API Key, Bearer Token, Basic Auth +- **Editable fields** — fill path, query, header, body parameters +- **JSON editor** — toggle between form fields and raw JSON editor +- **Send** — sends request via proxy, shows response with status + time +- **Response headers** — switch between Body and Headers view + +### View Documentation + +If the OpenAPI spec has `externalDocs`, a **View documentation** button appears in the navbar linking to external docs. diff --git a/examples/basic/content/docs/getting-started.mdx b/examples/basic/content/docs/getting-started.mdx index 813ddd1a..ec32620d 100644 --- a/examples/basic/content/docs/getting-started.mdx +++ b/examples/basic/content/docs/getting-started.mdx @@ -1,7 +1,7 @@ --- title: Getting Started description: Quick start guide for Chronicle -order: 2 +order: 1 --- # Getting Started @@ -10,30 +10,123 @@ Get up and running with Chronicle in minutes. ## Prerequisites -- Node.js 18+ -- pnpm or npm +- [Bun](https://bun.sh) (recommended) or Node.js 20+ ## Installation ```bash -npm install @raystack/chronicle +bun add @raystack/chronicle ``` -## Create Your First Doc +## Project Structure -Create a `chronicle.yaml` file: +Create the following structure: + +``` +my-docs/ +├── chronicle.yaml # Configuration +├── content/ +│ └── docs/ +│ ├── meta.json # Sidebar title & order +│ ├── index.mdx # Landing page +│ └── guide.mdx # A doc page +└── petstore.json # OpenAPI spec (optional) +``` + +## Configuration + +Create `chronicle.yaml`: ```yaml -title: My Documentation -contentDir: . +site: + title: My Documentation + description: Documentation powered by Chronicle + +content: + - dir: docs + label: Docs + theme: name: default + +search: + enabled: true +``` + +## Write Your First Page + +Create `content/docs/index.mdx`: + +```mdx +--- +title: Welcome +description: Welcome to my documentation +order: 1 +--- + +# Welcome + +This is my documentation site powered by Chronicle. +``` + +## Add Folder Metadata + +Create `content/docs/meta.json` to control sidebar title and ordering: + +```json +{ + "title": "Documentation", + "order": 1 +} ``` ## Run Development Server ```bash -npx chronicle dev +bunx chronicle dev ``` -Visit http://localhost:3000 to see your docs. +Visit [http://localhost:3000](http://localhost:3000) to see your docs. + +## Add API Reference + +Add an OpenAPI spec to your project and update `chronicle.yaml`: + +```yaml +api: + - name: Petstore + spec: ./petstore.json + basePath: /apis + server: + url: https://petstore.swagger.io/v2 + auth: + type: apiKey + header: api_key + placeholder: "Enter your API key" +``` + +Restart the dev server — API reference pages are auto-generated at `/apis`. + +## Build for Production + +```bash +bunx chronicle build +bunx chronicle start +``` + +## Docker + +```dockerfile +FROM oven/bun:latest +WORKDIR /app +COPY . . +RUN bun install +RUN bunx chronicle build +CMD ["bunx", "chronicle", "start"] +``` + +## Next Steps + +- [Features](/docs/features) — full feature overview +- [Configuration](/docs/guides/configuration) — chronicle.yaml reference +- [Installation](/docs/guides/installation) — detailed setup guide