Skip to content

Commit 1450e83

Browse files
rsbhclaude
rsbh
and
claude
authored
docs: add features overview and update getting started guide (#63)
- 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) <noreply@anthropic.com>
1 parent 7ab1885 commit 1450e83

2 files changed

Lines changed: 291 additions & 10 deletions

File tree

‎examples/basic/content/docs/features.mdx‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
title: Features
3+
description: Overview of Chronicle features
4+
order: 2
5+
---
6+
7+
# Features
8+
9+
Chronicle is a self-hosted documentation platform built with Vite + Nitro. Here's what it offers.
10+
11+
## Content
12+
13+
- **MDX support** — write documentation in MDX with React component embedding
14+
- **Frontmatter** — `title`, `description`, `order`, `icon`, `lastModified`
15+
- **Directory metadata** — `meta.json` for folder titles, ordering, and sidebar config
16+
- **Remark plugins** — directives, admonitions, image resolution, link resolution, mermaid, reading time
17+
- **Syntax highlighting** — powered by Shiki via Apsara CodeBlock
18+
- **Versioning** — multiple documentation versions with URL-based routing
19+
20+
## API Reference
21+
22+
- **OpenAPI / Swagger support** — auto-generates API reference pages from specs (OpenAPI 3.x and Swagger 2.0)
23+
- **Read-only overview** — field names, types, required badges, examples, response schemas
24+
- **Playground dialog** — test requests with editable fields, JSON body editor, auth switching
25+
- **Auth types** — API Key, Bearer Token, Basic Auth (auto-detected from spec `securitySchemes`)
26+
- **Code snippets** — cURL, Python, Go, TypeScript with language switcher
27+
- **Response panel** — status code tabs with JSON syntax highlighting
28+
- **`.md` export** — every API endpoint has a `.md` URL with full documentation
29+
30+
## Navigation
31+
32+
- **Sidebar** — auto-generated from file structure, configurable via `meta.json`
33+
- **Breadcrumbs** — shows path hierarchy for docs and API pages
34+
- **Prev/Next** — arrow navigation between pages and API endpoints
35+
- **Search** — keyword search across all documentation
36+
- **Folder sorting** — via `order` in `meta.json` or frontmatter
37+
38+
## Themes
39+
40+
- **Default theme** — sidebar + content layout with sub-navigation bar
41+
- **Paper theme** — book-style single-column with reading progress
42+
- **Dark/light mode** — system preference or manual toggle
43+
44+
## SEO & AI
45+
46+
- **Meta tags** — auto-generated title, description, Open Graph, Twitter Card
47+
- **Sitemap** — auto-generated `sitemap.xml`
48+
- **robots.txt** — auto-generated
49+
- **llms.txt** — AI-discoverable documentation index
50+
- **`.md` URLs** — every page (docs and API) has a markdown URL for AI tools
51+
- **Open in AI** — copy as markdown, open in ChatGPT or Claude
52+
53+
## Developer Experience
54+
55+
- **CLI** — `chronicle dev`, `chronicle build`, `chronicle start`
56+
- **Hot reload** — instant updates during development
57+
- **Monorepo support** — works as a package in monorepos
58+
- **Docker support** — containerized deployment
59+
- **Zod-validated config** — `chronicle.yaml` with schema validation
60+
61+
---
62+
63+
## Configuration
64+
65+
### chronicle.yaml
66+
67+
```yaml
68+
site:
69+
title: My Documentation
70+
description: Documentation powered by Chronicle
71+
72+
content:
73+
- dir: docs
74+
label: Docs
75+
index_page: getting-started # redirect /docs to this page
76+
77+
theme:
78+
name: default
79+
80+
search:
81+
enabled: true
82+
83+
api:
84+
- name: Petstore
85+
spec: ./petstore.json
86+
basePath: /apis
87+
server:
88+
url: https://petstore.swagger.io/v2
89+
auth:
90+
type: apiKey
91+
header: api_key
92+
placeholder: "Enter your API key"
93+
```
94+
95+
### meta.json
96+
97+
Place `meta.json` in any folder to control sidebar behavior:
98+
99+
```json
100+
{
101+
"title": "Getting Started",
102+
"order": 1,
103+
"pages": ["introduction", "installation", "quick-start"],
104+
"defaultOpen": true
105+
}
106+
```
107+
108+
| Field | Description |
109+
|---|---|
110+
| `title` | Folder display name in sidebar and breadcrumbs |
111+
| `order` | Sort order (lower = first) |
112+
| `pages` | Explicit page ordering within folder |
113+
| `root` | Mark as content root boundary |
114+
| `defaultOpen` | Sidebar folder open by default |
115+
| `icon` | Folder icon |
116+
117+
### Page Frontmatter
118+
119+
```mdx
120+
---
121+
title: My Page
122+
description: Page description for SEO
123+
order: 1
124+
icon: book
125+
lastModified: 2024-01-15
126+
---
127+
```
128+
129+
---
130+
131+
## Markdown URLs
132+
133+
Every page has a `.md` URL that returns raw markdown:
134+
135+
- **Docs pages**: `/{slug}.md` — returns the raw MDX content
136+
- **API endpoints**: `/apis/{spec}/{operationId}.md` — generates markdown with:
137+
- Authorization headers
138+
- Path, query, body parameters with types and descriptions
139+
- Request body example JSON
140+
- Response schemas per status code
141+
- cURL example
142+
143+
### Usage
144+
145+
```bash
146+
# Get markdown for a docs page
147+
curl https://docs.example.com/docs/getting-started.md
148+
149+
# Get markdown for an API endpoint
150+
curl https://docs.example.com/apis/petstore/findPetsByStatus.md
151+
```
152+
153+
The "Open in AI" dropdown in the navbar uses these URLs to:
154+
- **Copy as MD** — copies markdown to clipboard
155+
- **View MD** — opens markdown in new tab
156+
- **Open in ChatGPT** — sends the `.md` URL to ChatGPT
157+
- **Open in Claude** — sends the `.md` URL to Claude
158+
159+
---
160+
161+
## API Reference Page
162+
163+
### Overview Page
164+
165+
The API overview shows:
166+
- Endpoint title and description
167+
- HTTP method badge + path with copy button
168+
- **Authorisations** — auth header fields
169+
- **Path/Query Parameters** — field name, type, required badge, description, example
170+
- **Request Body** — fields with nested object support
171+
- **Response** — status code selector, field definitions, "Show child attributes" for nested objects
172+
173+
Right column:
174+
- Code snippet with language selector (cURL, Python, Go, TypeScript)
175+
- Response JSON panel with status code tabs
176+
177+
### Playground Dialog
178+
179+
Click **Test request** in the navbar to open the playground:
180+
- **Auth switching** — select between API Key, Bearer Token, Basic Auth
181+
- **Editable fields** — fill path, query, header, body parameters
182+
- **JSON editor** — toggle between form fields and raw JSON editor
183+
- **Send** — sends request via proxy, shows response with status + time
184+
- **Response headers** — switch between Body and Headers view
185+
186+
### View Documentation
187+
188+
If the OpenAPI spec has `externalDocs`, a **View documentation** button appears in the navbar linking to external docs.

‎examples/basic/content/docs/getting-started.mdx‎

Lines changed: 103 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Getting Started
33
description: Quick start guide for Chronicle
4-
order: 2
4+
order: 1
55
---
66

77
# Getting Started
@@ -10,30 +10,123 @@ Get up and running with Chronicle in minutes.
1010

1111
## Prerequisites
1212

13-
- Node.js 18+
14-
- pnpm or npm
13+
- [Bun](https://bun.sh) (recommended) or Node.js 20+
1514

1615
## Installation
1716

1817
```bash
19-
npm install @raystack/chronicle
18+
bun add @raystack/chronicle
2019
```
2120

22-
## Create Your First Doc
21+
## Project Structure
2322

24-
Create a `chronicle.yaml` file:
23+
Create the following structure:
24+
25+
```
26+
my-docs/
27+
├── chronicle.yaml # Configuration
28+
├── content/
29+
│ └── docs/
30+
│ ├── meta.json # Sidebar title & order
31+
│ ├── index.mdx # Landing page
32+
│ └── guide.mdx # A doc page
33+
└── petstore.json # OpenAPI spec (optional)
34+
```
35+
36+
## Configuration
37+
38+
Create `chronicle.yaml`:
2539

2640
```yaml
27-
title: My Documentation
28-
contentDir: .
41+
site:
42+
title: My Documentation
43+
description: Documentation powered by Chronicle
44+
45+
content:
46+
- dir: docs
47+
label: Docs
48+
2949
theme:
3050
name: default
51+
52+
search:
53+
enabled: true
54+
```
55+
56+
## Write Your First Page
57+
58+
Create `content/docs/index.mdx`:
59+
60+
```mdx
61+
---
62+
title: Welcome
63+
description: Welcome to my documentation
64+
order: 1
65+
---
66+
67+
# Welcome
68+
69+
This is my documentation site powered by Chronicle.
70+
```
71+
72+
## Add Folder Metadata
73+
74+
Create `content/docs/meta.json` to control sidebar title and ordering:
75+
76+
```json
77+
{
78+
"title": "Documentation",
79+
"order": 1
80+
}
3181
```
3282

3383
## Run Development Server
3484

3585
```bash
36-
npx chronicle dev
86+
bunx chronicle dev
3787
```
3888

39-
Visit http://localhost:3000 to see your docs.
89+
Visit [http://localhost:3000](http://localhost:3000) to see your docs.
90+
91+
## Add API Reference
92+
93+
Add an OpenAPI spec to your project and update `chronicle.yaml`:
94+
95+
```yaml
96+
api:
97+
- name: Petstore
98+
spec: ./petstore.json
99+
basePath: /apis
100+
server:
101+
url: https://petstore.swagger.io/v2
102+
auth:
103+
type: apiKey
104+
header: api_key
105+
placeholder: "Enter your API key"
106+
```
107+
108+
Restart the dev server — API reference pages are auto-generated at `/apis`.
109+
110+
## Build for Production
111+
112+
```bash
113+
bunx chronicle build
114+
bunx chronicle start
115+
```
116+
117+
## Docker
118+
119+
```dockerfile
120+
FROM oven/bun:latest
121+
WORKDIR /app
122+
COPY . .
123+
RUN bun install
124+
RUN bunx chronicle build
125+
CMD ["bunx", "chronicle", "start"]
126+
```
127+
128+
## Next Steps
129+
130+
- [Features](/docs/features) — full feature overview
131+
- [Configuration](/docs/guides/configuration) — chronicle.yaml reference
132+
- [Installation](/docs/guides/installation) — detailed setup guide

0 commit comments

Comments
 (0)