-
-
Notifications
You must be signed in to change notification settings - Fork 173
chore(cientos): new docs on nuxt #1208
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
77 commits
Select commit
Hold shift + click to select a range
b64c561
feat(cientos): new docs on nuxt
JaimeTorrealba 92938a2
chore(cientos-docs): rename package from "docs-boilerplate" to "cient…
alvarosabu 30aca27
Merge branch 'main' into cientos-docs
alvarosabu 734a283
📝 Add tweaks to navbar, homepage getting-started pages
JaimeTorrealba 1337005
docs(cientos): migration page on new docs
JaimeTorrealba dc96faa
📝 Migration of orbit controls
JaimeTorrealba f1e8851
📝 Add automatic fetch of collections.
JaimeTorrealba 38b4d63
📝 Add transform controls (fixing the demo)
JaimeTorrealba f2785dc
✨ Keyboard controls
JaimeTorrealba f4f0d6e
📝 pointer lock controls migration
JaimeTorrealba e594bfe
📝 Camera controls
JaimeTorrealba 8075fac
📝 Migration Loaders section
JaimeTorrealba 7c3b100
Merge branch 'main' into cientos-docs
alvarosabu 95ec8bb
📝 Add materials section
JaimeTorrealba 847e5dd
📝 Add shapes section
JaimeTorrealba 7da301d
📝New section debug/performance. Includes:
JaimeTorrealba 03ec31a
docs(cientos): add new section light/shadow, with
JaimeTorrealba bbb9cf7
feat(cientos): Migration staging section
JaimeTorrealba 748bdcb
docs(cientos): migration of abstractions.
JaimeTorrealba de48cc9
docs(cientos): new section Objects:
JaimeTorrealba 3a4fe63
docs(cientos): last migration miscellaneous section.
JaimeTorrealba da4ea31
docs(cientos): Implement all* index page.
JaimeTorrealba 95fb631
Merge branch 'main' into cientos-docs
JaimeTorrealba 6d3d3a4
Merge branch 'main' into cientos-docs
JaimeTorrealba a522415
Merge branch 'main' into cientos-docs
alvarosabu 1399b0f
refactor: update logo and branding in TheLogo component
alvarosabu 4cce85c
chore: update package.json dependencies to use catalog:nuxt and catal…
alvarosabu d1d71c8
chore: update pnpm-lock.yaml and package.json to use catalog:nuxt for…
alvarosabu ca84097
docs(cientos): remove duplicated titles on pages
JaimeTorrealba 6eb058f
docs(cientos): demos restored and with Leches pane
JaimeTorrealba 0e24fe1
cientos(docs): add leches to controls demos
JaimeTorrealba b4129d7
cientos(docs): add leches to debug section and fix demos on loaders s…
JaimeTorrealba db00bc0
cientos(docs): Leches to Light/Shadow section
JaimeTorrealba 5f1c322
lint
JaimeTorrealba 60edb72
docs(cientos): add Leches to materials section, to note here:
JaimeTorrealba 6393349
cientos(docs): add leches to misc section
JaimeTorrealba 2c3062a
cientos(docs): Leches to all demos in shape section (Some weirdness h…
JaimeTorrealba 63b9683
Merge branch 'main' into cientos-docs
JaimeTorrealba 77c9cc0
docs(cientos): add Leches to object section.
JaimeTorrealba 7b3f5a6
docs(cientos): add leches to staged section
JaimeTorrealba 0774545
lint
JaimeTorrealba d093eef
docs(cientos): small fixes on precipitation demo & ocean docs
JaimeTorrealba 991c68c
docs(cientos): adding editor config to gitignore
JaimeTorrealba 4f0314f
Merge branch 'main' into cientos-docs
JaimeTorrealba ad67fd0
lint
JaimeTorrealba 7febb39
update pnpm lock
JaimeTorrealba cad2997
Merge branch 'main' into cientos-docs
JaimeTorrealba 78a0219
docs(cientos): add camera shake
JaimeTorrealba dd2099e
docs(cientos): improve new html docs, based on the #1239
JaimeTorrealba 3d0c1c4
Merge branch 'main' into cientos-docs
alvarosabu 09c7811
docs(cientos): fix code review.
JaimeTorrealba e2bbecb
Merge branch 'main' into cientos-docs
alvarosabu d9f9f97
docs(cientos): fix missing links
JaimeTorrealba 728dd3d
chore(cientos-docs): add Netlify configuration
alvarosabu 25213d7
replace UAlert -> prose-warnings
JaimeTorrealba 73c26e7
docs(cientos): minor tweaks
alvarosabu c7daac3
chore: abstract scene wrappers with controls
alvarosabu 9cdfd4a
refactor(loaders): remove unnecessary div wrappers around TresCanvas …
alvarosabu 7f66c2e
chore(cientos-docs): scene wrapper controls for materials and shapes
alvarosabu e23b80b
chore: controls for debug performance
alvarosabu 066db57
chore: update lighting demos
alvarosabu e933ced
chore: updated staging components
alvarosabu 158d720
chore: updated objects and misc
alvarosabu e440d92
Merge branch 'main' into cientos-docs
JaimeTorrealba 12b12d0
docs(cientos): update smoke
JaimeTorrealba be3fab4
Merge branch 'chore/cientos-docs-scene-wrapper-approach' into cientos…
JaimeTorrealba 39a816a
Merge pull request #1273 from Tresjs/chore/cientos-docs-scene-wrapper…
JaimeTorrealba 193265d
Merge branch 'cientos-docs' of https://github.com/Tresjs/tres into ci…
JaimeTorrealba 37629a1
docs(cientos): add new smoke demo to use uuid on leches
JaimeTorrealba c526978
docs(cientos): Alvaro second review (lint problem)
JaimeTorrealba 267c74c
Merge branch 'main' into cientos-docs
alvarosabu bf30f5a
docs(cientos-docs): update installation instructions for create-tres …
alvarosabu d0dcfc1
chore(cientos-docs): lint formatting
alvarosabu fcddf20
docs(cientos-docs): fix code formatting in upgrade guide example
alvarosabu 8737750
docs(cientos): Move Grid components from debug/performance to shapes.
JaimeTorrealba c71dd1a
docs(cientos-docs): update llms configuration for Cientos documentati…
alvarosabu b1f93a6
Merge branch 'main' into cientos-docs
alvarosabu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # EditorConfig is awesome: https://EditorConfig.org | ||
|
|
||
| root = true | ||
|
|
||
| [*] | ||
| charset = utf-8 | ||
| end_of_line = lf | ||
| indent_size = 2 | ||
| indent_style = space | ||
| insert_final_newline = true | ||
| trim_trailing_whitespace = true |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # Nuxt dev/build outputs | ||
| .output | ||
| .data | ||
| .nuxt | ||
| .nitro | ||
| .cache | ||
| dist | ||
|
|
||
| # Node dependencies | ||
| node_modules | ||
|
|
||
| # Logs | ||
| logs | ||
| *.log | ||
|
|
||
| # Misc | ||
| .DS_Store | ||
| .fleet | ||
| .idea | ||
|
|
||
| # Local env files | ||
| .env | ||
| .env.* | ||
| !.env.example |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| shamefully-hoist=true |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,281 @@ | ||
| # Cientos docs - CLAUDE.md | ||
|
|
||
| This is a documentation app built with Nuxt v4 and Nuxt UI v4. It serves as a reference implementation for creating new documentation sites in the TresJS ecosystem. | ||
|
|
||
| ## Overview | ||
|
|
||
| This docs provides a complete setup for creating documentation sites with: | ||
|
|
||
| - Nuxt v4 with compatibility mode enabled | ||
| - Nuxt UI v4 for beautiful, accessible components | ||
| - Nuxt Content for markdown-based content | ||
| - TresJS integration for 3D examples | ||
| - Full-text search functionality | ||
| - Dark mode support | ||
| - SEO optimization | ||
|
|
||
| ## Architecture | ||
|
|
||
| ### App Structure | ||
|
|
||
| ``` | ||
| app/ | ||
| ├── app.config.ts # UI theme and app configuration | ||
| ├── app.vue # Root application component | ||
| ├── error.vue # Error page component | ||
| ├── assets/css/ # Global styles | ||
| ├── components/ # Vue components | ||
| │ ├── content/ # MDC prose components | ||
| │ └── diagrams/ # Custom diagram components | ||
| ├── composables/ # Composable functions (useNavigation) | ||
| ├── layouts/ # Page layouts (docs.vue) | ||
| ├── pages/ # Route pages | ||
| │ ├── index.vue # Landing page | ||
| │ └── [...slug].vue # Dynamic docs pages | ||
| └── utils/ # Utility functions | ||
| ``` | ||
|
|
||
| ### Content Structure | ||
|
|
||
| Content is organized in numbered directories for ordering: | ||
|
|
||
| ``` | ||
| content/ | ||
| ├── index.md # Landing page content | ||
| ├── 1.getting-started/ # Getting started section | ||
| ├── 2.guide/ # Guide section | ||
| └── 3.api/ # API reference section | ||
| ``` | ||
|
|
||
| ## Key Features | ||
|
|
||
| ### Nuxt UI v4 | ||
|
|
||
| - Uses Nuxt UI v4 components (`UApp`, `UPage`, `UMain`, etc.) | ||
| - Custom theme configuration in `app.config.ts` | ||
| - Teal color scheme as primary | ||
| - Custom CSS variables for patterns and gradients | ||
|
|
||
| ### Nuxt Content | ||
|
|
||
| - Markdown with MDC (Markdown Components) syntax | ||
| - Collection-based content management | ||
| - Automatic table of contents generation | ||
| - Search integration | ||
|
|
||
| ### TresJS Integration | ||
|
|
||
| - Vue template compiler options configured for TresJS | ||
| - Support for 3D scene components | ||
| - Ready for interactive 3D examples | ||
|
|
||
| ### SEO & Meta | ||
|
|
||
| - Configured SEO meta tags | ||
| - Open Graph and Twitter card support | ||
| - Dynamic titles and descriptions | ||
| - Sitemap generation ready | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Theme Customization | ||
|
|
||
| Edit `app/app.config.ts` to customize: | ||
|
|
||
| ``` | ||
| ui: { | ||
| colors: { | ||
| primary: 'teal', // Change primary color | ||
| neutral: 'zinc' // Change neutral color | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ### Navigation | ||
|
|
||
| Edit `app/composables/useNavigation.ts` to modify header navigation links. | ||
|
|
||
| ### Content Collections | ||
|
|
||
| Content is organized using Nuxt Content collections defined in `content.config.ts`: | ||
|
|
||
| - `landing` - Landing page (index.md) | ||
| - `docs` - All documentation pages | ||
|
|
||
| ### LLM Documentation | ||
|
|
||
| The `nuxt-llms` module is configured to generate LLM-friendly documentation at `/llms.txt` and `/llms-full.txt`. | ||
|
|
||
| ## Components | ||
|
|
||
| ### Layout Components | ||
|
|
||
| - **AppHeader** - Site header with navigation, search, and color mode toggle | ||
| - **AppFooter** - Footer with links and copyright | ||
| - **AppSide** - Sidebar navigation for docs layout | ||
|
|
||
| ### Content Components | ||
|
|
||
| - **ProseA** - Enhanced anchor links in markdown content | ||
|
|
||
| ### Diagram Components | ||
|
|
||
| Custom SVG diagram components for technical documentation. | ||
|
|
||
| ## Development | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - Node.js 18+ | ||
| - pnpm package manager | ||
|
|
||
| ### Commands | ||
|
|
||
| ```bash | ||
| # Install dependencies | ||
| pnpm install | ||
|
|
||
| # Development server | ||
| pnpm dev | ||
|
|
||
| # Build for production | ||
| pnpm build | ||
|
|
||
| # Preview production build | ||
| pnpm preview | ||
|
|
||
| # Lint code | ||
| pnpm lint | ||
|
|
||
| # Type checking | ||
| pnpm typecheck | ||
| ``` | ||
|
|
||
| ## Styling | ||
|
|
||
| ### CSS Architecture | ||
|
|
||
| - **Tailwind CSS v4** via `@import 'tailwindcss'` | ||
| - **Nuxt UI** styles via `@import '@nuxt/ui'` | ||
| - Custom theme variables in `main.css` | ||
| - Pattern backgrounds (`.pattern-bg`, `.pattern-dot-bg`) | ||
|
|
||
| ### Color Palette | ||
|
|
||
| Two custom color palettes are defined: | ||
|
|
||
| - **Teal** (50-950) - Primary brand color | ||
| - **Yellow/Brown** (50-950) - Accent color | ||
|
|
||
| ### Dark Mode | ||
|
|
||
| Automatic dark mode with theme-aware pattern backgrounds and custom favicon switching. | ||
|
|
||
| ## Content Writing | ||
|
|
||
| ### Markdown Format | ||
|
|
||
| ```md | ||
| --- | ||
| title: Page Title | ||
| description: Page description for SEO | ||
| --- | ||
|
|
||
| # Heading | ||
|
|
||
| Content here with **bold** and *italic* text. | ||
|
|
||
| ::callout | ||
| Custom MDC component | ||
| :: | ||
| ``` | ||
|
|
||
| ### MDC Components | ||
|
|
||
| Use Vue components directly in markdown: | ||
|
|
||
| ```md | ||
| ::block-hero | ||
| --- | ||
| cta: | ||
| - Get started | ||
| - /getting-started | ||
| --- | ||
|
|
||
| #title | ||
| Hero Title | ||
|
|
||
| #description | ||
| Hero description | ||
| :: | ||
| ``` | ||
|
|
||
| ## Deployment | ||
|
|
||
| ### Static Site Generation | ||
|
|
||
| Configured for static site generation with Nitro prerendering: | ||
|
|
||
| ``` | ||
| nitro: { | ||
| prerender: { | ||
| routes: ['/'], | ||
| crawlLinks: true, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ### Environment Variables | ||
|
|
||
| Create `.env` file for environment-specific configuration (use `.env.example` as reference). | ||
|
|
||
| ## Best Practices | ||
|
|
||
| 1. **Content Organization** - Use numbered prefixes for ordering | ||
| 2. **Component Naming** - Use PascalCase for components | ||
| 3. **MDC Syntax** - Leverage MDC for rich content | ||
| 4. **Accessibility** - All UI components are accessible by default | ||
| 5. **Performance** - Images are optimized via @nuxt/image | ||
| 6. **SEO** - Always include title and description frontmatter | ||
|
|
||
| ## Extending the Boilerplate | ||
|
|
||
| ### Adding New Sections | ||
|
|
||
| 1. Create new directory in `content/` | ||
| 2. Add index page with navigation | ||
| 3. Update `useNavigation.ts` if needed | ||
| 4. Update `llms` configuration in `nuxt.config.ts` | ||
|
|
||
| ### Custom Components | ||
|
|
||
| 1. Add components in `app/components/` | ||
| 2. MDC components go in `app/components/content/` | ||
| 3. Auto-imported by Nuxt | ||
|
|
||
| ### Styling Customization | ||
|
|
||
| 1. Update theme variables in `app.config.ts` | ||
| 2. Add custom CSS in `app/assets/css/main.css` | ||
| 3. Use Tailwind utilities for component styles | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### Build Issues | ||
|
|
||
| - Ensure Node.js 18+ is installed | ||
| - Clear `.nuxt` and `node_modules`, reinstall | ||
| - Check `pnpm-workspace.yaml` includes `apps/*` | ||
|
|
||
| ### Content Not Rendering | ||
|
|
||
| - Check frontmatter syntax | ||
| - Verify collection configuration in `content.config.ts` | ||
| - Ensure files use `.md` extension | ||
|
|
||
| ## Resources | ||
|
|
||
| - [Nuxt Documentation](https://nuxt.com) | ||
| - [Nuxt UI Documentation](https://ui.nuxt.com) | ||
| - [Nuxt Content Documentation](https://content.nuxt.com) | ||
| - [TresJS Documentation](https://docs.tresjs.org) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@JaimeTorrealba, this file should be added to the gitignore. We should consider adding one like this on the root in another PR.
For now, the linting should have the final word.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added, this was on the docs-boilerplate