also looking at this
Deploy: uniform auth session model (main → production)
#7
282 files
+3028
-64856
| @@ -1,653 +0,0 @@ | ||
| 1 | # Build Documentation | |
| 2 | ||
| 3 | This 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 | ||
| 7 | Documentation 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 | ||
| 16 | Documentation files live in the `docs/` directory: | |
| 17 | ||
| 18 | ``` | |
| 19 | docs/ | |
| 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 | ||
| 34 | Configure your documentation in `config/docs.ts`: | |
| 35 | ||
| 36 | ```typescript | |
| 37 | // config/docs.ts | |
| 38 | import type { BunPressOptions } from '@stacksjs/bunpress' | |
| 39 | ||
| 40 | const 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 | ||
| 130 | export default config | |
| 131 | ``` | |
| 132 | ||
| 133 | ## Writing Markdown | |
| 134 | ||
| 135 | ### Basic Syntax | |
| 136 | ||
| 137 | ```markdown | |
| 138 | # Heading 1 | |
| 139 | ## Heading 2 | |
| 140 | ### Heading 3 | |
| 141 | ||
| 142 | Regular paragraph text with **bold**, *italic*, and `inline code`. | |
| 143 | ||
| 144 | - Bullet list item 1 | |
| 145 | - Bullet list item 2 | |
| 146 | - Nested item | |
| 147 | ||
| 148 | 1. Numbered list item 1 | |
| 149 | 2. Numbered list item 2 | |
| 150 | ||
| 151 | [Link text](https://example.com) | |
| 152 | ||
| 153 |  | |
| 154 | ``` | |
| 155 | ||
| 156 | ### Code Blocks | |
| 157 | ||
| 158 | Use fenced code blocks with language specification: | |
| 159 | ||
| 160 | ````markdown | |
| 161 | ```typescript | |
| 162 | ||
| 163 | // TypeScript code with syntax highlighting | |
| 164 | import { route } from '@stacksjs/router' | |
| 165 | ||
| 166 | route.get('/hello', () => { | |
| 167 | return { message: 'Hello, World!' } | |
| 168 | }) | |
| 169 | ||
| 170 | ``` | |
| 171 | ```` | |
| 172 | ||
| 173 | ### Highlighting Lines | |
| 174 | ||
| 175 | Highlight specific lines in code blocks: | |
| 176 | ||
| 177 | ````markdown | |
| 178 | ```typescript{2,4-6} | |
| 179 | ||
| 180 | import { route } from '@stacksjs/router' | |
| 181 | ||
| 182 | route.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 | ||
| 193 | Use custom containers for callouts: | |
| 194 | ||
| 195 | ```markdown | |
| 196 | ::: tip | |
| 197 | This is a tip or helpful hint. | |
| 198 | ::: | |
| 199 | ||
| 200 | ::: warning | |
| 201 | This is a warning to be cautious about. | |
| 202 | ::: | |
| 203 | ||
| 204 | ::: danger | |
| 205 | This is a dangerous action or critical warning. | |
| 206 | ::: | |
| 207 | ||
| 208 | ::: info | |
| 209 | This is general information. | |
| 210 | ::: | |
| 211 | ||
| 212 | ::: details Click to expand | |
| 213 | This 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 | ||
| 229 | Add metadata to your pages using YAML frontmatter: | |
| 230 | ||
| 231 | ```markdown | |
| 232 | --- | |
| 233 | title: Getting Started | |
| 234 | description: Learn how to get started with My Project | |
| 235 | outline: deep | |
| 236 | --- | |
| 237 | ||
| 238 | # Getting Started | |
| 239 | ||
| 240 | Your content here... | |
| 241 | ``` | |
| 242 | ||
| 243 | ### Available Frontmatter Options | |
| 244 | ||
| 245 | ```yaml | |
| 246 | --- | |
| 247 | # Page title (used in browser tab and sidebar) | |
| 248 | title: Page Title | |
| 249 | ||
| 250 | # Meta description for SEO | |
| 251 | description: A brief description of this page | |
| 252 | ||
| 253 | # Control outline depth (false | 'deep' | number) | |
| 254 | outline: deep | |
| 255 | ||
| 256 | # Custom layout | |
| 257 | layout: home | |
| 258 | ||
| 259 | # Additional head tags | |
| 260 | head: | |
| 261 | ||
| 262 | - - meta | |
| 263 | - name: keywords | |
| 264 | ||
| 265 | content: stacks, typescript, framework | |
| 266 | ||
| 267 | # Disable features | |
| 268 | sidebar: false | |
| 269 | aside: false | |
| 270 | --- | |
| 271 | ``` | |
| 272 | ||
| 273 | ## Home Page Layout | |
| 274 | ||
| 275 | Create an attractive home page: | |
| 276 | ||
| 277 | ```markdown | |
| 278 | --- | |
| 279 | layout: home | |
| 280 | title: My Project | |
| 281 | description: A powerful TypeScript framework | |
| 282 | ||
| 283 | hero: | |
| 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 | ||
| 302 | features: | |
| 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 | ``` | |
| 326 | docs/ | |
| 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 | ||
| 350 | Link between documentation pages: | |
| 351 | ||
| 352 | ```markdown | |
| 353 | <!-- Relative links --> | |
| 354 | See the [configuration guide](./configuration.md) for more details. | |
| 355 | ||
| 356 | <!-- Absolute links (from docs root) --> | |
| 357 | Learn about [routing](/guide/routing) first. | |
| 358 | ||
| 359 | <!-- Link to specific heading --> | |
| 360 | Check the [validation section](/api/actions#validation). | |
| 361 | ``` | |
| 362 | ||
| 363 | ## API Documentation | |
| 364 | ||
| 365 | Document your APIs clearly: | |
| 366 | ||
| 367 | ```markdown | |
| 368 | # Router API | |
| 369 | ||
| 370 | The router module provides routing functionality for your application. | |
| 371 | ||
| 372 | ## Methods | |
| 373 | ||
| 374 | ### `route.get(path, handler)` | |
| 375 | ||
| 376 | Register 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 | ||
| 391 | import { route } from '@stacksjs/router' | |
| 392 | ||
| 393 | // With inline handler | |
| 394 | route.get('/users', () => { | |
| 395 | return User.all() | |
| 396 | }) | |
| 397 | ||
| 398 | // With action reference | |
| 399 | route.get('/users', 'Actions/User/ListUsersAction') | |
| 400 | ||
| 401 | ``` | |
| 402 | ||
| 403 | ### `route.post(path, handler)` | |
| 404 | ||
| 405 | Register a POST route. | |
| 406 | ||
| 407 | <!-- Similar structure for other methods --> | |
| 408 | ``` | |
| 409 | ||
| 410 | ## Building and Previewing | |
| 411 | ||
| 412 | ### Development Mode | |
| 413 | ||
| 414 | Start the docs development server: | |
| 415 | ||
| 416 | ```bash | |
| 417 | buddy docs:dev | |
| 418 | ``` | |
| 419 | ||
| 420 | This starts a hot-reloading server, typically at `<http://localhost:5173/docs>`. | |
| 421 | ||
| 422 | ### Building for Production | |
| 423 | ||
| 424 | Build the documentation for production: | |
| 425 | ||
| 426 | ```bash | |
| 427 | buddy docs:build | |
| 428 | ``` | |
| 429 | ||
| 430 | Output is generated to the `outDir` specified in your config (default: `./dist/docs`). | |
| 431 | ||
| 432 | ### Preview Production Build | |
| 433 | ||
| 434 | Preview the production build locally: | |
| 435 | ||
| 436 | ```bash | |
| 437 | buddy docs:preview | |
| 438 | ``` | |
| 439 | ||
| 440 | ## Advanced Configuration | |
| 441 | ||
| 442 | ### Custom Theme | |
| 443 | ||
| 444 | Extend the default theme: | |
| 445 | ||
| 446 | ```typescript | |
| 447 | // config/docs.ts | |
| 448 | export 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 | ||
| 467 | Configure different sidebars for different sections: | |
| 468 | ||
| 469 | ```typescript | |
| 470 | markdown: { | |
| 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 | ||
| 496 | Enable search functionality: | |
| 497 | ||
| 498 | ```typescript | |
| 499 | markdown: { | |
| 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 | ||
| 520 | The 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 | ||
| 529 | Documentation is automatically served by the Stacks server: | |
| 530 | ||
| 531 | ```typescript | |
| 532 | // config/app.ts | |
| 533 | export default { | |
| 534 | // Docs will be available at /docs | |
| 535 | docs: { | |
| 536 | enabled: true, | |
| 537 | path: '/docs', | |
| 538 | }, | |
| 539 | } | |
| 540 | ``` | |
| 541 | ||
| 542 | ## Complete Example | |
| 543 | ||
| 544 | Here is a complete documentation page: | |
| 545 | ||
| 546 | ```markdown | |
| 547 | --- | |
| 548 | title: Actions Guide | |
| 549 | description: Learn how to create and use actions in your Stacks application | |
| 550 | --- | |
| 551 | ||
| 552 | # Actions | |
| 553 | ||
| 554 | Actions 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 | ||
| 558 | Generate a new action using Buddy: | |
| 559 | ||
| 560 | ```bash | |
| 561 | ||
| 562 | buddy make:action SendWelcomeEmail | |
| 563 | ||
| 564 | ``` | |
| 565 | ||
| 566 | This creates a new file in `app/Actions/SendWelcomeEmail.ts`. | |
| 567 | ||
| 568 | ## Action Structure | |
| 569 | ||
| 570 | ::: code-group | |
| 571 | ```typescript [Basic Action] | |
| 572 | ||
| 573 | import { Action } from '@stacksjs/actions' | |
| 574 | ||
| 575 | export 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 | ||
| 588 | import { Action } from '@stacksjs/actions' | |
| 589 | import { schema } from '@stacksjs/validation' | |
| 590 | ||
| 591 | export 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 | |
| 611 | Actions 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 | ||
| 620 | route.post('/welcome', 'Actions/SendWelcomeEmail') | |
| 621 | ||
| 622 | ``` | |
| 623 | ||
| 624 | ### From CLI | |
| 625 | ||
| 626 | Actions can also be triggered from CLI commands: | |
| 627 | ||
| 628 | ```typescript | |
| 629 | ||
| 630 | // In a command | |
| 631 | await 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 | ||
| 645 | Now 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) | |