ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/bootcamp/docs.mddeleted+0-653
Changes to docs/bootcamp/docs.md
@@ -1,653 +0,0 @@
1# Build Documentation
2
3This tutorial will guide you through building documentation for your Stacks project. Stacks uses BunPress (based on VitePress) to generate beautiful, fast documentation sites from Markdown files.
4
5## Overview
6
7Documentation in Stacks is:
8
9- **Markdown-based** - Write docs in familiar Markdown syntax
10- **Automatically served** - Docs are served at your configured path
11- **Highly customizable** - Configure navigation, themes, and more
12- **SEO-friendly** - Built-in sitemap and meta tag support
13
14## Project Structure
15
16Documentation files live in the `docs/` directory:
17
18```
19docs/
20├── index.md # Homepage
21├── guide/
22│ ├── intro.md # Getting started
23│ └── config.md # Configuration guide
24├── api/
25│ ├── actions.md # Actions reference
26│ └── routing.md # Routing reference
27└── _data/ # Shared data files
28```
29
30## Setting Up BunPress
31
32### Configuration
33
34Configure your documentation in `config/docs.ts`:
35
36```typescript
37// config/docs.ts
38import type { BunPressOptions } from '@stacksjs/bunpress'
39
40const config: BunPressOptions = {
41 verbose: true,
42 docsDir: './docs',
43 outDir: './dist/docs',
44
45 // Navigation bar
46 nav: [
47 {
48 text: 'Changelog',
49 link: 'https://github.com/your-org/your-repo/blob/main/CHANGELOG.md',
50 },
51 {
52 text: 'Resources',
53 items: [
54 { text: 'Team', link: '/team' },
55 { text: 'Sponsors', link: '/sponsors' },
56 { text: 'Contributing', link: '/contributing' },
57 ],
58 },
59 ],
60
61 // Markdown configuration
62 markdown: {
63 title: 'My Project Documentation',
64 meta: {
65 description: 'Documentation for My Project',
66 author: 'Your Name',
67 },
68 syntaxHighlightTheme: 'github-dark',
69 toc: {
70 enabled: true,
71 minDepth: 2,
72 maxDepth: 3,
73 },
74 sidebar: {
75 '/': [
76 {
77 text: 'Getting Started',
78 collapsed: false,
79 items: [
80 { text: 'Introduction', link: '/guide/intro' },
81 { text: 'Quick Start', link: '/guide/quick-start' },
82 { text: 'Configuration', link: '/guide/config' },
83 ],
84 },
85 {
86 text: 'Core Concepts',
87 collapsed: true,
88 items: [
89 { text: 'Routing', link: '/guide/routing' },
90 { text: 'Components', link: '/guide/components' },
91 { text: 'Actions', link: '/guide/actions' },
92 ],
93 },
94 {
95 text: 'API Reference',
96 collapsed: true,
97 items: [
98 { text: 'Actions', link: '/api/actions' },
99 { text: 'Router', link: '/api/router' },
100 { text: 'Database', link: '/api/database' },
101 ],
102 },
103 ],
104 },
105 themeConfig: {
106 logo: '/images/logo.svg',
107 footer: {
108 message: 'Released under the MIT License.',
109 copyright: 'Copyright 2024-present Your Company.',
110 },
111 socialLinks: [
112 { icon: 'twitter', link: 'https://twitter.com/yourhandle' },
113 { icon: 'github', link: 'https://github.com/your-org/your-repo' },
114 { icon: 'discord', link: 'https://discord.gg/yourdiscord' },
115 ],
116 },
117 },
118
119 // SEO Configuration
120 sitemap: {
121 enabled: true,
122 baseUrl: 'https://your-domain.com/docs',
123 },
124
125 robots: {
126 enabled: true,
127 },
128}
129
130export default config
131```
132
133## Writing Markdown
134
135### Basic Syntax
136
137```markdown
138# Heading 1
139## Heading 2
140### Heading 3
141
142Regular paragraph text with **bold**, *italic*, and `inline code`.
143
144- Bullet list item 1
145- Bullet list item 2
146 - Nested item
147
1481. Numbered list item 1
1492. Numbered list item 2
150
151[Link text](https://example.com)
152
153![Image alt text](/images/screenshot.png)
154```
155
156### Code Blocks
157
158Use fenced code blocks with language specification:
159
160````markdown
161```typescript
162
163// TypeScript code with syntax highlighting
164import { route } from '@stacksjs/router'
165
166route.get('/hello', () => {
167 return { message: 'Hello, World!' }
168})
169
170```
171````
172
173### Highlighting Lines
174
175Highlight specific lines in code blocks:
176
177````markdown
178```typescript{2,4-6}
179
180import { route } from '@stacksjs/router'
181
182route.get('/hello', () => { // Line 2 highlighted
183 return {
184 message: 'Hello, World!', // Lines 4-6 highlighted
185 }
186})
187
188```
189````
190
191### Custom Containers
192
193Use custom containers for callouts:
194
195```markdown
196::: tip
197This is a tip or helpful hint.
198:::
199
200::: warning
201This is a warning to be cautious about.
202:::
203
204::: danger
205This is a dangerous action or critical warning.
206:::
207
208::: info
209This is general information.
210:::
211
212::: details Click to expand
213This content is hidden by default and can be expanded.
214:::
215```
216
217### Tables
218
219```markdown
220| Feature | Supported | Notes |
221|---------|-----------|-------|
222| Routing | Yes | File-based and explicit |
223| Auth | Yes | Token-based |
224| Database | Yes | SQLite, MySQL, PostgreSQL |
225```
226
227## Frontmatter
228
229Add metadata to your pages using YAML frontmatter:
230
231```markdown
232---
233title: Getting Started
234description: Learn how to get started with My Project
235outline: deep
236---
237
238# Getting Started
239
240Your content here...
241```
242
243### Available Frontmatter Options
244
245```yaml
246---
247# Page title (used in browser tab and sidebar)
248title: Page Title
249
250# Meta description for SEO
251description: A brief description of this page
252
253# Control outline depth (false | 'deep' | number)
254outline: deep
255
256# Custom layout
257layout: home
258
259# Additional head tags
260head:
261
262 - - meta
263 - name: keywords
264
265 content: stacks, typescript, framework
266
267# Disable features
268sidebar: false
269aside: false
270---
271```
272
273## Home Page Layout
274
275Create an attractive home page:
276
277```markdown
278---
279layout: home
280title: My Project
281description: A powerful TypeScript framework
282
283hero:
284 name: My Project
285 text: Build amazing apps with TypeScript
286 tagline: Simple, fast, and modern
287 image:
288 src: /logo.svg
289 alt: My Project Logo
290 actions:
291
292 - theme: brand
293
294 text: Get Started
295 link: /guide/intro
296
297 - theme: alt
298
299 text: View on GitHub
300 link: https://github.com/your-org/your-repo
301
302features:
303
304 - icon: ⚡️
305
306 title: Lightning Fast
307 details: Built on Bun for maximum performance
308
309 - icon: ��️
310
311 title: Developer Experience
312 details: Type-safe, auto-complete everything
313
314 - icon: ��
315
316 title: Batteries Included
317 details: Auth, database, routing, and more built-in
318---
319```
320
321## Organizing Documentation
322
323### Directory Structure Best Practices
324
325```
326docs/
327├── index.md # Home page
328├── guide/ # User guides
329│ ├── intro.md # Introduction
330│ ├── quick-start.md # Quick start tutorial
331│ ├── configuration.md # Configuration reference
332│ └── deployment.md # Deployment guide
333├── api/ # API reference
334│ ├── actions.md # Actions API
335│ ├── router.md # Router API
336│ └── database.md # Database API
337├── examples/ # Example code
338│ ├── basic-app.md # Basic application
339│ └── full-stack.md # Full-stack example
340├── team.md # Team page
341├── sponsors.md # Sponsors page
342└── public/ # Static assets
343 └── images/
344 ├── logo.svg
345 └── screenshots/
346```
347
348### Cross-Referencing
349
350Link between documentation pages:
351
352```markdown
353<!-- Relative links -->
354See the [configuration guide](./configuration.md) for more details.
355
356<!-- Absolute links (from docs root) -->
357Learn about [routing](/guide/routing) first.
358
359<!-- Link to specific heading -->
360Check the [validation section](/api/actions#validation).
361```
362
363## API Documentation
364
365Document your APIs clearly:
366
367```markdown
368# Router API
369
370The router module provides routing functionality for your application.
371
372## Methods
373
374### `route.get(path, handler)`
375
376Register a GET route.
377
378**Parameters:**
379
380| Parameter | Type | Description |
381|-----------|------|-------------|
382| `path` | `string` | The URL path pattern |
383| `handler` | `Function \| string` | The route handler |
384
385**Returns:** `Route` - The route instance for chaining
386
387**Example:**
388
389```typescript
390
391import { route } from '@stacksjs/router'
392
393// With inline handler
394route.get('/users', () => {
395 return User.all()
396})
397
398// With action reference
399route.get('/users', 'Actions/User/ListUsersAction')
400
401```
402
403### `route.post(path, handler)`
404
405Register a POST route.
406
407<!-- Similar structure for other methods -->
408```
409
410## Building and Previewing
411
412### Development Mode
413
414Start the docs development server:
415
416```bash
417buddy docs:dev
418```
419
420This starts a hot-reloading server, typically at `<http://localhost:5173/docs>`.
421
422### Building for Production
423
424Build the documentation for production:
425
426```bash
427buddy docs:build
428```
429
430Output is generated to the `outDir` specified in your config (default: `./dist/docs`).
431
432### Preview Production Build
433
434Preview the production build locally:
435
436```bash
437buddy docs:preview
438```
439
440## Advanced Configuration
441
442### Custom Theme
443
444Extend the default theme:
445
446```typescript
447// config/docs.ts
448export default {
449 // ...
450 markdown: {
451 themeConfig: {
452 // Custom CSS variables
453 customCss: `
454 :root {
455 --vp-c-brand-1: #646cff;
456 --vp-c-brand-2: #747bff;
457 --vp-c-brand-3: #9499ff;
458 }
459 `,
460 },
461 },
462}
463```
464
465### Multiple Sidebars
466
467Configure different sidebars for different sections:
468
469```typescript
470markdown: {
471 sidebar: {
472 '/guide/': [
473 {
474 text: 'Guide',
475 items: [
476 { text: 'Introduction', link: '/guide/intro' },
477 { text: 'Quick Start', link: '/guide/quick-start' },
478 ],
479 },
480 ],
481 '/api/': [
482 {
483 text: 'API Reference',
484 items: [
485 { text: 'Actions', link: '/api/actions' },
486 { text: 'Router', link: '/api/router' },
487 ],
488 },
489 ],
490 },
491}
492```
493
494### Search Configuration
495
496Enable search functionality:
497
498```typescript
499markdown: {
500 themeConfig: {
501 search: {
502 provider: 'local', // Built-in search
503 options: {
504 translations: {
505 button: {
506 buttonText: 'Search',
507 buttonAriaLabel: 'Search documentation',
508 },
509 },
510 },
511 },
512 },
513}
514```
515
516## Deployment
517
518### Static Hosting
519
520The built documentation is static and can be deployed to any static hosting:
521
522- **Vercel**: Connect your repo, set build command to `buddy docs:build`
523- **Netlify**: Similar setup with build command
524- **GitHub Pages**: Deploy the `dist/docs` folder
525- **AWS S3 + CloudFront**: Upload static files
526
527### Integrated with Stacks
528
529Documentation is automatically served by the Stacks server:
530
531```typescript
532// config/app.ts
533export default {
534 // Docs will be available at /docs
535 docs: {
536 enabled: true,
537 path: '/docs',
538 },
539}
540```
541
542## Complete Example
543
544Here is a complete documentation page:
545
546```markdown
547---
548title: Actions Guide
549description: Learn how to create and use actions in your Stacks application
550---
551
552# Actions
553
554Actions are reusable units of business logic in Stacks. They can be triggered from routes, CLI commands, events, or other actions.
555
556## Creating an Action
557
558Generate a new action using Buddy:
559
560```bash
561
562buddy make:action SendWelcomeEmail
563
564```
565
566This creates a new file in `app/Actions/SendWelcomeEmail.ts`.
567
568## Action Structure
569
570::: code-group
571```typescript [Basic Action]
572
573import { Action } from '@stacksjs/actions'
574
575export default new Action({
576 name: 'SendWelcomeEmail',
577 description: 'Send a welcome email to new users',
578
579 async handle(request) {
580 // Your logic here
581 },
582})
583
584```
585
586```typescript [With Validation]
587
588import { Action } from '@stacksjs/actions'
589import { schema } from '@stacksjs/validation'
590
591export default new Action({
592 name: 'SendWelcomeEmail',
593
594 validations: {
595 email: {
596 rule: schema.string().email(),
597 message: 'Valid email required',
598 },
599 },
600
601 async handle(request) {
602 const email = request.get('email')
603 // Send email
604 },
605})
606
607```
608:::
609
610::: tip
611Actions are automatically discovered and registered. You don't need to import them anywhere.
612:::
613
614## Using Actions
615
616### From Routes
617
618```typescript
619
620route.post('/welcome', 'Actions/SendWelcomeEmail')
621
622```
623
624### From CLI
625
626Actions can also be triggered from CLI commands:
627
628```typescript
629
630// In a command
631await Action.run('SendWelcomeEmail', { email: 'user@example.com' })
632
633```
634
635## Next Steps
636
637- [Validation Guide](/guide/validation) - Learn about input validation
638- [Routing Guide](/guide/routing) - Connect actions to routes
639- [Testing Actions](/guide/testing-actions) - Write tests for your actions
640
641```
642
643## Next Steps
644
645Now that you know how to build documentation, continue to:
646
647- [Build a CLI](/bootcamp/cli) - Create command-line tools
648- [Deployment How-To](/bootcamp/how-to/deploy) - Deploy your documentation
649
650## Related Documentation
651
652- [BunPress Documentation](https://bunpress.dev)
653- [VitePress Documentation](https://vitepress.dev)