Skip to content

Commit c1f6cde

Browse files
lambdalisuelambdalisue
committed
docs: expand project structure and build documentation
Updated README.md and architecture.md to provide comprehensive documentation of the project structure, build workflow, and features. Changes: - Expanded directory structure from 8 to 22+ entries with detailed descriptions of all key files and subdirectories - Added detailed build workflow documentation covering API generation and static site generation with Pagefind - Documented all route formats (HTML, JSON, Markdown) and LLM endpoints - Added client-side features documentation (theme switching, code highlighting, carousel, etc.) - Included Pagefind installation instructions for different platforms This makes the project more maintainable and easier for contributors to understand the architecture and build process.
1 parent 2539cd4 commit c1f6cde

2 files changed

Lines changed: 122 additions & 18 deletions

File tree

‎.claude/rules/architecture.md‎

Lines changed: 72 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,25 +8,84 @@ paths: "main.ts, lib/**/*.ts, templates/**/*.tsx, scripts/**/*.ts"
88

99
```
1010
documents/
11-
├── main.ts # Entry point (Deno.serve)
12-
├── docs/ # Markdown documentation
13-
├── data/api/ # Generated from `deno doc --json`
14-
├── lib/ # Core modules (markdown, api-docs)
15-
├── templates/ # Hono JSX components
16-
└── scripts/ # Build and generation scripts
11+
├── main.ts # Entry point (Deno.serve)
12+
├── deno.json # Project configuration
13+
├── docs/ # Markdown documentation source
14+
├── data/
15+
│ ├── api/ # Generated API JSON (deno doc --json)
16+
│ ├── index/ # Example scenario index files
17+
│ └── docs.ts # Documentation pages configuration
18+
├── templates/ # Hono JSX components
19+
│ ├── api/ # API reference page templates
20+
│ ├── docs/ # Documentation page templates
21+
│ ├── Layout.tsx # Main layout component
22+
│ ├── HomeLayout.tsx # Home page layout
23+
│ ├── components.tsx # Shared UI components
24+
│ ├── home.tsx # Home page template
25+
│ └── scripts.ts # Client-side JavaScript (theme, carousel, etc.)
26+
├── lib/ # Core modules
27+
│ ├── api-docs.ts # API documentation types & utilities
28+
│ ├── api-markdown.ts # API markdown generation
29+
│ ├── markdown.ts # Markdown processing & link rewriting
30+
│ ├── llms.ts # LLM-friendly endpoints generation
31+
│ ├── signature-formatters.ts # Type signature formatting
32+
│ └── type-references.ts # Type reference resolution
33+
├── static/ # Static assets (CSS, images, favicon)
34+
├── scripts/ # Build and generation scripts
35+
│ ├── build.ts # SSG build + Pagefind indexing
36+
│ └── generate-api-docs.ts # Fetch & process API docs from JSR
37+
├── tests/ # Integration tests
38+
└── probitas/ # Example Probitas scenarios
1739
```
1840

1941
## Routes
2042

21-
| Path | Description |
22-
| ---------------- | ------------------- |
23-
| `/` | Landing page |
24-
| `/docs/{page}` | Documentation pages |
25-
| `/api/{package}` | API reference |
43+
| Path | Format | Description |
44+
| --------------------------- | -------- | -------------------------- |
45+
| `/` | HTML | Landing page |
46+
| `/index.md` | Markdown | Overview for LLMs |
47+
| `/llms.txt` | Text | LLM site map |
48+
| `/docs/*` | HTML | Documentation pages |
49+
| `/docs/*.md` | Markdown | Raw markdown for LLMs |
50+
| `/api/` | HTML | API reference index |
51+
| `/api/{package}/` | HTML | Package API reference |
52+
| `/api/{package}/index.json` | JSON | Raw API data |
53+
| `/api/{package}/index.md` | Markdown | API documentation for LLMs |
2654

27-
## API Generation
55+
## Build Workflow
56+
57+
### 1. API Documentation Generation
2858

2959
```bash
30-
# Generate API docs (run from scripts/generate-api-docs.ts)
3160
deno task generate-api
3261
```
62+
63+
Runs `scripts/generate-api-docs.ts`:
64+
65+
1. Fetches all `@probitas/*` packages from JSR API
66+
2. Runs `deno doc --json` for each package
67+
3. Processes and filters exports (removes private items, imports, etc.)
68+
4. Saves to `data/api/{package}.json`
69+
5. Generates `data/api/index.json` with package metadata
70+
71+
### 2. Static Site Generation
72+
73+
```bash
74+
deno task build
75+
```
76+
77+
Runs `scripts/build.ts`:
78+
79+
1. **SSG**: Uses Hono's `toSSG()` to generate HTML/JSON/Markdown files
80+
2. **Asset Copy**: Copies `static/` contents to `dist/static/`
81+
3. **Search Index**: Runs Pagefind to generate searchable index
82+
83+
## Client-Side Features
84+
85+
The site includes JavaScript functionality (see `templates/scripts.ts`):
86+
87+
- **Theme switching**: Light/dark mode with localStorage persistence
88+
- **Code highlighting**: Dynamic highlight.js loading with theme sync
89+
- **Code copy buttons**: Copy-to-clipboard for code blocks
90+
- **Carousel**: Interactive example carousel on home page
91+
- **Scroll indicators**: Fade effects for scrollable navigation

‎README.md‎

Lines changed: 50 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,30 @@ documents/
4747
├── deno.json # Project configuration
4848
├── docs/ # Markdown documentation source
4949
├── data/
50-
│ └── api/ # Generated API JSON (deno doc --json)
50+
│ ├── api/ # Generated API JSON (deno doc --json)
51+
│ ├── index/ # Example scenario index files
52+
│ └── docs.ts # Documentation pages configuration
5153
├── templates/ # JSX page templates
54+
│ ├── api/ # API reference templates
55+
│ ├── docs/ # Documentation page templates
56+
│ ├── Layout.tsx # Main layout component
57+
│ ├── HomeLayout.tsx # Home page layout
58+
│ ├── components.tsx # Shared UI components
59+
│ ├── home.tsx # Home page template
60+
│ └── scripts.ts # Client-side JavaScript
5261
├── lib/ # Utility modules
53-
├── static/ # Static assets
54-
└── scripts/ # Build scripts
62+
│ ├── api-docs.ts # API documentation types & utilities
63+
│ ├── api-markdown.ts # API markdown generation
64+
│ ├── markdown.ts # Markdown processing
65+
│ ├── llms.ts # LLM-friendly endpoints
66+
│ ├── signature-formatters.ts # Type signature formatting
67+
│ └── type-references.ts # Type reference resolution
68+
├── static/ # Static assets (CSS, images, favicon)
69+
├── scripts/ # Build & generation scripts
70+
│ ├── build.ts # Static site generation & Pagefind indexing
71+
│ └── generate-api-docs.ts # API documentation fetching
72+
├── tests/ # Integration tests
73+
└── probitas/ # Example Probitas scenarios
5574
```
5675

5776
## Routes
@@ -82,8 +101,34 @@ API documentation is generated from JSR packages using `deno doc`:
82101
deno task generate-api
83102
```
84103

85-
This fetches the latest API information from all `@probitas/*` packages and
86-
saves them to `data/api/`.
104+
This script:
105+
106+
1. Fetches all `@probitas/*` packages from JSR API
107+
2. Runs `deno doc --json` for each package
108+
3. Processes and saves the output to `data/api/`
109+
4. Formats the generated JSON files
110+
111+
The generated files are then used by the build process to create API reference
112+
pages.
113+
114+
### Build Process
115+
116+
The `deno task build` command performs the following steps:
117+
118+
1. **Static Site Generation**: Uses Hono's SSG to generate HTML, JSON, and
119+
Markdown files
120+
2. **Asset Copying**: Copies static assets (CSS, images, favicon) to `dist/`
121+
3. **Search Indexing**: Runs [Pagefind](https://pagefind.app/) to generate a
122+
search index
123+
124+
The build requires Pagefind to be installed. On macOS:
125+
126+
```bash
127+
brew install pagefind
128+
```
129+
130+
For other platforms, see
131+
[Pagefind installation guide](https://pagefind.app/docs/installation/).
87132

88133
## Deployment
89134

0 commit comments

Comments
 (0)