# Write beautiful docs with Markdown ::u-page-hero #title Write beautiful docs with Markdown. #description Ship fast, flexible, and SEO-optimized documentation with beautiful design out of the box. :br Docus brings the best of the Nuxt ecosystem. #links :::u-button --- color: neutral size: xl to: https://docus.dev/en/getting-started/installation trailing-icon: i-lucide-arrow-right --- Get started ::: :::u-button --- color: neutral icon: simple-icons-github size: xl to: https://github.com/nuxt-content/docus variant: outline --- Star on GitHub ::: #headline :::u-button --- size: sm to: https://github.com/nuxt-content/docus/releases/tag/v5.0.0 variant: outline --- Docus v5 → ::: :: ::u-page-section :::u-page-grid ::::u-page-card --- spotlight: true class: group col-span-2 lg:col-span-1 target: _blank to: https://nuxt.com --- :floating-nuxt #title Built with [Nuxt](https://nuxt.com){rel=""nofollow""} #description Optimized by the most famous Vue framework. Docus gives you everything you need to build fast, performant, and SEO-friendly websites. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank to: https://ui.nuxt.com --- :::::u-color-mode-image --- height: 320 width: 859 alt: Beautiful visual powered by UI class: w-full h-80 object-cover rounded-lg dark: /landing/dark/templates-ui-pro.webp light: /landing/light/templates-ui-pro.webp --- ::::: #title Powered by [Nuxt UI](https://ui.nuxt.com){rel=""nofollow""} #description Beautiful out of the box, minimal by design but highly customizable. Docus leverages Nuxt UI to give you the best docs writing experience with zero boilerplate, just focus on your content. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- :::::tabs ::::::tabs-item{.mt-5 icon="i-lucide-eye" label="Preview"} :::::::div{.flex.flex-col.gap-4} ::::::::note{.my-0} Here's some additional information for you. :::::::: ::::::::tip{.my-0} Here's a helpful suggestion. :::::::: ::::::::warning{.my-0} Be careful with this action as it might have unexpected results. :::::::: ::::::::caution{.my-0} This action cannot be undone. :::::::: ::::::: :::::: ::::::tabs-item --- class: mt-5 mb-2 text-xs overflow-x-auto icon: i-lucide-code label: Code --- ```mdc ::note Here's some additional information. :: ::tip Here's a helpful suggestion. :: ::warning Be careful with this action as it might have unexpected results. :: ::caution This action cannot be undone. :: ``` :::::: ::::: #title Enhanced Markdown syntax by [Nuxt Content](https://content.nuxt.com){rel=""nofollow""} #description The only thing you need to take care about is writing your content. Write your pages in Markdown and extend with MDC syntax to embed Nuxt UI or custom Vue components. Structure, routing, and rendering are handled for you. :::: ::::u-page-card --- class: col-span-2 md:col-span-1 --- :assistant-demo #title Built-in [Assistant]{.text-primary} #description Let visitors ask questions about your documentation in natural language. The assistant searches your content and provides accurate answers with source citations. :::: ::::u-page-card --- spotlight: true class: col-span-2 md:col-span-1 min-h-[450px] target: _blank --- :color-mode-switch #title [Nuxt Color](https://color-mode.nuxtjs.org/){rel=""nofollow""} mode #description Built-in dark mode provided, no configuration required. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- :::::u-color-mode-image --- height: 554 width: 859 alt: Built-in navigation and full-text search class: rounded-lg dark: /landing/dark/command-menu.png format: webp light: /landing/light/command-menu.png loading: lazy --- ::::: #title Built-in navigation and [full-text search]{.text-primary} #description Only focus on ordering your content, Docus handles the search modal and auto-generates the side navigation for you. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- :::::browser-frame :video{.rounded-md controls loop playsinline src="https://res.cloudinary.com/nuxt/video/upload/v1767647099/studio/studio-demo_eiofld.mp4"} ::::: #title Edit your content in production with [Nuxt Studio](https://nuxt.studio){rel=""nofollow""} #description Write and manage your content visually, with zero Markdown knowledge required. Let your non technical colleagues collaborate on the documentation and integrate Vue components without code skills. :::: ::::u-page-card --- spotlight: true class: col-span-2 lg:col-span-1 target: _blank to: https://image.nuxt.com/ --- :::::div{.flex-1.flex.items-center.justify-center} ::::::u-color-mode-image --- alt: Nuxt Image visual class: w-[30%] lg:w-[70%] my-12 lg:my-0 dark: /landing/dark/nuxt-image.svg light: /landing/light/nuxt-image.svg --- :::::: ::::: #title [Nuxt Image](https://image.nuxt.com){rel=""nofollow""} optimization #description Docus automatically converts Markdown images to use `` . :::: ::::u-page-card --- spotlight: true class: col-span-2 lg:col-span-1 target: _blank to: https://docus.dev/en/concepts/internationalization --- :::::u-color-mode-image --- height: 195 width: 403 alt: Internationalization illustration class: w-full my-12 lg:my-0 dark: /landing/dark/i18n.svg light: /landing/light/i18n.svg --- ::::: #title [Internationalization]{.text-primary} support #description Built-in i18n support with automatic routing and content management. Create multi-language documentation effortlessly. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank to: https://docus.dev/en/ai/mcp --- :::::u-color-mode-image --- height: 400 width: 859 alt: Native MCP server and AI-ready content illustration class: w-full h-auto rounded-lg translate-y-10 dark: /landing/dark/mcp.svg light: /landing/light/mcp.svg --- ::::: #title [AI-Ready]{.text-primary} with native MCP #description Built-in Model Context Protocol server connects your documentation to AI tools like Cursor, VS Code, and Claude. Automatic generation of `llms.txt` and `llms-full.txt` files for seamless LLM integration. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- ```ts [app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'green', secondary: 'sky', }, }, socials: { x: 'https://x.com/nuxt_js', nuxt: 'https://nuxt.com' } }) ``` #title Customize with [Nuxt App Config](https://nuxt.com/docs/4.x/getting-started/configuration#app-configuration){rel=""nofollow""} #description Update colors, social links, header logos and component styles globally using the `app.config.ts`, no direct code modifications required. :::: ::::u-page-card --- spotlight: true class: col-span-2 lg:col-span-1 --- :::::div{.flex-1.flex.flex-col.items-center.justify-center.py-8.text-center} ::::::div{.flex.flex-col.gap-3.w-full.max-w-xs} :::::::u-button --- block: true color: primary size: lg to: https://docus.dev/en/getting-started/introduction trailing-icon: i-lucide-arrow-right --- Read Documentation ::::::: :::::::u-button --- block: true color: neutral icon: i-simple-icons-github size: lg target: _blank to: https://github.com/nuxt-content/docus variant: outline --- View on GitHub ::::::: :::::: ::::: #title [Ready]{.text-primary} to start? #description Explore all the features that make Docus the perfect documentation solution. :::: ::: :: # Introduction Welcome to **Docus**, a fully integrated documentation solution built with [Nuxt UI](https://ui.nuxt.com){rel=""nofollow""}. ## What is Docus? Docus is a theme based on the [UI documentation template](https://docs-template.nuxt.dev/){rel=""nofollow""}. While the visual style comes ready out of the box, your focus should be on writing content using the Markdown and [MDC syntax](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""} provided by [Nuxt Content](https://content.nuxt.com){rel=""nofollow""}. We use this theme across all our Nuxt module documentations, including: ::card-group :::card --- icon: i-lucide-image target: _blank title: Nuxt Image to: https://image.nuxt.com --- The documentation of `@nuxt/image` ::: :::card --- icon: i-simple-icons-nuxtdotjs target: _blank title: Nuxt Content to: https://content.nuxt.com --- The documentation of `@nuxt/content` ::: :::card --- icon: i-simple-icons-supabase target: _blank title: Nuxt Supabase to: https://supabase.nuxtjs.org --- The documentation of `@nuxt/supabase` ::: :::card --- icon: i-simple-icons-strapi target: _blank title: Nuxt Strapi to: https://strapi.nuxtjs.org --- The documentation of `@nuxt/strapi` ::: :: ## Key Features This theme includes a range of features designed to improve documentation management: - **Powered by** **[Nuxt 4](https://nuxt.com){rel=""nofollow""}**: Utilizes the latest Nuxt framework for optimal performance. - **Built with** **[Nuxt UI](https://ui.nuxt.com){rel=""nofollow""}**: Integrates a comprehensive suite of UI components. - **[MDC Syntax](https://content.nuxt.com/usage/markdown){rel=""nofollow""}** **via** **[Nuxt Content](https://content.nuxt.com){rel=""nofollow""}**: Supports Markdown with component integration for dynamic content. - **[Nuxt Studio](https://docus.dev/en/getting-started/studio){rel=""nofollow""}** **Compatible**: Write and edit your content visually. No Markdown knowledge is required! - **Auto-generated Sidebar Navigation**: Automatically generates navigation from content structure. - **Full-Text Search**: Includes built-in search functionality for content discovery. - **Optimized Typography**: Features refined typography for enhanced readability. - **Dark Mode**: Offers dark mode support for user preference. - **Extensive Functionality**: Explore the theme to fully appreciate its capabilities. # Installation ## `create-docus` CLI ::steps ### Create your docs directory Use the `create-docus` CLI to create a new Docus project: ```bash [Terminal] npx create-docus my-docs ``` You can choose between two templates: - `default`: Basic Docus setup for single-language documentation - `i18n`: Includes internationalization support for multi-language documentation ```bash [Terminal] # Create with i18n template npx create-docus my-docs -t i18n ``` We recommend using the `npm` package manager. ### Start your docs server in development Move to your docs directory and start your docs server in development mode: ```bash [Terminal] cd my-docs npm run dev ``` A local preview of your documentation will be available at {rel=""nofollow""} ### Write your documentation Head over the [Edition](https://docus.dev/en/concepts/edition) section to learn how to write your documentation. :: ## AI Assistant Skill Get started quickly with Docus by adding specialized knowledge to your AI assistant (Cursor, Claude, etc.): ```bash [Terminal] npx skills add https://docus.dev ``` This skill helps you create documentation faster by providing your AI assistant with: - Best practices for writing documentation with Docus - MDC component usage and ready-to-use templates - Writing guidelines and content structure patterns - Configuration and customization tips Once installed, your AI assistant can help you scaffold new documentation projects, generate pages with proper structure, and write content following Docus best practices. ::tip{to="https://docus.dev/en/ai/skills"} You can also publish your own skills from your Docus site. Learn more about Agent Skills. :: ## Layer Integration Docus uses a **Nuxt layer-based approach**, you can extend the Docus layer directly in your `nuxt.config.ts` with `extends: ['docus']`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ extends: ['docus'] }) ``` # Project Structure ## Global structure Docus is a **Nuxt layer** that extends your standard Nuxt application with documentation features. This gives you the flexibility of a full Nuxt project. When you create a new Docus project with `npx create-docus my-docs`, you get: ```bash my-docs/ ├── content/ # Your markdown content │ ├── index.md # Homepage │ └── docs/ # Documentation pages ├── public/ # Static assets └── package.json # Dependencies and scripts ``` You can still use any feature or file of a classical Nuxt project: ```bash my-docs/ ├── nuxt.config.ts # Nuxt configuration (add extra modules, components, etc.) ├── app/ # App directory ├── app.config.ts # App configuration │ ├── components/ # Components (add your own components) │ ├── layouts/ # Layouts (add your own layouts) │ └── pages/ # Pages (add your own pages) └── server/ # Server-side code (add your own server-side code) ``` ### `content/` directory This is where you [write pages](https://docus.dev/en/concepts/edition) in Markdown. Docus automatically generates routes based on your file structure. **Single language structure:** ```bash content/ ├── index.md # Landing page (/) ├── getting-started.md # Documentation page (/getting-started) └── guide/ ├── introduction.md # Documentation page (/guide/introduction) └── configuration.md # Documentation page (/guide/configuration) ``` ::tip{to="https://docus.dev/en/concepts/edition"} You can separate your documentation files within a `docs/` subfolder to make them accessible at the `/docs` route. Additionally, you have the flexibility to override your landing page using custom Vue pages if desired. :: **Multi-language structure (with i18n):** ```bash content/ ├── en/ │ ├── index.md # English landing page (/en) │ └── guide/ │ └── introduction.md # Documentation page (/en/guide/introduction) └── fr/ ├── index.md # French landing page (/fr) └── guide/ └── introduction.md # Documentation page (/fr/guide/introduction) ``` ::tip{to="https://docus.dev/en/concepts/internationalization"} More information about i18n is available in the internationalization section. :: ### `public/` directory Files contained within the `public/` directory are served at the root and are not modified by the build process. This is where you can locate your images, icons, and other static assets. ### `package.json` This file contains all the dependencies and scripts for your application. The `package.json` of a Docus application is really minimal and looks like: ```json [package.json] { "name": "my-docs", "scripts": { "build": "nuxt build --extends docus", "dev": "nuxt dev --extends docus", }, "dependencies": { "docus": "latest", "better-sqlite3": "^12.2.0", "nuxt": "^4.0.0" } } ``` ### `nuxt.config.ts` *This file is not mandatory to start a Docus application.* You can add extra modules to your Nuxt configuration file: ```typescript [nuxt.config.ts] export default defineNuxtConfig({ extends: ['@vercel/analytics/nuxt/module'] }) ``` ### `app.config.ts` *This file is not mandatory to start a Docus application.* ::warning You need a `nuxt.config.ts` to be set if you want to override app configuration. :: This is where you can [configure Docus](https://docus.dev/en/concepts/configuration) to fit your branding, handle SEO, set your locale, and adapt links and socials. ```ts [app.config.ts] export default defineAppConfig({ docus: { locale: 'en', // Set your single-language locale }, seo: { title: 'My Docs', description: 'My awesome documentation', }, // ... other configurations }) ``` ## Full Nuxt Project Capabilities Since Docus is a Nuxt layer, you can use **any feature** of a standard Nuxt project: ::warning You need a `nuxt.config.ts` to be set if you want to override your app with Nuxt files. If no Nuxt config is created, changes will not be applied. :: ```bash my-docs/ ├── app/ # App directory (optional) │ ├── app.config.ts # App configuration │ ├── app.css # Custom theme (auto-imported by Docus) │ ├── components/ # Custom Vue components │ ├── layouts/ # Custom layouts │ ├── pages/ # Custom Vue pages (outside of content) │ ├── composables/ # Vue composables │ └── middleware/ # Route middleware ├── server/ # Server-side code │ └── api/ # API routes ├── plugins/ # Nuxt plugins ├── middleware/ # Global middleware └── modules/ # Custom Nuxt modules ``` ::tip{to="https://docus.dev/en/concepts/nuxt"} This layer-based approach gives you the power of the entire Nuxt ecosystem while keeping documentation as the primary focus. :: # Studio module The **Nuxt Studio** module is a browser-based interface for editing your Nuxt Content website directly in production. Access it by GitHub, GitLab or Google authentication on your deployed site, and start managing content without any local development tools. ::tip{to="https://nuxt.studio/introduction"} Browse Nuxt Studio documentation to learn how ton install the module. :: :video{controls loop src="https://res.cloudinary.com/nuxt/video/upload/v1767647099/studio/studio-demo_eiofld.mp4"} The **studio editor** allows you to manage content entirely from your browser on your production website. There's no need for local development tools, Git commands, or terminal access. It's ideal for content teams who want to edit and preview changes in a familiar environment. ## Visual edition in production for your Nuxt Content website Nuxt Studio provides **visual editing directly in production** for Nuxt Content–powered websites. Originally offered as a standalone premium platform, Studio is now a **free, open-source, and self-hostable Nuxt module**. It enables your entire team, developers and non-technical editors alike, to create and update content safely without leaving your live website. ## Current features ### ✨ **TipTap Visual Editor** Rich Markdown editor with full MDC component support. ### 💻 **Monaco Code Editor** Advanced code editor for Markdown (MDC), YAML, and JSON files if you want to edit raw code. ### 📝 **Form-based Editor** Edit YAML, JSON, and frontmatter using auto-generated forms based on collection schemas. ### 🎨  **Vue Component Props Editor** Visual interface to edit Vue component props directly from the editor. ### 🔄 **Real-time Preview** Instantly preview content changes on your production website. ### 🔐 **Multi-provider Authentication** Secure OAuth authentication with GitHub, GitLab, and Google. ### 🔑 **Custom Authentication** Utilities to implement custom authentication flows (password, SSO, LDAP, etc.). ### 📝 **File Management** Create, edit, rename, and delete content files in the [content/]{.s2} directory. ### 🖼 **Media Management** Centralized media library with support for JPEG, PNG, GIF, WebP, AVIF, SVG, and more. ### 🌳 **Git Integration** Commit content changes directly from production and rely on your CI/CD pipeline to deploy them. ### 🚀 **Development Mode** Edit content and media files directly from your local filesystem using the Studio interface. ### 🌍 **Internationalization** Full i18n support for 17 languages: AR, BG, DE, EN, ES, FA, FI, FR, ID, IT, JA, NL, PL, PT-BR, UA, ZH, ZH-TW. ## **Upcoming features** ### 📂 **Collections View** Manage and navigate all content collections from a unified interface. ### 🖼 **Media Optimization** Optimize images and media assets directly within the editor. ### 🤖**AI Content Assistant** Get smart, AI-powered suggestions to improve and speed up content creation. ### 💡**Community-driven Features** Have an idea? Share your feedback and help shape the future of Nuxt Studio. # Migration ## **Migrating from Docus v3 to v4** Docus v4 introduces a new **layer-based approach** that leverages the official Nuxt CLI instead of the custom Docus CLI. While your existing content and configuration remain compatible, you'll need to update your commands and project setup. ### **⚠️ Breaking Changes** The main breaking changes are related to CLI commands: | v3 | v4 | | ------------------------ | ---------------------------- | | `npx docus init my-docs` | `npx create-docus my-docs` | | `docus dev` | `nuxt dev --extends docus` | | `docus build` | `nuxt build --extends docus` | ::tip Your existing Markdown content and MDC syntax will work without changes. The migration primarily involves updating your development and build workflow. :: ## **Migrating to Docus** Already using a Markdown-based solution for your documentation? Whether it’s **Docus v1**, the **Nuxt UI docs template**, or another static site setup, migrating to Docus is simple and straightforward. Docus offers a clean and maintainable solution with a single dependency: the Docus library itself. There’s no need to manage multiple dependencies. With everything built-in and maintained together, keeping your documentation up to date is easier than ever. To migrate, just move your existing Markdown files into the `content/` directory of the Docus starter. From there, you have two scenarios: - **If your current docs already use Nuxt Content and the MDC syntax**, make sure the components used in your content exist in Nuxt UI. If any components are missing, you can easily create your own custom ones. - **If you’re using standard Markdown**, you can copy your files as is. Then, enhance your documentation progressively using the [built-in components](https://docus.dev/en/essentials/components) provided by Nuxt UI. Once your content has been moved to the `content/` folder, you can go through the [configuration section](https://docus.dev/en/concepts/configuration) to easily customize your app. Docus is designed to focus on writing content, so if you're already using Markdown, you can easily switch to it. # Troubleshooting ## `pnpm` issues ### Approve build scripts If you encounter build or dev errors when using `pnpm`, especially related to `better-sqlite3` dependency, you might need to approve certain packages for building. Run the following command to approve packages for building: ```bash [Terminal] pnpm approve-builds ``` When prompted, select `better-sqlite3` and `sharp` from the list of packages to approve it for building. ### Enable shameful hoisting (compatibility mode) If you see errors such as `Can't resolve 'tailwindcss'` or `Can't resolve '@nuxt/ui'` you don't necessary need to import them, you can just apply a flat `node_modules` layout (like npm or yarn). You can enable compatibility mode by creating a `.npmrc` file with: ```bash [.npmrc] shamefully-hoist=true ``` # Edition Docus provides customization options to suit your needs. - You can integrate it as a complete website solution with both landing and documentation sections - Or embed the documentation functionality within your Nuxt application while maintaining full control over all other aspects (thanks to the [Nuxt layer feature](https://nuxt.com/docs/4.x/getting-started/layers){rel=""nofollow""}). ## Landing page The landing page is the first page your visitors see at the root `/` of your site. ### `Markdown` (default) By default, the landing page corresponds to the `content/index.md` file. Docus automatically: - Creates a `landing` content collection for the `content/index.md` file - Registers the `/` route to render your Markdown landing page ::tip{to="https://ui.nuxt.com/docs/components"} The `MDC` syntax gives you the ability to use Vue components, including slots and props in your `.md` files. You can use any Nuxt UI component in your Markdown to build your landing page. :: ### `Vue` (custom) Since Docus is a layer, it allows you to fully customize your landing page by creating a Vue page at `app/pages/index.vue` (or `app/pages/[[lang]]/index.vue` for i18n setups). This gives you full control with Vue components, custom layouts, and advanced interactions. In this case, Docus: - Do not create `landing` collection - Use native Nuxt router and consider `index.vue` as your home page ::note This automatic detection works for both single-language and multi-language (i18n) setups. :: ### Components MDC provides a dedicated syntax to easily use Vue components in your content: ```mdc [content/index.md] :::u-page-feature ::: ``` ### Slots Slots can receive text content or other components. - **Default slot** is rendered directly inside the component or with `#default`. - **Named slots** are defined using the `#` symbol followed by the slot name. ```mdc [index.md] :::u-page-feature #title Nuxt 4 #description Powered by Nuxt 4 for optimal performances and SEO. ::: ``` ### Props Props are passed using inline syntax or YAML frontmatter within the component block: ::tabs :::tabs-item{icon="i-lucide-braces" label="Inline"} ```mdc [index.md] :::u-page-feature{icon="i-simple-icons-nuxt" to="https://nuxt.com"} #title Nuxt 4 #description Powered by Nuxt 4 for optimal performances and SEO. ::: ``` ::: :::tabs-item{icon="i-lucide-code" label="YAML"} ```mdc [index.md] :::u-page-feature --- icon: i-simple-icons-nuxt to: https://nuxt.com --- #title Nuxt 4 #description Powered by Nuxt 4 for optimal performances and SEO. ::: ``` ::: :: ::note{to="https://content.nuxt.com"} Check the Nuxt Content documentation for more details about the MDC syntax :: ## Documentation pages ::tip There is a one to one relationship between content files and pages on your site. Each Markdown page in the `content/` folder maps directly to a page route. :: ### Without docs folder To get started, simply edit or add a `.md` files in the `content/` directory to have your pages updated. Docus will handle routing, navigation, and full-text search automatically. ```bash content/ ├── index.md # Landing page → / ├── getting-started.md # Documentation → /getting-started └── guide/ └── introduction.md # Documentation → /guide/introduction ``` ### With docs folder You can optionally organize your documentation files within a `docs/` subfolder. When Docus detects a `docs/` folder in your `content/` directory, it automatically prefixes all documentation URLs with `/docs`. ```bash content/ ├── index.md # Landing page → / └── docs/ ├── getting-started.md # Documentation → /docs/getting-started └── guide/ └── introduction.md # Documentation → /docs/guide/introduction ``` ::tip This is particularly useful when you want to use Docus as embedded documentation alongside other custom pages. You can create additional pages like a blog, contact page, pricing page, or any other custom content at the root level, while keeping your documentation organized under `/docs` . :: ### Mixed content Since Docus is a Nuxt layer, you can combine Markdown files with custom Vue pages: ```bash ├── app/ │ └── pages/ │ ├── pricing.vue # Custom pricing page → /pricing │ └── contact.vue # Custom contact page → /contact └── content/ ├── index.md # Landing page → / └── blog.md # Blog page → /blog └── docs/ # Documentation → /docs/* ├── getting-started.md └── api/ └── reference.md ``` This structure gives you the flexibility to build a complete website with Docus. Use Markdown for documentation and Vue pages for custom functionality like blogs, dashboards, or any interactive pages. ### Frontmatter Every file of the `content/` folder starts with the `---` syntax on top of the page. It corresponds to the frontmatter of your file which is a convention of Markdown-based CMS to provide meta-data to pages. ::tabs :::tabs-item{icon="i-lucide-code" label="Code"} ```md [content/getting-started/edition.md] --- title: 'Edition' description: 'Learn how to write your documentation.' --- ``` ::: :::tabs-item{icon="i-lucide-eye" label="Preview"} ![Frontmatter title and description](https://docus.dev/documentation/frontmatter-preview-title-description.png) ::: :: ### Parameters Pages in the `/content` directory are defined as [page](https://content.nuxt.com/docs/collections/types#page-type){rel=""nofollow""} type in Nuxt Content. They all follow the same structure with existing frontmatter keys: | | | | | | ------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | - | | Key | Type | Description | | | `title` | `string` | Title of the page. Displayed on top of the page. Used as SEO title if `seo` key is not provided. | | | `description` | `string` | Description of the page. Displayed bellow the title on top of the page. Used as SEO description if `seo` key is not provided. | | | `navigation` | `boolean` | Define if the page is included in left aside navigation. | | | `layout` | `string` | Change Nuxt layout of the page (default to `docs` defined by Docus). | | | `seo` | `{ title: string, description: string }` | SEO metas of your page. | | # Configuration Docus allows you to configure your documentation through the [app.config.ts](https://nuxt.com/docs/guide/directory-structure/app-config){rel=""nofollow""} file provided by Nuxt. ::warning You need a `nuxt.config.ts` to be set if you want to override your app config. Without an existing Nuxt config file, changes won't be applied. :: ## SEO Technical SEO is tricky and boring. Docus offers a solid, opt-in default setup that works out of the box, while giving you full control to customize your SEO metadata, from page titles to social sharing images. ### Metadata Docus offers flexible `SEO` metadata configuration, allowing you to easily override values globally or on a per-page basis. #### Global configuration Define default `SEO` metas for your entire documentation in `app.config.ts`. These values will be used as fallbacks across pages that don't specify their own in the front-matter as described in next section. You can also configure your `site.name` value from your `nuxt.config.ts` file, default is based on your `package.json` name. ::code-group ```ts [app.config.ts] export default defineAppConfig({ seo: { // Default to `%s - ${site.name}` titleTemplate: '', // Default to package.json name title: '', // Default to package.json description description: '' }, }) ``` ```ts [nuxt.config.ts] export default defineNuxtConfig({ site: { name: 'Docus', }, }) ``` :: #### Per-page configuration Each Markdown file in the `content/` directory starts with a frontmatter block (`---`). You can define `SEO` metadata per page by using the `seo` key: ```md [content/concepts/configuration.md] --- seo: title: 'Configuration' description: 'Customize your Docus documentation from the Nuxt application configuration file.' --- ``` ::tip{to="https://docus.dev/en/concepts/edition#frontmatter"} For more details on front-matter, see the edition guide. :: ### **Social sharing (OG) image** When you share a link of your documentation on social media or some chat platforms, the link will be **unfurled**, in other terms it gives a glimpse of what someone linked (displaying a title, description, and an image). All of these are powered by the **Open Graph Protocol**. #### Documentation pages We're using [Nuxt OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction){rel=""nofollow""} under the hood to generate OG image for each documentation page based on the provided title and description. For example, the OG image for the current page is: ![og image documentation page](https://docus.dev/_og/s/c_Docs,headline_Core+Concepts,title_Configuration,description_Customize+your+Docus+documentation+from+Nuxt+application+configuration+file.,p_Ii9lbi9jb25jZXB0cy9jb25maWd1cmF0aW9uIg.png) #### Landing page Same as the documentation pages, the landing page uses the same OG image generator based on the provided title and description. ![og image landing page](https://docus.dev/_og/s/c_Landing,title_Write+beautiful+docs+with+Markdown,description_Ship+fast+flexible+and+SEO-optimized+documentation+with+beautiful+design+out+of+the+box.+Docus+brings+together+the+best+of+the+Nuxt+ecosystem.+Powered+by+Nuxt+UI.,p_Ii9lbiI.png) #### Override OG image Since Docus is a [Nuxt layer](https://nuxt.com/docs/guide/going-further/layers){rel=""nofollow""}, you can override docs or landing page OG image by creating a file with the same name in your own `components/OgImage/` directory. ```text components/ OgImage/ Docs.takumi.vue # overrides the docs OG image Landing.takumi.vue # overrides the landing OG image ``` Your component receives `title`, `description`, and `headline` (docs only) as props and can use any Tailwind CSS or inline styles supported by the [Takumi renderer](https://nuxtseo.com/docs/og-image/guides/renderers){rel=""nofollow""}. ### Sitemap Docus automatically generates a sitemap at `/sitemap.xml` containing all your documentation pages. This helps search engines discover and index your content. #### Excluding pages To exclude a specific page from the sitemap, add `sitemap: false` to its frontmatter: ```md [content/draft-page.md] --- sitemap: false --- This page won't appear in the sitemap. ``` #### Site URL For proper sitemap URLs, set the `NUXT_SITE_URL` environment variable: ```bash NUXT_SITE_URL=https://your-site.com ``` ## Header Configure your documentation site's `title` or `logo`: ```ts [app.config.ts] export default defineAppConfig({ header: { title: '', logo: { light: '', dark: '', alt: '', }, }, }) ``` ### Brand Assets You can configure additional brand assets for your logo. Right-clicking the logo in the header opens a context menu with copy and download actions. ```ts [app.config.ts] export default defineAppConfig({ header: { title: 'My Project', logo: { light: '/logo/logo-dark.svg', dark: '/logo/logo-light.svg', alt: 'My Project Logo', wordmark: { light: '/logo/wordmark-dark.svg', dark: '/logo/wordmark-light.svg', }, favicon: '/favicon.svg', brandAssetsUrl: 'https://example.com/brand', }, }, }) ``` | Field | Description | | ------------------------------ | ------------------------------------------------------------------------ | | `logo.wordmark.light` / `dark` | Full wordmark (icon + text) for each color mode. | | `logo.display` | Which variant to show in the header: `'logo'` (default) or `'wordmark'`. | | `logo.class` | Additional CSS classes on the logo image (e.g. `'h-8'`). | | `logo.favicon` | Path to the favicon file. Defaults to `/favicon.ico`. | | `logo.brandAssetsUrl` | Link to your brand assets page, shown as a menu item. | When the logo is an SVG, the context menu offers **Copy logo** and **Copy wordmark** actions that copy the raw SVG with `currentColor` fills, ready to paste into Figma or any design tool. For non-SVG formats (PNG, etc.), only download actions are available. ## Color Mode By default, Docus includes a color mode toggle in the header and footer, allowing users to switch between light and dark modes. If your documentation only uses one theme, you can force it by setting the `colorMode` option: ```ts [app.config.ts] export default defineAppConfig({ docus: { colorMode: 'dark' } }) ``` | Value | Behavior | | -------------- | ------------------------------------ | | `''` (default) | System preference with toggle button | | `'light'` | Forces light mode, hides toggle | | `'dark'` | Forces dark mode, hides toggle | ### Keyboard Shortcut Press :kbd{value="D"} to toggle between light and dark mode when the color mode toggle is visible. You can customize or disable this shortcut in `app.config.ts`: ```ts [app.config.ts] export default defineAppConfig({ docus: { shortcuts: { toggleColorMode: 'd', // Default }, }, }) ``` Set `toggleColorMode` to an empty string to disable the shortcut. See the [Assistant](https://docus.dev/en/ai/assistant#keyboard-shortcuts) page for the shortcut format (`meta_d`, `ctrl_shift_p`, etc.). When a color mode is forced, the toggle button is hidden from the header and footer, and the color mode commands are removed from the command palette. ## Navigation ### Sub Navigation For documentation sites with many content sections, you can enable a sub-navigation that splits your top-level content folders into sections and filters the left sidebar to show only the active section's pages. Two display modes are available: - **`header`** — renders a secondary tab bar below the header (desktop only, with a drawer on mobile) - **`aside`** — renders section anchors at the top of the left sidebar (with a drawer on mobile) ```ts [app.config.ts] export default defineAppConfig({ navigation: { sub: 'header', // or 'aside' }, }) ``` :video{src="https://res.cloudinary.com/nuxt/video/upload/v1773263594/docus/subnav_idh2ae.mp4"} ::note The tabs are automatically generated from your top-level folders in `content/` . Each folder's title and icon are read from its `.navigation.yml` file. :: ## Search Docus includes built-in full-text search powered by [Nuxt UI ContentSearch](https://ui.nuxt.com/docs/components/content-search){rel=""nofollow""}. By default, it uses client-side [Fuse.js](https://www.fusejs.io/){rel=""nofollow""} filtering which loads all search sections upfront. ### FTS5 Full-Text Search You can switch to [SQLite FTS5](https://content.nuxt.com/docs/utils/use-search-collection){rel=""nofollow""} for faster, indexed search with built-in snippet highlighting. This builds an FTS5 index in the browser using SQLite WASM and only runs the search when a query is entered, instead of loading all sections upfront. ```ts [app.config.ts] export default defineAppConfig({ search: { fts: true } }) ``` | Mode | Index | Speed | Typo tolerance | Upfront payload | | ----------------- | --------------------- | --------------- | -------------- | ------------------- | | Fuse.js (default) | In-memory JS scan | O(n) per query | Full fuzzy | All sections loaded | | FTS5 | SQLite inverted index | O(log n) lookup | Prefix only | None | ## Socials Links Add your social media links in the footer using a `Record` where the key matches an icon from [Simple Icons](https://simpleicons.org/){rel=""nofollow""} library. ```ts [app.config.ts] export default defineAppConfig({ socials: { x: 'https://x.com/nuxt_js', discord: 'https://discord.com/invite/ps2h6QT', nuxt: 'https://nuxt.com', } }) ``` ## Table of Contents You can customize the table of content on the right sidebar of each page. ```ts [app.config.ts] export default defineAppConfig({ toc: { // Rename the title of the table of contents title: 'On this page', // Add a bottom section to the table of contents bottom: { title: 'Community', links: [{ icon: 'i-lucide-book-open', label: 'Nuxt UI docs', to: 'https://ui.nuxt.com/getting-started/installation/nuxt', target: '_blank' }] } } }) ``` ## Locale For single-language documentation (without the full `@nuxtjs/i18n` module), you can configure the locale through `app.config.ts`: ```ts [app.config.ts] export default defineAppConfig({ docus: { locale: 'fr', // Default: 'en' } }) ``` This sets the language for: - UI component translations - The `lang` and `dir` attributes on the `` tag - Built-in Docus interface strings ::tip{to="https://docus.dev/en/concepts/internationalization"} For multi-language documentation with language switching, see the [Internationalization guide](https://docus.dev/en/concepts/internationalization) . :: ## GitHub Integration Docus reads your `.git/` folder to get the `url` and `branch` of your repository to add: - GitHub icon in the header and footer - `Edit this page` and `Report an issue` links in the footer of each page. You can customize the `url`, `branch` and `rootDir` of your docs application by adding the following configuration to your `app.config.ts` file: ```ts [app.config.ts] export default defineAppConfig({ github: { url: 'https://github.com/nuxt-content/docus', branch: 'main', rootDir: 'docs' } }) ``` If you don't want to use GitHub, you can set the `github` key to `false` to disable the GitHub integration. ```ts [app.config.ts] export default defineAppConfig({ github: false }) ``` ::tip{to="https://docus.dev/en/getting-started/studio"} Those configurations can also be handled in Studio editor, give it a try! :: # Theme Docus is built on top of Nuxt UI and takes full advantage of Tailwind CSS v4, CSS variables. The Tailwind Variants API offers a flexible and scalable theming system. ::tip{to="https://ui.nuxt.com/getting-started/theme"} For a full overview of Nuxt UI theming, check out the Nuxt UI documentation. :: ## Override with `@theme` You can customize your theme with CSS variables inside a `@theme` directive to define your project's custom design tokens, like fonts, colors, and breakpoints. To override the theme, create an `app/app.css` file in your project: ```css [app/app.css] @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` ::warning Docus automatically imports `app/app.css` — you don't need to add it to the `css` array in `nuxt.config.ts` , and you should **not** include `@import "tailwindcss"` in this file as Docus handles it for you. :: ## Colors Docus uses pre-configured color aliases that are used to style components and power the `color` props across the UI. Each badge below represents a default alias: - :u-badge{label="primary" variant="outline"} → Main brand color, used as the default color for components :br [(default: green)]{.text-xs,text-muted} - :u-badge{color="secondary" label="secondary" variant="outline"} → Secondary color to complement the primary color :br [(default: blue)]{.text-xs,text-muted} - :u-badge{color="success" label="success" variant="outline"} → Used for success states :br [(default: green)]{.text-xs,text-muted} - :u-badge{color="info" label="info" variant="outline"} → Used for informational states :br [(default: blue)]{.text-xs,text-muted} - :u-badge{color="warning" label="warning" variant="outline"} → Used for warning states :br [(default: yellow)]{.text-xs,text-muted} - :u-badge{color="error" label="error" variant="outline"} → Used for form error validation states :br [(default: red)]{.text-xs,text-muted} - :u-badge{color="neutral" label="neutral" variant="outline"} → Neutral color for backgrounds, text, etc. :br [(default: slate)]{.text-xs,text-muted} You can customize these colors globally by updating the `app.config.ts` file under the `ui.colors` key: ```ts [app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'blue', neutral: 'zinc' } } }) ``` ## Components Beyond colors, all [Nuxt UI components](https://ui.nuxt.com/components){rel=""nofollow""} can be themed globally via `app.config.ts`. You can override any component’s appearance by using the same structure as the component’s internal theme object (displayed at [the end of each component page](https://ui.nuxt.com/components/card#theme){rel=""nofollow""}). For example, to change the font weight of all buttons: ```ts [app.config.ts] export default defineAppConfig({ ui: { button: { slots: { base: 'font-bold' } } } }) ``` In this example, the `font-bold` class will override the default `font-medium` class on all buttons. ::note{to="https://ui.nuxt.com/components/button#theme"} To explore the available theme options for each component, refer to the **Theme** section in their respective Nuxt UI documentation page. :: ## Docus Subcomponents Docus uses several Nuxt UI components internally for navigation, table of contents, and sub-navigation. You can customize their default variants through `app.config.ts` using the `defaultVariants` key, without having to override the entire component. The following components are configurable: | Component | Key | Defaults | | -------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------ | | [ContentToc](https://ui.nuxt.com/components/content-toc){rel=""nofollow""} | `ui.contentToc` | `highlight: true` | | [ContentNavigation](https://ui.nuxt.com/components/content-navigation){rel=""nofollow""} | `ui.contentNavigation` | `variant: 'link'`, `highlight: true` | | [NavigationMenu](https://ui.nuxt.com/components/navigation-menu){rel=""nofollow""} | `ui.navigationMenu` | `variant: 'pill'`, `highlight: true` | For example, to change the table of contents highlight style to `circuit` and switch the sidebar navigation variant to `pill`: ```ts [app.config.ts] export default defineAppConfig({ ui: { contentToc: { defaultVariants: { highlightVariant: 'circuit', highlightColor: 'secondary' } }, contentNavigation: { defaultVariants: { variant: 'pill', highlight: false } } } }) ``` Each component supports the following variant options: - **`highlight`** — Display an active indicator line (`true` or `false`) - **`highlightColor`** — Color of the indicator (`primary`, `secondary`, `neutral`, etc.) - **`variant`** — Visual style (`pill` or `link`, where applicable) - **`highlightVariant`** — Indicator style (`straight` or `circuit`, ContentToc only) - **`color`** — Base color of the active link # Customization Docus is built on top of Nuxt 4 which offers a flexible component layer system that allows you to override some part of the UI by redefining specific components in your own app. This makes it easy to fully customize the visual appearance and behavior of your documentation without touching the core theme. To override a component, simply create a Vue file with the same name in the `components/` directory. Docus will automatically use your version instead of the default one. ## App Header You can customize different parts of the header by overriding the following components: ### `AppHeaderLogo` For simple adjustments like changing the logo size, you can use the `logo.class` option in `app.config.ts` without overriding the component (e.g. `class: 'h-8'`). To fully replace the default logo in the header, create the `components/AppHeaderLogo.vue` file. Your component will replace the default one provided by Docus theme. You can use the `useLogoAssets()` composable to keep the right-click context menu with copy and download actions. ![App header logo visualisation](https://docus.dev/documentation/app-header-logo.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderLogo.vue variant: link --- Default component code :: ### `AppHeaderLeft` The logo sits inside a default home link wrapper. If you want to change that link (URL, attributes) or the layout around `AppHeaderLogo`, override `components/AppHeaderLeft.vue` instead. ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderLeft.vue variant: link --- Default component code :: ### `AppHeaderCTA` To customize the call-to-action area in the header (for example, adding a “Get Started” button or external link), override the `components/AppHeaderCTA.vue` component. ![App header CTA visualisation](https://docus.dev/documentation/app-header-cta.webp) ::note --- to: https://github.com/nuxt-content/docus/blob/main/docs/app/components/AppHeaderCTA.vue --- By default this components is empty but you can have a look at how we're overriding it on Docus documentation itself. :: ### `AppHeaderCenter` To customize the center area in the header, override the `components/AppHeaderCenter.vue` component. Your component will replace the search bar provided by Docus theme. ![App header logo visualisation](https://docus.dev/documentation/app-header-center.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderCenter.vue variant: link --- Default component code :: ### `AppHeaderBody` By default, when you open the menu on mobile view, Docus is displaying your `content/` folder tree as a menu with the [ContentNavigation](https://ui.nuxt.com/components/content-navigation){rel=""nofollow""} component. You can override this menu with the `components/AppHeaderBody.vue` component and fill the menu body (under the header) in mobile. ![App header body visualisation](https://docus.dev/documentation/app-header-body.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderBody.vue variant: link --- Default component code :: ### `AppHeaderBottomRight` When [`navigation.sub`](https://docus.dev/en/concepts/configuration#sub-navigation) is set to `'header'`, Docus renders a secondary tab bar below the header. To add custom content on the right side of this bar (e.g. a toggle, a badge), create a `components/AppHeaderBottomRight.vue` component. ::note --- to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderBottom.vue --- To fully replace the sub navigation bar, override the `AppHeaderBottom.vue` component instead. :: ::tip{to="https://docus.dev/en/concepts/nuxt"} If you want to customize the header globally, maybe you should consider using your own layout. :: ## App Footer You can customize different parts of the footer by overriding the following components: ### `AppFooterLeft` To replace the left side of the footer, create the `components/AppFooterLeft.vue` file. Your component will replace the default one provided by Docus theme. ![App footer left visualisation](https://docus.dev/documentation/app-footer-left.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppFooterLeft.vue variant: link --- Default component code :: ### `AppFooterRight` To replace the right side of the footer, create the `components/AppFooterRight.vue` file. Your component will replace the default one provided by Docus theme. ![App footer right visualisation](https://docus.dev/documentation/app-footer-right.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppFooterRight.vue variant: link --- Default component code :: ::tip{to="https://docus.dev/en/concepts/nuxt"} If you want to customize the footer globally, maybe you should consider using your own layout. :: ## Docs You can also customize header and both asides of the documentation pages. ### `DocsPageHeaderLinks` In the header right side of your documentation page, Docus default behaviour is displaying a dropdown with quick actions related to the current page’s Markdown source. It allows the reader of the documentation to: - **Copy a direct link** to the raw `.md` file to the clipboard. - **View the Markdown source** in a new browser tab. - **Open the page’s content in ChatGPT or Claude**, pre-filled with a prompt to analyze the Markdown file. These actions are especially useful for contributors, readers, or AI-assisted workflows but you can create your own `components/DocsPageHeaderLinks.vue` component to override it. ![App Page Header Links](https://docus.dev/documentation/app-page-header-links.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/tree/main/layer/app/components/docs/DocsPageHeaderLinks.vue variant: link --- Default component code :: ### `DocsAsideRight` To fully replace the right aside of the documentation pages, create a `components/DocsAsideRight.vue` component. ![Docs right aside](https://docus.dev/documentation/docs-aside-right.png) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/tree/main/layer/app/components/docs/DocsAsideRight.vue variant: link --- Default component code :: ### `DocsAsideRightBottom` To customize bottom part of the right aside of the documentation pages. You can create the`components/DocsAsideRightBottom.vue` component. Your component will replace the default bottom table of content provided by Docus theme. ![Docs right aside bottom](https://docus.dev/documentation/docs-aside-right-bottom.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/tree/main/layer/app/components/docs/DocsAsideRightBottom.vue variant: link --- Default component code :: ### `DocsAsideLeftTop` To customize top part of the left aside of the documentation pages. You can create the`components/DocsAsideLeftTop.vue` component. ![Docs Aside Left Top](https://docus.dev/documentation/docs-aside-left-top.webp) ::note --- to: https://github.com/nuxt/image/blob/main/docs/app/components/DocsAsideLeftTop.vue --- By default this components is empty but you can have a look at how we're overriding it on Nuxt Image documentation itself. :: ### `DocsAsideLeftBody` To customize main part of the left aside of the documentation pages. You can create the`components/DocsAsideLeftTop.vue` component. Your component will replace the default file navigation provided by Docus theme. ![Docs aside left body visualisation](https://docus.dev/documentation/docs-aside-left-body.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/tree/main/layer/app/components/docs/DocsAsideLeftBody.vue variant: link --- Default component code :: ## Custom Icons Docus uses [Nuxt Icon](https://github.com/nuxt/icon){rel=""nofollow""} with the [Iconify](https://iconify.design/){rel=""nofollow""} provider, giving you access to thousands of icons out of the box (e.g. `i-lucide-arrow-right`, `i-simple-icons-github`). To add your own icons, place SVG files in the `assets/icons/` directory of your app. They are automatically registered under the `custom` prefix and available everywhere in your project. ```text assets/ icons/ my-logo.svg ``` You can then use them with the `i-custom:` prefix: ```md [content/getting-started.md] --- navigation: icon: i-custom:my-logo --- ``` ```ts [app.config.ts] export default defineAppConfig({ toc: { bottom: { links: [{ icon: 'i-custom:my-logo', label: 'Preview', to: '/preview' }] } } }) ``` ```vue [components/MyComponent.vue] ``` ::tip{to="https://iconify.design/docs/icons/icon-set-basics.html"} SVG files should use `currentColor` for fills and strokes so the icon adapts to text color. :: # Internationalization Docus introduces **native internationalization support** based on the `@nuxtjs/i18n` module, allowing you to create documentation in multiple languages with automatic routing and content management. ## Features - **Built-in i18n module**: Native integration with `@nuxtjs/i18n` - **Dynamic locale routing**: Automatic URL prefixing with language codes (`/en/docs`, `/fr/docs`) - **Content collections per locale**: Separate content management for each language - **Language switcher**: Built-in component for switching between locales - **Single-language configuration**: Simple locale configuration for single-language sites via `app.config.ts` ## Single Language Configuration If you're building documentation in a single language (without the full `@nuxtjs/i18n` module), you can configure the locale through `app.config.ts`. This is useful for setting the language for UI components and localizing built-in strings. ```ts [app.config.ts] export default defineAppConfig({ docus: { locale: 'fr', // Set your locale (default: 'en') } }) ``` ## Multi-Language Setup For multi-language documentation, use the full `@nuxtjs/i18n` integration as described below. ### Setup an existing project To enable i18n in your Docus project, add the `@nuxtjs/i18n` module to your `nuxt.config.ts` and define your locales: ```typescript [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxtjs/i18n'], i18n: { defaultLocale: 'en', locales: [ { code: 'en', name: 'English' }, { code: 'fr', name: 'Français' }, ], } }) ``` ::warning Docus overrides the `@nuxtjs/i18n` strategy to `prefix` . :: ## Create a new project with i18n template When creating a new project, you can choose the i18n template for pre-configured internationalization: ```bash [Terminal] npx create-docus my-docs -t i18n ``` ## Directory Structure When i18n is enabled, organize your content by locale in the `content/` directory: ```bash content/ ├── en/ # English content │ ├── index.md # English homepage │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ └── guide/ │ └── advanced.md ├── fr/ # French content │ ├── index.md # French homepage │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ └── guide/ │ └── advanced.md ``` ::warning Each locale should mirror the same directory structure to maintain consistent navigation across languages. :: ## Locale fallback Docus warns and skips any locale that does not exist in your `content/` directory. Missing locales are not registered. ::tip This is especially helpful when you extend Docus and use `@nuxtjs/i18n` for the rest of your site, but only want the docs in a subset of languages. :: Docus detects locales from your nuxt config: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxtjs/i18n'], i18n: { locales: ['en', 'fr', 'ja'], defaultLocale: 'en' } }) ``` But only register it based on your `content/` folder structure: ```bash content/ ├─ en/ # registered ✅ ├─ fr/ # registered ✅ (if present) └─ ja/ # skipped 🚫 (if missing) ``` If a user requests a missing docs locale, Docus redirects to the **default locale**. ::warning You must set a `defaultLocale` in your i18n config and ensure it exists under `content/` :: # Nuxt ## Nuxt App Docus is built on top of **Nuxt 4**, which means your documentation project is a full Nuxt application. When you scaffold a project using the **Docus CLI**, it adds a layer by default giving you all the flexibility of a standard Nuxt app. By default, the Docus starter only contains a `content/` and `public/` folder and a `package.json`. This is all you need to start writing your documentation. You can go further and use any feature of a Nuxt project, from [nuxt.config.ts](https://nuxt.com/docs/guide/directory-structure/nuxt-config){rel=""nofollow""} to [components](https://nuxt.com/docs/guide/directory-structure/nuxt-config){rel=""nofollow""} or [plugins](https://nuxt.com/docs/guide/directory-structure/plugins){rel=""nofollow""}. ::note You can use the Nuxt 4 [new directory structure](https://nuxt.com/docs/getting-started/upgrade#new-directory-structure){rel=""nofollow""} provided by the [compatibility version 4 .]() All files related to front app code goes in `app/` folder for cleaner organization and better IDE performance. :: ## Nuxt Modules Want to enhance your docs with custom functionality? You can install and configure [Nuxt modules](https://nuxt.com/modules){rel=""nofollow""} just like in any Nuxt app. To add [Vercel Web Analytics](https://vercel.com/docs/analytics){rel=""nofollow""} to your documentation: ::steps ### Install `@vercel/analytics` ```bash [Terminal] npm install @vercel/analytics ``` ### Enable Web Analytics in `nuxt.config.ts` For Nuxt, you can turn on Vercel Analytics without extra setup by using the inline module declaration: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@vercel/analytics/nuxt/module'], }) ``` :: ## Custom Components With the power of `Nuxt Content` and `Nuxt UI`, and with the help of the `MDC` syntax, you can use [Nuxt UI components](https://docus.dev/en/essentials/components) directly in your Markdown without any extra configuration needed. However, you’re not limited to pre-built components. Docus makes it easy to create your own Vue components in your Nuxt app and use them in your content. Here’s a simple example of a custom `BrowserFrame` component created in the `components` folder of your Nuxt app and integrated inside Markdown: ::tabs :::tabs-item{.my-5 icon="i-lucide-code" label="Code"} ```vue [components/content/BrowserFrame.vue] ``` ::: :::tabs-item{icon="i-simple-icons-markdown" label="Markdown"} ```mdc ::browser-frame{title="The Alps"} ![mountains landscape](/mountains.webp) :: ``` ::: :::tabs-item{icon="i-lucide-eye" label="Preview"} ::::browser-frame{title="The Alps"} ![mountains landscape](https://docus.dev/documentation/mountains.webp) :::: ::: :: This approach lets you create dynamic docs powered by Nuxt components using Markdown. ## Vue Pages In addition to Markdown pages, you can also create Vue pages in the `pages/` directory. ```vue [pages/hello.vue] ``` You can also use the `definePageMeta` function to set the page meta, such as using the `default` or `docs` layout, but also to define if the page should display the header and the footer: ```vue [pages/hello.vue] ``` ## Custom Layouts Docus uses two layouts: - `default` layout for the landing page and custom Vue pages - `docs` layout for the documentation pages If you want to use a different layout, you can create one in the `app/layouts/` directory. ```vue [app/layouts/custom.vue] ``` # Markdown Syntax ## Titles Use titles to introduce main sections. They structure your documentation and help users navigate content. ::code-preview --- class: "[&>div]:*:my-0" --- ## Titles #code ```mdc ## Titles ``` :: ### Subtitles Use subtitles to divide sections further. They create a more detailed content hierarchy for better readability. ::code-preview --- class: "[&>div]:*:my-0" --- ### Subtitles #code ```mdc ### Subtitles ``` :: ::tip Each title and subtitle creates an anchor and shows up automatically in the table of contents. :: ## Text Formatting Docus supports most Markdown formatting options. | Style | How to use | Result | | ------ | ------------ | ---------- | | Bold | `**bold**` | **Bold** | | Italic | `*italic*` | *Italic* | | Strike | `~~strike~~` | ~~Strike~~ | Combine formatting for richer text styles and visual emphasis. | Style | How to use | Result | | ------------- | ------------------- | ----------------- | | Bold Italic | `**_bold italic_**` | ***Bold Italic*** | | Bold Strike | `~~**bold**~~` | ~~**Bold**~~ | | Italic Strike | `~~*italic*~~` | ~~*Italic*~~ | ## Links Links connect different parts of your documentation and external resources, essential for user navigation and providing references. To create a link, wrap the link text in brackets `[]()`. ::code-preview --- class: "[&>div]:*:my-0" --- [Nuxt UI](https://ui.nuxt.com/getting-started/installation/nuxt){rel=""nofollow""} #code ```mdc [Nuxt UI](https://ui.nuxt.com/getting-started/installation/nuxt) ``` :: ### Internal links For linking within your documentation, use root-relative paths like `/getting-started/installation`. ::code-preview --- class: "[&>div]:*:my-0" --- [Installation](https://docus.dev/en/getting-started/installation) #code ```mdc [Installation](/en/getting-started/installation) ``` :: ## Lists Organize related items in a structured, readable format. Markdown supports unordered, ordered, and nested lists for various content needs. ### Unordered Use unordered lists for items without a specific sequence. Start each item with a `-` symbol. ::code-preview --- class: "[&>div]:*:my-0" --- - I'm a list item. - I'm another list item. - I'm the last list item. #code ```mdc - I'm a list item. - I'm another list item. - I'm the last list item. ``` :: ### Ordered Use ordered lists when item order matters, like steps in a process. Start each item with a number. ::code-preview --- class: "[&>div]:*:my-0" --- 1. I'm a list item. 2. I'm another list item. 3. I'm the last list item. #code ```mdc 1. I'm a list item. 2. I'm another list item. 3. I'm the last list item. ``` :: ### Nested Create hierarchical lists with sub-items for complex structures. Indent sub-items by four spaces for nesting. ::code-preview --- class: "[&>div]:*:my-0" --- - I'm a list item. - I'm a nested list item. - I'm another nested list item. - I'm another list item. #code ```mdc - I'm a list item. - I'm a nested list item. - I'm another nested list item. - I'm another list item. ``` :: ## Tables Present structured data in rows and columns clearly. Tables are ideal for comparing data or listing properties. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- | Prop | Default | Type | | ------- | --------- | -------- | | `name` | | `string` | | `size` | `md` | `string` | | `color` | `neutral` | `string` | #code ```mdc | Prop | Default | Type | |---------|-----------|--------------------------| | `name` | | `string`{lang="ts-type"} | | `size` | `md` | `string`{lang="ts-type"} | | `color` | `neutral` | `string`{lang="ts-type"} | ``` :: ## Blockquotes Highlight important quotations, citations, or emphasized text. Blockquotes visually distinguish quoted content. ### Singleline Single-line blockquotes are best for short, impactful quotes or citations that fit within a single line. To create a single-line blockquote, add a `>` in front of a paragraph. Ideal for short and impactful quotes. ::code-preview --- class: "[&>div]:*:my-0" --- > Nuxt UI is a collection of Vue components, composables and utils, oriented on structure and layout and designed to be used as building blocks for your app. #code ```mdc > Nuxt UI is a collection of Vue components, composables and utils, oriented on structure and layout and designed to be used as building blocks for your app. ``` :: ### Multiline Multi-line blockquotes are suitable for longer quotes or when you need to include multiple paragraphs within a single quotation. ::code-preview --- class: "[&>div]:*:my-0" --- > Nuxt UI is a collection of Vue components, composables and utils, oriented on structure and layout and designed to be used as building blocks for your app. > > Create beautiful, responsive, and accessible Vue applications with Nuxt UI. #code ```mdc > Nuxt UI is a collection of Vue components, composables and utils, oriented on structure and layout and designed to be used as building blocks for your app. > > Create beautiful, responsive, and accessible Vue applications with Nuxt UI. ``` :: # Code Blocks ## Basic ### Inline Code Use inline code to display code snippets within text paragraphs. It's ideal for referencing code elements directly in sentences. ::code-preview --- class: "[&>div]:*:my-0" --- `inline code` #code ```mdc `inline code` ``` :: ### Code Blocks Use code blocks to display multi-line code snippets with syntax highlighting. Code blocks are essential for presenting code examples clearly. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` #code ````mdc ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` ```` :: When writing a code-block, you can specify a filename that will be displayed on top of the code block. An icon will be automatically displayed based on the extension or the name. Filenames help users understand the code's location and purpose within a project. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` #code ````mdc ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` ```` :: Every code-block has a built-in copy button that will copy the code to your clipboard. ::tip{to="https://ui.nuxt.com/getting-started/icons/nuxt#theme"} Icons are already defined by default, but you can customize them in your `app.config.ts`: ```ts [app.config.ts] export default defineAppConfig({ ui: { prose: { codeIcon: { terminal: 'i-ph-terminal-window-duotone' } } } }) ``` :: ## Advanced ### CodeGroup Group code blocks in tabs using `code-group`. `code-group` is perfect for showing code examples in multiple languages or package managers. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-group{.w-full} ```bash [pnpm] pnpm add @nuxt/ui ``` ```bash [yarn] yarn add @nuxt/ui ``` ```bash [npm] npm install @nuxt/ui ``` ```bash [bun] bun add @nuxt/ui ``` ::: #code ````mdc ::code-group ```bash [pnpm] pnpm add @nuxt/ui ``` ```bash [yarn] yarn add @nuxt/ui ``` ```bash [npm] npm install @nuxt/ui ``` ```bash [bun] bun add @nuxt/ui ``` :: ```` :: ### CodeTree Display code blocks in a file tree view using `code-tree`. `code-tree` is excellent for showcasing project structures and file relationships. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-tree{default-value="app/app.config.ts"} ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'], future: { compatibilityVersion: 4 }, css: ['~/assets/css/main.css'] }) ``` ```css [app/assets/css/main.css] @import "tailwindcss"; @import "@nuxt/ui"; ``` ```ts [app/app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'sky', colors: 'slate' } } }) ``` ```vue [app/app.vue] ``` ```json [package.json] { "name": "nuxt-app", "private": true, "type": "module", "scripts": { "build": "nuxt build", "dev": "nuxt dev", "generate": "nuxt generate", "preview": "nuxt preview", "postinstall": "nuxt prepare", "lint": "eslint .", "lint:fix": "eslint --fix ." }, "dependencies": { "@iconify-json/lucide": "^1.2.18", "@nuxt/ui": "^4.0.0", "nuxt": "^4.1.0" }, "devDependencies": { "eslint": "^9.34.0", "typescript": "^5.9.3", "vue-tsc": "^3.0.6" } } ``` ```json [tsconfig.json] { "extends": "./.nuxt/tsconfig.json" } ``` ````md [README.md] # Nuxt 4 Minimal Starter Look at the [Nuxt 4 documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. ## Setup Make sure to install the dependencies: ```bash # npm npm install # pnpm pnpm install # yarn yarn install # bun bun install ``` ## Development Server Start the development server on `http://localhost:3000`: ```bash # npm npm run dev # pnpm pnpm run dev # yarn yarn dev # bun bun run dev ``` ## Production Build the application for production: ```bash # npm npm run build # pnpm pnpm run build # yarn yarn build # bun bun run build ``` Locally preview production build: ```bash # npm npm run preview # pnpm pnpm run preview # yarn yarn preview # bun bun run preview ``` Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. ```` ::: :: ### `CodePreview` Use `code-preview` to show code output alongside the code. `code-preview` is ideal for interactive examples and demonstrating code results. Write the code to be previewed in the `default` slot and the actual code in the `code` slot. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" label: Preview --- :::code-preview --- class: "[&>div]:*:my-0" --- `inline code` #code ```mdc `inline code` ``` ::: #code ````mdc ::code-preview `inline code` #code ```mdc `inline code` ``` :: ```` :: ### `CodeCollapse` Use `code-collapse` for long code blocks to keep pages clean. `code-collapse` allows users to expand code blocks only when needed, improving readability. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-collapse --- class: "[&>div]:my-0" --- ```css [main.css] @import "tailwindcss"; @import "@nuxt/ui"; @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` ::: #code ````mdc ::code-collapse ```css [main.css] @import "tailwindcss"; @import "@nuxt/ui"; @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` :: ```` :: # Markdown Components Prose components are replacements for HTML typography tags. They provide a simple way to customize your UI when using Markdown. **Docus and Nuxt UI** provides a set of styled and beautiful prose components to help you write your documentation using the [MDC syntax](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""}. ::note{to="https://ui.nuxt.com/getting-started"} This page highlights only the prose components best suited for writing documentation. However, you can use **any Nuxt UI or Nuxt UI component** in your Markdown. For the full list of available components, visit the Nuxt UI documentation. :: ### `Accordion` Use the `accordion` and `accordion-item` components to display an [Accordion](https://ui.nuxt.com/components/accordion){rel=""nofollow""} in your content. ::tabs :::tabs-item{icon="i-lucide-eye" label="Preview"} ::::accordion :::::accordion-item --- icon: i-lucide-circle-help label: What is Docus and what are its key features?? --- Docus is a fully integrated documentation solution built with Nuxt UI. It's a theme based on the UI documentation template that provides a ready-to-use visual. User can focus on content using Markdown and MDC syntax. ::::: :::::accordion-item --- icon: i-lucide-circle-help label: How do I get started with Docus? --- The only thing you need to start a Docus project is a `content/` folder. You can have a check at the starter for a quick start. ::::: :::::accordion-item{icon="i-lucide-circle-help" label="What is Nuxt UI?"} [Nuxt UI](https://ui.nuxt.com/){rel=""nofollow""} is a collection of premium Vue components, composables and utils. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::accordion :::accordion-item{label="What is Docus and what are its key features??" icon="i-lucide-circle-help"} Docus is a fully integrated documentation solution built with Nuxt UI. It's a theme based on the UI documentation template that provides a ready-to-use visual. User can focus on content using Markdown and MDC syntax. ::: :::accordion-item{label="How do I get started with Docus?" icon="i-lucide-circle-help"} The only thing you need to start a Docus project is a `content/` folder. You can have a check at the starter for a quick start. ::: :::accordion-item{label="What is Nuxt UI?" icon="i-lucide-circle-help"} [Nuxt UI](https://ui.nuxt.com/) is a collection of premium Vue components, composables and utils. ::: :: ``` ::: :: ### `Badge` Use markdown in the default slot of the `badge` component to display a [Badge](https://ui.nuxt.com/components/badge){rel=""nofollow""} in your content. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::badge **v3.0.0** :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::badge **v3.0.0** :: ``` ::: :: ### `Callout` Use markdown in the default slot of the `callout` component to add eye-catching context to your content. Use the `icon` and `color` props to customize it. You can also pass any property from the `` component. You can also use the `note`, `tip`, `warning` and `caution` shortcuts with pre-defined icons and colors. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::div{.flex.flex-col.gap-4.w-full} :::::note{.w-full.my-0} Here's some additional information for you. ::::: :::::tip{.w-full.my-0} Here's a helpful suggestion. ::::: :::::warning{.w-full.my-0} Be careful with this action as it might have unexpected results. ::::: :::::caution{.w-full.my-0} This action cannot be undone. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::note Here's some additional information. :: ::tip Here's a helpful suggestion. :: ::warning Be careful with this action as it might have unexpected results. :: ::caution This action cannot be undone. :: ``` ::: :: ### `Card` and `CardGroup` Use markdown in the default slot of the `card` component to highlight your content. Use the `title`, `icon` and `color` props to customize it. You can also pass any property from the ``. Wrap your `card` components with the `card-group` component to group them together in a grid layout. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::card-group{.w-full.my-0} :::::card --- icon: i-simple-icons-github target: _blank title: Dashboard to: https://github.com/nuxt-ui-templates/dashboard --- A dashboard with multi-column layout. ::::: :::::card --- icon: i-simple-icons-github target: _blank title: SaaS to: https://github.com/nuxt-ui-templates/saas --- A template with landing, pricing, docs and blog. ::::: :::::card --- icon: i-simple-icons-github target: _blank title: Docs to: https://github.com/nuxt-ui-templates/docs --- A documentation with `@nuxt/content` . ::::: :::::card --- icon: i-simple-icons-github target: _blank title: Landing to: https://github.com/nuxt-ui-templates/landing --- A landing page you can use as starting point. ::::: :::: ::: :::tabs-item{.my-5 icon="i-lucide-code" label="Code"} ```mdc :::card-group ::card --- title: Dashboard icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/dashboard target: _blank --- A dashboard with multi-column layout. :: ::card --- title: SaaS icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/saas target: _blank --- A template with landing, pricing, docs and blog. :: ::card --- title: Docs icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/docs target: _blank --- A documentation with `@nuxt/content`. :: ::card --- title: Landing icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/landing target: _blank --- A landing page you can use as starting point. :: ::: ``` ::: :: ### `Collapsible` Wrap your content with the `collapsible` component to display a [Collapsible](https://ui.nuxt.com/components/collapsible){rel=""nofollow""} in your content. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::collapsible | Prop | Default | Type | | ------- | --------- | -------- | | `name` | | `string` | | `size` | `md` | `string` | | `color` | `neutral` | `string` | :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::collapsible | Prop | Default | Type | |---------|-----------|--------------------------| | `name` | | `string`{lang="ts-type"} | | `size` | `md` | `string`{lang="ts-type"} | | `color` | `neutral` | `string`{lang="ts-type"} | :: ``` ::: :: ### `Field` and `FieldGroup` A `field`is a prop or parameter to display in your content. You can group them by `field-group` in a list. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::field-group{.my-0} :::::field{name="analytics" type="boolean"} Default to `false` \- Enables analytics for your project (coming soon). ::::: :::::field{name="blob" type="boolean"} Default to `false` \- Enables blob storage to store static assets, such as images, videos and more. ::::: :::::field{name="cache" type="boolean"} Default to `false` \- Enables cache storage to cache your server route responses or functions using Nitro's `cachedEventHandler` and `cachedFunction` ::::: :::::field{name="database" type="boolean"} Default to `false` \- Enables SQL database to store your application's data. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::field-group ::field{name="analytics" type="boolean"} Default to `false` - Enables analytics for your project (coming soon). :: ::field{name="blob" type="boolean"} Default to `false` - Enables blob storage to store static assets, such as images, videos and more. :: ::field{name="cache" type="boolean"} Default to `false` - Enables cache storage to cache your server route responses or functions using Nitro's `cachedEventHandler` and `cachedFunction` :: ::field{name="database" type="boolean"} Default to `false` - Enables SQL database to store your application's data. :: :: ``` ::: :: ### `Icon` Use the `icon` component to display an [Icon](https://ui.nuxt.com/components/icon){rel=""nofollow""} in your content. ::code-preview :icon{name="i-simple-icons-nuxtdotjs"} #code ```mdc :icon{name="i-simple-icons-nuxtdotjs"} ``` :: ### `Kbd` Use the `kbd` component to display a [Kbd](https://ui.nuxt.com/components/kbd){rel=""nofollow""} in your content. ::code-preview #code ```mdc :kbd{value="meta"} :kbd{value="K"} ``` :: ### `Tabs` Use the `tabs` and `tabs-item` components to display [Tabs](https://ui.nuxt.com/components/tabs){rel=""nofollow""} in your content. ::code-preview :::tabs{.w-full} ::::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. :: ``` :::: ::::tabs-item{icon="i-lucide-eye" label="Preview"} :::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. ::::: :::: ::: #code ````mdc ::tabs{.w-full} :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. :::: ``` :::: :::tabs-item{icon="i-lucide-eye" label="Preview"} :::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. ::::: ::: :: ```` :: ### `Steps` Wrap your headings with the Steps component to display a list of steps. Use the `level` prop to define which heading will be used for the steps. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Preview"} ::::steps{level="4"} #### Start a fresh new project ```bash [Terminal] npm create nuxt@latest -- -t github:nuxt-content/docus ``` #### Run docus CLI to run your dev server ```bash [Terminal] docus dev ``` :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ````mdc ::steps{level="4"} #### Start a fresh new project ```bash [Terminal] npm create nuxt@latest -- -t github:nuxt-content/docus ``` #### Run docus CLI to run your dev server ```bash [Terminal] docus dev ``` :: ```` ::: :: # Images and Embeds ## Markdown Display images or videos using standard Markdown syntax. ### Images ::code-preview ![Nuxt Social Image](https://nuxt.com/new-social.jpg) #code ```mdc ![Nuxt Social Image](https://nuxt.com/new-social.jpg) ``` :: Or with your local images ::code-preview ![Snow-capped mountains in a sea of clouds at sunset](https://docus.dev/mountains.webp) #code ```mdc ![Snow-capped mountains in a sea of clouds at sunset](/mountains.webp) ``` :: ::note{to="https://image.nuxt.com/"} Docus will use `` component under the hood instead of the native `img` tag. :: ### Videos ::code-preview :video{autoplay controls loop src="https://res.cloudinary.com/dcrl8q2g3/video/upload/v1745404403/landing_od8epr.mp4"} #code ```mdc :video{autoplay controls loop src="https://res.cloudinary.com/dcrl8q2g3/video/upload/v1745404403/landing_od8epr.mp4"} ``` :: ### # Assistant ## About the Assistant The assistant answers questions about your documentation through natural language queries. It is embedded directly in your documentation site, so users can find answers quickly and succeed with your product. When users ask questions, the assistant: - **Searches and retrieves** relevant content from your documentation using an [MCP server](https://docus.dev/en/ai/mcp). - **Cites sources** with navigable links to take users directly to referenced pages. - **Generates copyable code examples** to help users implement solutions from your documentation. ## How It Works The assistant uses a multi-agent architecture: 1. **Main Agent** - Receives user questions and decides when to search documentation 2. **Search Agent** - Uses [MCP server](https://docus.dev/en/ai/mcp) tools to find relevant content 3. **Response Generation** - Synthesizes information into helpful, conversational answers By default, the assistant connects to your documentation's built-in MCP server at `/mcp`, giving it access to all your pages without additional configuration. You can also connect to an external MCP server if needed. ## Quick Start ### 1. Install dependencies ::code-group ```bash [npm] npm install ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt ``` ```bash [pnpm] pnpm add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt ``` ```bash [yarn] yarn add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt ``` :: ### 2. Set up AI Gateway authentication Pick **one** of this method: **API key** — Create a key in [Vercel AI Gateway](https://vercel.com/~/ai/api-keys){rel=""nofollow""} and add it to your environment: ```bash [.env] AI_GATEWAY_API_KEY=your-api-key ``` **OIDC (only on Vercel)** — `VERCEL_OIDC_TOKEN` is injected automatically. Nothing to add in the production. For local dev, run `vercel env pull` on a [linked project](https://vercel.com/docs/cli/link){rel=""nofollow""}. ### 3. Deploy Deploy your site — the assistant is available as soon as authentication is configured. ## Using the Assistant Users can interact with the assistant in multiple ways: ### Floating Input On documentation pages, a floating input appears at the bottom of the screen. Users can type their questions directly and press Enter to get answers. ::tip Use the keyboard shortcut :kbd{value="meta"} :kbd{value="I"} to focus the floating input. :: ### Explain with AI Each documentation page includes an **Explain with AI** button in the table of contents sidebar. Clicking this button opens the assistant with the current page as context, asking it to explain the content. ### Slideover Chat When a conversation starts, a slideover panel opens on the right side of the screen. This panel displays the conversation history and allows users to continue asking questions. ## Configuration Configure the assistant through `app.config.ts`: ```ts [app.config.ts] export default defineAppConfig({ assistant: { // Show the floating input on documentation pages floatingInput: true, // Show the "Explain with AI" button in the sidebar explainWithAi: true, // FAQ questions to display when chat is empty faqQuestions: [], // Keyboard shortcuts shortcuts: { focusInput: 'meta_i' }, // Custom icons icons: { trigger: 'i-lucide-sparkles', explain: 'i-lucide-brain' } } }) ``` ### FAQ Questions Display suggested questions when the chat is empty. This helps users discover what they can ask. #### Simple Format ```ts [app.config.ts] export default defineAppConfig({ assistant: { faqQuestions: [ 'How do I install Docus?', 'How do I customize the theme?', 'How do I add components to my pages?' ] } }) ``` #### Category Format Organize questions into categories: ```ts [app.config.ts] export default defineAppConfig({ assistant: { faqQuestions: [ { category: 'Getting Started', items: [ 'How do I install Docus?', 'What is the project structure?' ] }, { category: 'Customization', items: [ 'How do I change the theme colors?', 'How do I add a custom logo?' ] } ] } }) ``` #### Localized Format For multi-language documentation, provide FAQ questions per locale: ```ts [app.config.ts] export default defineAppConfig({ assistant: { faqQuestions: { en: [ { category: 'Getting Started', items: ['How do I install?'] } ], fr: [ { category: 'Démarrage', items: ['Comment installer ?'] } ] } } }) ``` ## Keyboard Shortcuts Configure the keyboard shortcut for focusing the floating input: ```ts [app.config.ts] export default defineAppConfig({ assistant: { shortcuts: { // Default: 'meta_i' (Cmd+I on Mac, Ctrl+I on Windows) focusInput: 'meta_k' // Change to Cmd/Ctrl+K } } }) ``` The shortcut format uses underscores to separate keys. Common examples: - `meta_i` - Cmd+I (Mac) / Ctrl+I (Windows) - `meta_k` - Cmd+K (Mac) / Ctrl+K (Windows) - `ctrl_shift_p` - Ctrl+Shift+P ## Custom Icons Customize the icons used by the assistant: ```ts [app.config.ts] export default defineAppConfig({ assistant: { icons: { // Icon for the trigger button and slideover header trigger: 'i-lucide-bot', // Icon for the "Explain with AI" button explain: 'i-lucide-lightbulb' } } }) ``` Icons use the [Iconify](https://iconify.design/){rel=""nofollow""} format (e.g., `i-lucide-sparkles`, `i-heroicons-sparkles`). ## Internationalization All UI texts are automatically translated based on the user's locale. Docus includes built-in translations for English and French. The following texts are translated: - Slideover title and placeholder - Tooltip texts - Button labels ("Clear chat", "Close", "Explain with AI") - Status messages ("Thinking...", "Chat is cleared on refresh") ## Disable Features ### Disable the Floating Input Hide the floating input at the bottom of documentation pages: ```ts [app.config.ts] export default defineAppConfig({ assistant: { floatingInput: false } }) ``` ### Disable "Explain with AI" Hide the "Explain with AI" button in the documentation sidebar: ```ts [app.config.ts] export default defineAppConfig({ assistant: { explainWithAi: false } }) ``` ### Disable the Assistant Entirely The assistant is disabled when no authentication is available. To explicitly disable it, remove `AI_GATEWAY_API_KEY` from your environment: ```bash [.env] # AI_GATEWAY_API_KEY=your-api-key ``` On Vercel with OIDC, remove the auto-injected system environment variable from your project settings. ## Advanced Configuration Configure advanced options in `nuxt.config.ts` under `docus.assistant`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { // AI model (uses AI SDK Gateway format) model: 'google/gemini-3-flash', // MCP server (path or URL) mcpServer: '/mcp', // API endpoint path apiPath: '/__docus__/assistant' } } }) ``` ### MCP Server Configuration The assistant uses an MCP server to access your documentation. You have two options: #### Use the Built-in MCP Server (Default) By default, the assistant uses Docus's built-in MCP server at `/mcp`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { mcpServer: '/mcp' } } }) ``` ::warning Make sure the MCP server is enabled in your configuration. If you've customized the MCP path, update `mcpServer` accordingly. :: #### Use an External MCP Server Connect to any external MCP server by providing a full URL: ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { mcpServer: 'https://other-docs.example.com/mcp' } } }) ``` This is useful when you want the assistant to answer questions from a different documentation source, or when connecting to a centralized knowledge base. ### Custom AI Model The assistant uses `google/gemini-3-flash` by default. You can change this to any model supported by the AI SDK Gateway: ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { model: 'anthropic/claude-opus-4.5' } } }) ``` ### Site Name in Responses The assistant automatically uses your site name in its responses. Configure the site name in `nuxt.config.ts`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ site: { name: 'My Documentation' } }) ``` This makes the assistant respond as "the My Documentation assistant" and speak with authority about your specific product. ## Programmatic Access Use the `useAssistant` composable to control the assistant programmatically: ```vue ``` ### Composable API | Property | Type | Description | | -------------------------------- | ---------------------- | --------------------------------------------------------------------------------------- | | `isEnabled` | `ComputedRef` | Whether the assistant is enabled (`AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` at build) | | `isOpen` | `Ref` | Whether the slideover is open | | `open(message?, clearPrevious?)` | `Function` | Open the assistant, optionally with a message | | `close()` | `Function` | Close the assistant slideover | | `toggle()` | `Function` | Toggle the assistant open/closed | | `clearMessages()` | `Function` | Clear the conversation history | # MCP Server ## About MCP Servers The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/){rel=""nofollow""} is an open protocol that creates standardized connections between AI applications and external services, like documentation. Every Docus instance includes a built-in MCP server, preparing your content for the broader AI ecosystem where any MCP client (like Claude, Cursor, VS Code, and others) can connect to your documentation. ### How MCP Servers Work When an MCP server is connected to an AI tool, the LLM can decide to use your documentation tools during response generation: - The LLM can **proactively search your documentation** while generating a response, not just when explicitly asked. - The LLM determines **when to use tools** based on the context of the conversation and the relevance of your documentation. - Each tool call happens **during the generation process**, allowing the LLM to incorporate real-time information from your documentation into its response. For example, if a user asks a coding question and the LLM determines that your documentation is relevant, it can search your docs and include that information in the response without the user explicitly asking about your documentation. ## Accessing Your MCP Server Your MCP server is automatically available at the `/mcp` path of your documentation URL. ::note For example, if your documentation is hosted at `https://docs.example.com` , your MCP server URL is `https://docs.example.com/mcp` . :: ## Disable the MCP Server If you want to disable the MCP server, you can do so in your `nuxt.config.ts`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ mcp: { enabled: false, }, }) ``` ## Built-in Tools Docus provides two tools out of the box that allow any LLM to discover and read your documentation: ### `list-pages` Lists all documentation pages with their titles, paths, and descriptions. AI assistants should call this first to discover available content. | Parameter | Type | Description | | --------- | ----------------- | ---------------------- | | `locale` | string (optional) | Filter pages by locale | ### `get-page` Retrieves the full markdown content of a specific documentation page. | Parameter | Type | Description | | --------- | ----------------- | -------------------------------------------------------- | | `path` | string (required) | The page path (e.g., `/en/getting-started/installation`) | ## Setup The Docus MCP server uses HTTP transport and can be installed in different AI assistants. ### Claude Code Add the server using the CLI command: ```bash claude mcp add --transport http my-docs https://docs.example.com/mcp ``` ### Cursor :install-button{ide="cursor" label="Install in Cursor" url="https://docs.example.com/mcp"} Or manually create/update `.cursor/mcp.json` in your project root: ```json [.cursor/mcp.json] { "mcpServers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Visual Studio Code Ensure you have GitHub Copilot and GitHub Copilot Chat extensions installed. :install-button{ide="vscode" label="Install in VS Code" url="https://docs.example.com/mcp"} Or manually create/update the `.vscode/mcp.json` file: ```json [.vscode/mcp.json] { "servers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Windsurf 1. Open Windsurf and navigate to **Settings** > **Windsurf Settings** > **Cascade** 2. Click the **Manage MCPs** button, then select the **View raw config** option 3. Add the following configuration: ```json [.codeium/windsurf/mcp_config.json] { "mcpServers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Zed 1. Open Zed and go to **Settings** > **Open Settings** 2. Navigate to the JSON settings file 3. Add the following context server configuration: ```json [.config/zed/settings.json] { "context_servers": { "my-docs": { "source": "custom", "command": "npx", "args": ["mcp-remote", "https://docs.example.com/mcp"], "env": {} } } } ``` ## Customization Since Docus uses the `@nuxtjs/mcp-toolkit` module, you can extend the MCP server with custom tools, resources, prompts, and handlers. ### Adding Custom Tools Create new tools in the `server/mcp/tools/` directory: ```ts [server/mcp/tools/search.ts] import { z } from 'zod' export default defineMcpTool({ description: 'Search documentation by keyword', inputSchema: { query: z.string().describe('The search query'), }, handler: async ({ query }) => { const results = await searchDocs(query) return { content: [{ type: 'text', text: JSON.stringify(results) }], } }, }) ``` ### Adding Resources Expose files or data sources as MCP resources in the `server/mcp/resources/` directory. The simplest way is using the `file` property: ```ts [server/mcp/resources/changelog.ts] export default defineMcpResource({ file: 'CHANGELOG.md', metadata: { description: 'Project changelog', }, }) ``` This automatically handles URI generation, MIME type detection, and file reading. ### Adding Prompts Create reusable prompts for AI assistants in the `server/mcp/prompts/` directory: ```ts [server/mcp/prompts/migration-help.ts] import { z } from 'zod' export default defineMcpPrompt({ description: 'Get help with migrating between versions', inputSchema: { fromVersion: z.string().describe('Current version'), toVersion: z.string().describe('Target version'), }, handler: async ({ fromVersion, toVersion }) => { return { messages: [{ role: 'user', content: { type: 'text', text: `Help me migrate from version ${fromVersion} to ${toVersion}. What are the breaking changes and steps I need to follow?`, }, }], } }, }) ``` ### Adding Custom Handlers Handlers allow you to create separate MCP endpoints with their own tools, resources, and prompts. This is useful for exposing different capabilities at different routes. For example, you could have: - `/mcp` - Main documentation MCP server - `/mcp/migration` - Dedicated MCP server for migration assistance ```ts [server/mcp/migration.ts] import { z } from 'zod' const migrationTool = defineMcpTool({ name: 'migrate-v3-to-v4', description: 'Migrate code from version 3 to version 4', inputSchema: { code: z.string().describe('The code to migrate'), }, handler: async ({ code }) => { // Migration logic return { content: [{ type: 'text', text: migratedCode }], } }, }) export default defineMcpHandler({ route: '/mcp/migration', name: 'Migration Assistant', version: '1.0.0', tools: [migrationTool], }) ``` ### Overwriting Built-in Tools You can override the default `list-pages` or `get-page` tools by creating a tool with the same name in your project: ```ts [server/mcp/tools/list-pages.ts] import { z } from 'zod' export default defineMcpTool({ description: 'Custom list pages implementation', inputSchema: { locale: z.string().optional(), category: z.string().optional(), }, handler: async ({ locale, category }) => { const pages = await getCustomPageList(locale, category) return { content: [{ type: 'text', text: JSON.stringify(pages) }], } }, }) ``` ::tip{to="https://mcp-toolkit.nuxt.dev/"} Check the MCP Toolkit documentation for more information about tools, resources, prompts, handlers and advanced configuration. :: # Agent Skills ## About Agent Skills Docus automatically discovers skills in your `skills/` directory and serves them at `/.well-known/skills/`, following the [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc){rel=""nofollow""}. This makes your skills installable from any documentation URL with a single command. [Agent Skills](https://agentskills.io/){rel=""nofollow""} are a lightweight, open format for giving AI agents specialized knowledge and workflows. A skill is a `SKILL.md` file with YAML frontmatter that describes what agents can do with your product, along with optional supporting reference files. ::note{to="https://docus.dev/.well-known/skills/index.json"} See the skills published on this documentation site. :: ## Quick Start ::steps ### Create a skill Add a `skills/` directory at the root of your Docus project with a skill subdirectory containing a `SKILL.md` file: ```bash my-docs/ └── skills/ └── my-product/ └── SKILL.md ``` ### Write your SKILL.md Follow the [agentskills.io specification](https://agentskills.io/specification){rel=""nofollow""}. The only required frontmatter field is `description` — `name` defaults to the directory name if omitted: ```md [skills/my-product/SKILL.md] --- name: my-product description: Build and deploy apps with My Product. Use when creating projects, configuring settings, or troubleshooting issues. --- # My Product ## Getting Started Create a new project: \`\`\`bash npx create-my-product my-app \`\`\` ``` ### Deploy Deploy your documentation. Docus automatically serves your skills at `/.well-known/skills/`. ### Share with users Users can install your skills with a single command: ```bash npx skills add https://your-docs-domain.com ``` The CLI detects installed agents (Claude Code, Cursor, Windsurf, and others) and installs the skill to all of them. :: ## Directory Structure A skill directory can contain supporting files beyond `SKILL.md`: ```bash skills/ └── my-product/ ├── SKILL.md # Required: instructions + metadata ├── references/ # Optional: additional documentation │ ├── api.md │ └── configuration.md ├── scripts/ # Optional: executable code │ └── setup.sh └── assets/ # Optional: templates, schemas └── config.template.yaml ``` All files are automatically listed in the `index.json` catalog and served at their respective paths under `/.well-known/skills/{skill-name}/`. ::tip Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files in `references/` — agents load these on demand, so smaller files mean less context usage. :: ## Configuration By default, Docus looks for skills in the `skills/` directory at the root of your project. You can change this with `docus.skills.dir` in your `nuxt.config.ts`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { skills: { dir: 'agent-skills' } } }) ``` ## Skill Name Requirements Skill names must follow the [Agent Skills naming specification](https://agentskills.io/specification#name-field){rel=""nofollow""}: - 1-64 characters - Lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`) - Must not start or end with a hyphen - Must not contain consecutive hyphens (`--`) - The `name` field in frontmatter must match the parent directory name ::note Skills that fail validation are skipped — check your build output for warnings. :: ## Multiple Skills You can publish multiple skills from a single documentation site: ```bash skills/ ├── my-product/ │ └── SKILL.md ├── create-project/ │ ├── SKILL.md │ └── references/ │ └── templates.md └── migration-guide/ └── SKILL.md ``` All skills appear in the `index.json` catalog and are independently installable. ## Preview and Versioning Since skills live in your repository alongside your documentation, they benefit from your existing Git workflow: - **Branch previews**: Test skill changes on preview deployments before merging. On Vercel, every pull request gets a preview URL where you can verify your skills work correctly: ```bash npx skills add https://my-docs-git-feat-new-skill.vercel.app ``` - **Version control**: Track skill changes with Git history, review diffs in pull requests, and roll back if needed. - **CI/CD**: Skills are built and deployed automatically with your documentation — no separate publishing step. ::tip Use preview URLs to test skills with your AI tools before shipping to production. This ensures your skill instructions work correctly with real agents. :: ## How Discovery Works This feature implements the [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc){rel=""nofollow""}, which extends [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615){rel=""nofollow""} (the same `.well-known` standard behind ACME certificate validation and `security.txt`). Docus scans your `skills/` directory at build time and generates two types of endpoints: ### Discovery index ```text GET /.well-known/skills/index.json ``` Returns a JSON catalog listing all available skills with their descriptions and files: ```json { "skills": [ { "name": "my-product", "description": "Build and deploy apps with My Product.", "files": ["SKILL.md", "references/api.md"] } ] } ``` ### Skill files ```text GET /.well-known/skills/{skill-name}/SKILL.md GET /.well-known/skills/{skill-name}/references/api.md ``` Individual skill files are served with appropriate content types (`text/markdown` for `.md` files, `application/json` for `.json`, etc.). ## Comparison with llms.txt Both `llms.txt` and Agent Skills help AI tools work with your documentation, but they serve different purposes: | | llms.txt | Agent Skills | | ------------ | ------------------------------------ | -------------------------------------------------- | | **Purpose** | Directory of all documentation pages | Capability summary with actionable instructions | | **Content** | Page titles, descriptions, and links | Step-by-step workflows, code examples, constraints | | **Loaded** | At discovery time | On demand, when the skill is activated | | **Format** | Plain text with links | Markdown with YAML frontmatter | | **Best for** | Helping agents find information | Teaching agents how to use your product | ::tip Use both together: `llms.txt` tells agents where to find information, while skills tell agents what they can accomplish and how. :: # LLMs Integration Docus integrates `nuxt-llms` by default to prepare your content for Large Language Models (LLMs). All your documentation pages are injected and `/llms.txt` and `/llms-full.txt` files are automatically generated and pre-rendered. ::note{to="https://docus.dev/llms.txt"} Have a check at the `/llms.txt` file generated for Docus documentation itself. :: ## Defaults Here are the default values use to generate the `/llms.txt` file: - `domain` → computed based on your deployment platform (or by using `NUXT_SITE_URL` env variable) - `title` → extracted from your `package.json` - `description` → extracted from your `package.json` - `full.title` → extracted from your `package.json` - `full.description` → extracted from your `package.json` ## Customize You can override your LLMs data from the `nuxt.config.ts` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { domain: 'https://your-site.com', title: 'Your Site Name', description: 'A brief description of your site', full: { title: 'Your Site Name', description: 'A brief description of your site', }, }, }) ``` ## Raw Markdown Access When `nuxt-llms` is enabled, Docus also exposes a raw markdown endpoint so AI agents can fetch LLM-ready source files without going through the full rendering pipeline. This reduces token usage and improves response speed for AI-powered tools consuming your documentation. ### How it works - **Endpoint**: `/raw/.md` — use the same path as the page URL, drop trailing `/index`, and keep the `.md` extension - **Content-Type**: `text/markdown; charset=utf-8` - **Auto-enrichment**: if the requested document is missing a top-level heading or description, the route automatically prepends the title and description to the markdown body - **LLMs.txt integration**: document links in `llms.txt` are automatically rewritten to the `/raw/...md` endpoint, so agents fetch compact markdown instead of full HTML ::note{to="https://docus.dev/raw/en/ai/llms.md"} Try accessing the raw Markdown version of this page. :: ### Configuration You can customize the raw markdown behavior from your `nuxt.config.ts`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { contentRawMarkdown: { // Prevent specific page collections from being exposed excludeCollections: ['landing', 'landing_en', 'landing_fr'], // Keep llms.txt links pointing to rendered pages instead of raw markdown rewriteLLMSTxt: false, }, }, }) ``` To disable raw markdown access entirely: ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { contentRawMarkdown: false, }, }) ``` ## Markdown Redirection ::note This feature is only available when Docus is deployed on Vercel. We'll be able to make it agnostic once Nitro v3 supports global rewrites for multi vendors. :: When deployed on Vercel, Docus automatically configures intelligent routing to serve markdown content to AI agents and CLI tools. ### Why? Agents like Claude Code use `Accept: text/markdown` headers by default, retuning raw Markdown is saving lots of data transfer and tokens in the process. ### How? Docus detects requests from AI agents and command-line tools using HTTP headers: - **Accept header**: Requests with `Accept: text/markdown` are automatically redirected - **User-agent detection**: `curl` requests as agents are automatically redirected ### Redirect Rules - **Root path**: `/` → `/llms.txt` - **Documentation pages**: `/{path}` → `/raw/{path}.md` ### Example Usage ```bash # Get llms.txt from homepage curl -H "Accept: text/markdown" https://docus.dev/ # Get llms.txt from locale homepage curl -H "Accept: text/markdown" https://docus.dev/en # Get raw markdown for a documentation page curl -H "Accept: text/markdown" https://docus.dev/en/ai/llms ``` All these commands will return markdown content instead of HTML. ::tip{to="https://github.com/nuxt-content/nuxt-llms"} Checkout the nuxt-llms documentation for more information about the module. :: # Rédigez votre documentation en Markdown ::u-page-hero #title Créez votre documentation en Markdown #description Publiez instantanément une documentation élégante, optimisée pour le SEO, avec design déjà pensé. :br Docus intègre le meilleur de l’écosystème Nuxt. #links :::u-button --- color: neutral size: xl to: https://docus.dev/fr/getting-started/installation trailing-icon: i-lucide-arrow-right --- Commencer ::: :::u-button --- color: neutral icon: simple-icons-github size: xl to: https://github.com/nuxt-content/docus variant: outline --- Voir sur GitHub ::: #headline :::u-button --- size: sm to: https://github.com/nuxt-content/docus/releases/tag/v5.0.0 variant: outline --- Docus v5 → ::: :: ::u-page-section :::u-page-grid ::::u-page-card --- spotlight: true class: group col-span-2 lg:col-span-1 target: _blank to: https://nuxt.com --- :floating-nuxt #title Construit avec [Nuxt](https://nuxt.com){rel=""nofollow""} #description Optimisé par votre meta framework Vue préféré. Docus vous donne tout ce dont vous avez besoin pour créer des sites rapides, performants et optimisés pour le SEO. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank to: https://ui.nuxt.com --- :::::u-color-mode-image --- height: 320 width: 859 alt: Magnifique visuel propulsé par UI class: w-full h-80 object-cover rounded-lg dark: /landing/dark/templates-ui-pro.webp light: /landing/light/templates-ui-pro.webp --- ::::: #title Stylisé par [Nuxt UI](https://ui.nuxt.com){rel=""nofollow""} #description Sexy, minimaliste et personnalisable. Docus intègre Nuxt UI pour vous offrir la meilleure expérience pour écrire une documentation sans boilerplate, concentrez-vous simplement sur votre contenu. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- :::::tabs ::::::tabs-item{.mt-5 icon="i-lucide-eye" label="Aperçu"} :::::::div{.flex.flex-col.gap-4} ::::::::note{.my-0} Voici des informations supplémentaires pour vous. :::::::: ::::::::tip{.my-0} Voici une suggestion utile. :::::::: ::::::::warning{.my-0} Faites attention à cette action car elle pourrait avoir des résultats inattendus. :::::::: ::::::::caution{.my-0} Cette action est irréversible. :::::::: ::::::: :::::: ::::::tabs-item --- class: mt-5 mb-2 text-xs overflow-x-auto icon: i-lucide-code label: Code --- ```mdc ::note Voici des informations supplémentaires. :: ::tip Voici une suggestion utile. :: ::warning Faites attention à cette action car elle pourrait avoir des résultats inattendus. :: ::caution Cette action est irréversible. :: ``` :::::: ::::: #title Markdown amélioré par [Nuxt Content](https://content.nuxt.com){rel=""nofollow""} #description La seule chose dont vous devez vous soucier est d'écrire votre contenu. Rédigez vos pages en Markdown et intégrer des composants Nuxt UI ou des composants Vue personnalisés. La structure, le routing et le rendu sont gérés pour vous. :::: ::::u-page-card --- class: col-span-2 md:col-span-1 --- :assistant-demo #title [Assistant]{.text-primary} intégré #description Permettez à vos visiteurs de poser des questions sur votre documentation en langage naturel. L'assistant recherche votre contenu et fournit des réponses précises avec les sources citées. :::: ::::u-page-card --- spotlight: true class: col-span-2 md:col-span-1 min-h-[450px] target: _blank --- :color-mode-switch #title [Nuxt Color](https://color-mode.nuxtjs.org){rel=""nofollow""} intégration #description Light et dark mode intégré, aucune configuration nécessaire. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- :::::u-color-mode-image --- height: 554 width: 859 alt: Navigation intégrée et recherche plein texte class: rounded-lg dark: /landing/dark/command-menu.png format: webp light: /landing/light/command-menu.png loading: lazy --- ::::: #title Navigation intégrée et [recherche textuelle]{.text-primary} #description Concentrez-vous uniquement sur votre contenu, Docus génère automatiquement une modale de recherche et la navigation latérale pour vous. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- :::::browser-frame :video{.rounded-md controls loop playsinline src="https://res.cloudinary.com/nuxt/video/upload/v1767647099/studio/studio-demo_eiofld.mp4"} ::::: #title Edition en production avec [Nuxt Studio](https://nuxt.studio){rel=""nofollow""} #description Rédigez et gérez votre contenu visuellement, sans aucune connaissance de Markdown requise. Laissez vos collègues non techniques collaborer sur la documentation et intégrer des composants Vue sans compétences en code. :::: ::::u-page-card --- spotlight: true class: col-span-2 lg:col-span-1 target: _blank to: https://image.nuxt.com/ --- :::::div{.flex-1.flex.items-center.justify-center} ::::::u-color-mode-image --- alt: Visuel Nuxt Image class: w-[30%] lg:w-[70%] my-12 lg:my-0 dark: /landing/dark/nuxt-image.svg light: /landing/light/nuxt-image.svg --- :::::: ::::: #title Optimisation [Nuxt Image](https://image.nuxt.com){rel=""nofollow""} #description Docus convertit automatiquement les images Markdown pour utiliser ``. :::: ::::u-page-card --- spotlight: true class: col-span-2 lg:col-span-1 target: _blank to: https://docus.dev/fr/concepts/internationalization --- :::::u-color-mode-image --- height: 195 width: 403 alt: Illustration de l'internationalisation class: w-full my-12 lg:my-0 dark: /landing/dark/i18n.svg light: /landing/light/i18n.svg --- ::::: #title Support d' [internationalisation]{.text-primary} #description Support i18n intégré avec routage automatique et gestion de contenu. Créez une documentation multilingue sans effort. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank to: https://docus.dev/fr/ai/mcp --- :::::u-color-mode-image --- height: 400 width: 859 alt: Illustration du serveur MCP natif et contenu prêt pour l'IA class: w-full h-auto rounded-lg dark: /landing/dark/mcp.svg light: /landing/light/mcp.svg --- ::::: #title Prêt pour l' [IA avec MCP natif]{.text-primary} #description Serveur Model Context Protocol intégré qui connecte votre documentation aux outils IA comme Cursor, VS Code et Claude. Génération automatique des fichiers `llms.txt` et `llms-full.txt` pour une intégration LLM transparente. :::: ::::u-page-card --- spotlight: true class: col-span-2 target: _blank --- ```ts [app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'green', secondary: 'sky', }, }, socials: { x: 'https://x.com/nuxt_js', nuxt: 'https://nuxt.com' } }) ``` #title Personnalisation avec [Nuxt App Config](https://nuxt.com/docs/4.x/getting-started/configuration#app-configuration){rel=""nofollow""} #description Mettez à jour les couleurs, les liens sociaux, les logos ou même le style de vos composants globalement via le `app.config.ts`, sans modification directe du code. :::: ::::u-page-card --- spotlight: true class: col-span-2 lg:col-span-1 --- :::::div{.flex-1.flex.flex-col.items-center.justify-center.py-8.text-center} ::::::div{.flex.flex-col.gap-3.w-full.max-w-xs} :::::::u-button --- block: true color: primary size: lg to: https://docus.dev/fr/getting-started/introduction trailing-icon: i-lucide-arrow-right --- Lire la documentation ::::::: :::::::u-button --- block: true color: neutral icon: i-simple-icons-github size: lg target: _blank to: https://github.com/nuxt-content/docus variant: outline --- Voir sur GitHub ::::::: :::::: ::::: #title [Prêt]{.text-primary} à commencer ? #description Explorez toutes les fonctionnalités qui font de Docus la solution idéale pour votre documentation. :::: ::: :: # Introduction Bienvenue sur **Docus**, une solution de documentation entièrement intégrée construite avec [Nuxt UI](https://ui.nuxt.com){rel=""nofollow""}. ## Qu'est-ce que Docus ? Docus est un thème basé sur le [template de documentation UI](https://docs-template.nuxt.dev/){rel=""nofollow""}. Le style visuel est prêt à l'emploi, votre priorité doit être d'écrire du contenu en utilisant la syntaxe Markdown et [MDC](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""} fournie par [Nuxt Content](https://content.nuxt.com){rel=""nofollow""}. Nous utilisons ce thème pour toutes nos documentations de modules Nuxt, y compris : ::card-group :::card --- icon: i-lucide-image target: _blank title: Nuxt Image to: https://image.nuxt.com --- La documentation de `@nuxt/image` ::: :::card --- icon: i-simple-icons-nuxtdotjs target: _blank title: Nuxt Content to: https://content.nuxt.com --- La documentation de `@nuxt/content` ::: :::card --- icon: i-simple-icons-supabase target: _blank title: Nuxt Supabase to: https://supabase.nuxtjs.org --- La documentation de `@nuxt/supabase` ::: :::card --- icon: i-simple-icons-strapi target: _blank title: Nuxt Strapi to: https://strapi.nuxtjs.org --- La documentation de `@nuxt/strapi` ::: :: ## Fonctionnalités clés Ce thème inclut de nombreuses fonctionnalités pour améliorer la gestion de votre documentation : - **Propulsé par** **[Nuxt 4](https://nuxt.com){rel=""nofollow""}** : Utilise le dernier framework Nuxt pour des performances optimales. - **Construit avec** **[Nuxt UI](https://ui.nuxt.com){rel=""nofollow""}**: Intègre une suite complète de composants UI. - **[Syntaxe MDC](https://content.nuxt.com/usage/markdown){rel=""nofollow""}** **via** **[Nuxt Content](https://content.nuxt.com){rel=""nofollow""}** : Prend en charge le Markdown avec intégration de composants pour du contenu dynamique. - **[Nuxt Studio](https://content.nuxt.com/docs/studio){rel=""nofollow""}** **Compatible** : Rédigez et éditez votre contenu visuellement. Aucune connaissance Markdown requise ! - **Navigation latérale auto-générée** : Génère automatiquement la navigation à partir de la structure du contenu. - **Recherche plein texte** : Fonctionnalité de recherche intégrée pour découvrir le contenu. - **Typographie optimisée** : Typographie raffinée pour une meilleure lisibilité. - **Mode sombre** : Prend en charge le mode sombre selon la préférence utilisateur. - **Fonctionnalités étendues** : Explorez le thème pour découvrir toutes ses capacités. # Installation ## CLI `create-docus` ::steps ### Créez votre dossier de documentation Utilisez le CLI `create-docus` pour créer un nouveau projet Docus : ```bash [Terminal] npx create-docus my-docs ``` Vous pouvez choisir entre deux templates: - `default` : Configuration Docus de base pour une documentation monolingue - `i18n` : Inclut le support d'internationalisation pour une documentation multilingue ```bash [Terminal] # Créer avec le modèle i18n npx create-docus my-docs -t i18n ``` Nous recommandons d'utiliser le gestionnaire de paquets `npm`. ### Démarrez votre serveur de documentation en mode développement Déplacez-vous dans votre dossier de documentation et démarrez votre serveur: ```bash [Terminal] cd my-docs npm run dev ``` Un aperçu de votre documentation sera disponible sur {rel=""nofollow""} ### Rédigez votre documentation Rendez-vous dans la section [Édition](https://docus.dev/fr/concepts/edition) pour apprendre à rédiger votre documentation. :: ## Skill pour assistant IA Démarrez rapidement avec Docus en ajoutant des connaissances spécialisées à votre assistant IA (Cursor, Claude, etc.) : ```bash [Terminal] npx skills add https://docus.dev ``` Ce skill vous aide à créer de la documentation plus rapidement en fournissant à votre assistant IA : - Les meilleures pratiques pour rédiger de la documentation avec Docus - L'utilisation des composants MDC et des templates prêts à l'emploi - Les guides de rédaction et les modèles de structure de contenu - Les conseils de configuration et de personnalisation Une fois installé, votre assistant IA peut vous aider à créer rapidement de nouveaux projets de documentation, générer des pages avec la bonne structure, et rédiger du contenu en suivant les meilleures pratiques Docus. ::tip{to="https://docus.dev/fr/ai/skills"} Vous pouvez aussi publier vos propres skills depuis votre site Docus. En savoir plus sur les Agent Skills. :: ## Intégration du layer Docus Docus utilise une **approche basée sur les layers Nuxt**, vous pouvez étendre le layer Docus directement dans votre `nuxt.config.ts` avec `extends: ['docus']` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ extends: ['docus'] }) ``` # Structure du projet ## Structure globale Docus est un **layer Nuxt** qui étend votre application Nuxt standard avec des fonctionnalités de documentation. Cela vous donne la flexibilité d'un projet Nuxt classique. Lorsque vous créez un nouveau projet Docus avec `npx create-docus my-docs`, voici la structure de base: ```bash my-docs/ ├── content/ # Votre contenu markdown │ ├── index.md # Page d'accueil │ └── docs/ # Pages de documentation ├── public/ # Ressources statiques └── package.json # Dépendances et scripts ``` Vous pouvez toujours utiliser n'importe quelle fonctionnalité ou fichier d'un projet Nuxt classique : ```bash my-docs/ ├── nuxt.config.ts # Configuration Nuxt (ajouter des modules, composants...) ├── app/ # Répertoire app ├── app.config.ts # App configuration │ ├── components/ # Composants (ajoutez vos propres composants) │ ├── layouts/ # Layouts (ajoutez vos propres layouts) │ └── pages/ # Pages (ajoutez vos propres pages) └── server/ # Code côté serveur (ajoutez votre propre code côté serveur) ``` ### Répertoire `content/` C'est ici que vous [rédigez vos pages](https://docus.dev/fr/concepts/edition) en Markdown. Docus génère automatiquement les routes basées sur votre structure de fichiers. **Structure monolingue :** ```bash content/ ├── index.md # Page d'accueil (/) ├── getting-started.md # Page de documentation (/getting-started) └── guide/ ├── introduction.md # Page de documentation (/guide/introduction) └── configuration.md # Page de documentation (/guide/configuration) ``` ::tip{to="https://docus.dev/fr/concepts/edition"} Vous pouvez séparer vos fichiers de documentation dans un sous-dossier `docs/` pour les rendre accessibles à la route `/docs` . De plus, vous avez la flexibilité de remplacer votre page d'accueil en utilisant des pages Vue personnalisées si désiré. :: **Structure multilingue (avec i18n) :** ```bash content/ ├── en/ │ ├── index.md # Page d'accueil anglaise (/en) │ └── guide/ │ └── introduction.md # Page de documentation (/en/guide/introduction) └── fr/ ├── index.md # Page d'accueil française (/fr) └── guide/ └── introduction.md # Page de documentation (/fr/guide/introduction) ``` ::tip{to="https://docus.dev/fr/concepts/internationalization"} Plus d'informations sur i18n sont disponibles dans la section internationalisation. :: ### Répertoire `public/` Les fichiers contenus dans le répertoire `public/` sont servis à la racine et ne sont pas modifiés par le processus de build. C'est ici que vous pouvez placer vos images, icônes et autres ressources statiques. ### `package.json` Ce fichier contient toutes les dépendances et scripts de votre application. Le `package.json` d'une application Docus est vraiment minimal et ressemble à : ```json [package.json] { "name": "my-docs", "scripts": { "build": "nuxt build --extends docus", "dev": "nuxt dev --extends docus", }, "dependencies": { "docus": "latest", "better-sqlite3": "^12.2.0", "nuxt": "^4.0.0" } } ``` ### `nuxt.config.ts` *Ce fichier n'est pas obligatoire pour démarrer une application Docus.* Vous pouvez ajouter des modules supplémentaires à votre fichier de configuration Nuxt : ```typescript [nuxt.config.ts] export default defineNuxtConfig({ extends: ['@vercel/analytics/nuxt/module'] }) ``` ### `app.config.ts` *Ce fichier n'est pas obligatoire pour démarrer une application Docus.* ::warning Un fichier `nuxt.config.ts` doit être existant pour surcharger votre app config. Sans le fichier Nuxt config, vos surcharges ne seront pas prises en compte. :: C'est ici que vous pouvez [configurer Docus](https://docus.dev/fr/concepts/configuration) pour l'adapter à votre marque, gérer le SEO, définir votre locale et adapter les liens et réseaux sociaux. ```ts [app.config.ts] export default defineAppConfig({ docus: { locale: 'fr', // Définir votre locale monolingue }, seo: { title: 'Ma Documentation', description: 'Ma super documentation', }, // ... autres configurations }) ``` ## Structure complète d'un projet Nuxt Puisque Docus est un layer Nuxt, vous pouvez utiliser **n'importe quelle fonctionnalité** d'un projet Nuxt standard : ::warning Un fichier `nuxt.config.ts` doit être existant pour surcharger votre app Nuxt. Sans le fichier Nuxt config, vos surcharges ne seront pas prises en compte. :: ```bash my-docs/ ├── app/ # Répertoire app (optionnel) │ ├── app.config.ts # App configuration │ ├── app.css # Thème personnalisé (auto-importé par Docus) │ ├── components/ # Composants Vue personnalisés │ ├── layouts/ # Layouts personnalisés │ ├── pages/ # Pages Vue personnalisées (en dehors du contenu) │ ├── composables/ # Composables Vue │ └── middleware/ # Middleware de route ├── server/ # Code côté serveur │ └── api/ # Routes API ├── plugins/ # Plugins Nuxt ├── middleware/ # Middleware global └── modules/ # Modules Nuxt personnalisés ``` ::tip{to="https://docus.dev/fr/concepts/nuxt"} Cette approche basée sur les layers offre toutes les fonctionnalités d'un projet Nuxt classique. :: # Module Studio Le module **Nuxt Studio** est une interface accessible depuis le navigateur permettant d'éditer votre site Nuxt Content directement en production. Accédez-y via une authentification GitHub, GitLab ou Google sur votre site déployé, et commencez à gérer votre contenu sans aucun outil de développement local. ::tip{to="https://nuxt.studio/introduction"} Consultez la documentation de Nuxt Studio pour apprendre comment installer le module. :: :video{controls loop src="https://res.cloudinary.com/nuxt/video/upload/v1767647099/studio/studio-demo_eiofld.mp4"} L'**éditeur Studio** vous permet de gérer entièrement votre contenu depuis votre navigateur sur votre site en production. Pas besoin d'outils de développement local, de commandes Git ou d'accès au terminal. C'est idéal pour les équipes de contenu qui souhaitent éditer et prévisualiser leurs modifications dans un environnement familier. ## Édition visuelle en production pour votre site Nuxt Content Nuxt Studio offre une **édition visuelle directement en production** pour les sites propulsés par Nuxt Content. Initialement proposé comme une plateforme premium autonome, Studio est désormais un **module Nuxt gratuit, open-source et auto-hébergeable**. Il permet à toute votre équipe, développeurs comme éditeurs non-techniques, de créer et mettre à jour du contenu en toute sécurité sans quitter votre site en ligne. ## Fonctionnalités actuelles ### ✨ **Éditeur visuel TipTap** Éditeur Markdown enrichi avec prise en charge complète des composants MDC. ### 💻 **Éditeur de code Monaco** Éditeur de code avancé pour les fichiers Markdown (MDC), YAML et JSON si vous souhaitez éditer le code brut. ### 📝 **Éditeur basé sur des formulaires** Éditez les fichiers YAML, JSON et le frontmatter à l'aide de formulaires générés automatiquement selon les schémas de collections. ### 🎨 **Éditeur de props de composants Vue** Interface visuelle pour éditer les props des composants Vue directement depuis l'éditeur. ### 🔄 **Prévisualisation en temps réel** Prévisualisez instantanément les modifications de contenu sur votre site en production. ### 🔐 **Authentification multi-fournisseurs** Authentification OAuth sécurisée avec GitHub, GitLab et Google. ### 🔑 **Authentification personnalisée** Utilitaires pour implémenter des flux d'authentification personnalisés (mot de passe, SSO, LDAP, etc.). ### 📝 **Gestion des fichiers** Créez, éditez, renommez et supprimez des fichiers de contenu dans le répertoire `content/`. ### 🖼 **Gestion des médias** Bibliothèque de médias centralisée avec prise en charge des formats JPEG, PNG, GIF, WebP, AVIF, SVG et plus encore. ### 🌳 **Intégration Git** Commitez les modifications de contenu directement depuis la production et appuyez-vous sur votre pipeline CI/CD pour les déployer. ### 🚀 **Mode développement** Éditez les fichiers de contenu et de médias directement depuis votre système de fichiers local via l'interface Studio. ### 🌍 **Internationalisation** Prise en charge complète de l'i18n pour 17 langues : AR, BG, DE, EN, ES, FA, FI, FR, ID, IT, JA, NL, PL, PT-BR, UA, ZH, ZH-TW. ## Fonctionnalités à venir ### 📂 **Vue des collections** Gérez et naviguez dans toutes les collections de contenu depuis une interface unifiée. ### 🖼 **Optimisation des médias** Optimisez les images et ressources médias directement dans l'éditeur. ### 🤖 **Assistant IA pour le contenu** Obtenez des suggestions intelligentes alimentées par l'IA pour améliorer et accélérer la création de contenu. ### 💡 **Fonctionnalités pilotées par la communauté** Vous avez une idée ? Partagez vos retours et contribuez à façonner l'avenir de Nuxt Studio. # Migration ## **Migration de Docus v3 vers v4** Docus v4 introduit une nouvelle version qui exploite le CLI Nuxt au lieu du CLI Docus. Votre contenu et vos configurations existants restent compatibles, il suffit simplement de mettre à jour la commande pour lancer le serveur ou le build. ### ⚠️ Breaking changes Les principaux changements cassants sont liés aux commandes CLI : | v3 | v4 | | ------------------------ | ---------------------------- | | `npx docus init my-docs` | `npx create-docus my-docs` | | `docus dev` | `nuxt dev --extends docus` | | `docus build` | `nuxt build --extends docus` | ::tip Votre contenu Markdown existant fonctionnera sans changements. La migration concerne principalement la mise à jour de votre workflow de développement et de build. :: ## **Migrer vers Docus** Vous utilisez déjà une solution basée sur Markdown pour votre documentation ? Que ce soit **Docus v1**, le **template de docs Nuxt UI**, ou une autre solution de site statique, migrer vers Docus est simple et direct. Docus offre une solution propre et maintenable avec une seule dépendance : la bibliothèque Docus elle-même. Plus besoin de gérer de multiples dépendances. Tout est intégré et maintenu ensemble, ce qui facilite la mise à jour de votre documentation. Pour migrer, déplacez simplement vos fichiers Markdown existants dans le dossier `content/` du starter Docus. À partir de là, deux scénarios : - **Si votre documentation actuelle utilise déjà Nuxt Content et la syntaxe MDC**, assurez-vous que les composants utilisés existent dans Nuxt UI. Si certains composants manquent, vous pouvez facilement créer les vôtres. - **Si vous utilisez du Markdown standard**, vous pouvez copier vos fichiers tels quels. Ensuite, améliorez progressivement votre documentation en utilisant les [composants intégrés](https://docus.dev/fr/essentials/components) fournis par Nuxt UI. Une fois votre contenu déplacé dans le dossier `content/`, vous pouvez consulter la [section configuration](https://docus.dev/fr/concepts/configuration) pour personnaliser facilement votre application. Docus est conçu pour se concentrer sur la rédaction de contenu, donc si vous utilisez déjà Markdown, vous pouvez facilement passer à Docus. # Dépannage ## Problèmes avec `pnpm` Si vous rencontrez des erreurs lors du build ou du développement avec `pnpm`, en particulier liées à la dépendance `better-sqlite3`, il se peut que vous deviez approuver certains paquets pour qu’ils puissent être compilés. Exécutez la commande suivante pour approuver les paquets à compiler: ```bash [Terminal] pnpm approve-builds ``` Lorsque vous y êtes invité, sélectionnez `better-sqlite3` et `sharp` dans la liste des packages pour l'approuver pour la compilation. ### Activer le *shameful hoisting* (mode compatibilité) Si vous voyez des erreurs du type `Can't resolve 'tailwindcss'` ou `Can't resolve '@nuxt/ui'`, vous n’avez pas forcément besoin de les importer. Vous pouvez simplement appliquer une structure flat des `node_modules` (comme avec npm ou yarn). Vous pouvez activer le mode compatibilité en créant un fichier `.npmrc` contenant : ```js shamefully-hoist=true ``` # Édition Docus vous permet d'écrire tout votre contenu en **Markdown** mais offre aussi la possibilité d'intégrer des **composants** grâce à la [syntaxe MDC](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""} fournie par **Nuxt Content**. ::tip{to="https://docus.dev/fr/essentials/components"} Consultez la liste des composants prose Nuxt UI que vous pouvez intégrer dans votre Markdown. :: ## Page d'accueil La page d'accueil est la première page que vos visiteurs voient à la racine `/` de votre site. Par défaut, Docus utilise le fichier `content/index.md` pour afficher cette page. ### Page d'accueil Markdown (par défaut) Par défaut, la page d'accueil correspond au fichier `content/index.md`. La syntaxe `MDC` vous offre la possibilité d'utiliser des composants Vue, y compris les slots et les props dans vos fichiers `.md`. Lorsqu'aucune page d'accueil personnalisée n'existe, Docus automatiquement: - Crée une collection de contenu `landing` pour `content/index.md` - Enregistre la route `/` pour afficher votre page d'accueil Markdown ### Page d'accueil Vue personnalisée Vous pouvez personnaliser votre page d'accueil en créant une page Vue à `app/pages/index.vue` (ou `app/pages/[[lang]]/index.vue` pour les configurations i18n). Cela vous donne un contrôle total avec les composants Vue, des layouts personnalisés et des interactions `js` avancées. **Lorsque vous créez** `app/pages/index.vue`, Docus : - Ne créera pas la collection `landing` - N'enregistrera pas la route d'accueil - Utilisera votre page Vue personnalisée comme page d'accueil ::note Cette détection automatique fonctionne pour les configurations monolingues et multilingues (i18n). :: ### Composants MDC fournit une syntaxe dédiée pour utiliser facilement des composants Vue dans votre contenu : ```mdc [content/index.md] :::u-page-feature ::: ``` ### Slots Les slots peuvent recevoir du texte ou d'autres composants. - **Slot par défaut** est rendu directement dans le composant ou avec `#default`. - **Slots nommés** sont définis en utilisant le symbole `#` suivi du nom du slot. ```mdc [index.md] :::u-page-feature #title Nuxt 4 #description Propulsé par Nuxt 4 pour des performances et un SEO optimaux. ::: ``` ### Props Les props sont passées en syntaxe inline ou via le frontmatter YAML dans le bloc du composant : ::tabs :::tabs-item{icon="i-lucide-braces" label="Inline"} ```mdc [index.md] :::u-page-feature{icon="i-simple-icons-nuxt" to="https://nuxt.com"} #title Nuxt 4 #description Propulsé par Nuxt 4 pour des performances et un SEO optimaux. ::: ``` ::: :::tabs-item{icon="i-lucide-code" label="YAML"} ```mdc [index.md] :::u-page-feature --- icon: i-simple-icons-nuxt to: https://nuxt.com --- #title Nuxt 4 #description Propulsé par Nuxt 4 pour des performances et un SEO optimaux. ::: ``` ::: :: ::note{to="https://content.nuxt.com"} Consultez la documentation Nuxt Content pour plus de détails sur la syntaxe MDC :: ## Pages de documentation ::tip Il existe une relation un à un entre les fichiers de contenu et les pages de votre site. Chaque page Markdown dans le dossier `content/` correspond directement à une route de page. :: ### **Sans dossier docs** Pour commencer, éditez ou ajoutez simplement des fichiers `.md` dans le dossier `content/` pour mettre à jour vos pages. Docus gère automatiquement le routage, la navigation et la recherche plein texte. ```bash content/ ├── index.md # Page d'accueil → / ├── getting-started.md # Documentation → /getting-started └── guide/ └── introduction.md # Documentation → /guide/introduction ``` ### **Avec dossier docs** Vous pouvez optionnellement organiser vos fichiers de documentation dans un sous-dossier `docs/`. Lorsque Docus détecte un dossier `docs/` dans votre répertoire `content/`, il préfixe automatiquement toutes les URLs de documentation avec `/docs`. ```bash content/ ├── index.md # Page d'accueil → / └── docs/ ├── getting-started.md # Documentation → /docs/getting-started └── guide/ └── introduction.md # Documentation → /docs/guide/introduction ``` ::tip Ceci est particulièrement utile lorsque vous souhaitez utiliser Docus comme documentation intégrée aux côtés d'autres pages personnalisées. Vous pouvez créer des pages supplémentaires comme un blog, une page de contact, une page de tarification, ou tout autre contenu personnalisé au niveau racine, tout en gardant votre documentation organisée sous `/docs` . :: **Exemple avec contenu mixte :** Puisque Docus est un layer Nuxt, vous pouvez combiner la documentation Markdown avec des pages Vue personnalisées : ```bash ├── app/ │ └── pages/ │ ├── blog.vue # Page blog personnalisée → /blog │ └── contact.vue # Page contact personnalisée → /contact └── content/ ├── index.md # Page d'accueil → / └── docs/ # Documentation → /docs/* ├── getting-started.md └── api/ └── reference.md ``` Cette structure vous donne la flexibilité de construire un site web complet avec Docus. Utilisez Markdown pour la documentation et des pages Vue pour les fonctionnalités personnalisées comme les blogs, tableaux de bord, ou toute page interactive. ### Frontmatter Chaque fichier du dossier `content/` commence par la syntaxe `---` en haut de la page. Cela correspond au frontmatter de votre fichier, une convention des CMS basés sur Markdown pour fournir des métadonnées aux pages. ::tabs :::tabs-item{icon="i-lucide-code" label="Code"} ```md [content/getting-started/edition.md] --- title: 'Édition' description: 'Apprenez à rédiger votre documentation.' --- ``` ::: :::tabs-item{icon="i-lucide-eye" label="Aperçu"} ![Frontmatter titre et description](https://docus.dev/documentation/frontmatter-preview-title-description.png) ::: :: ### Paramètres Les pages du répertoire `/content` sont définies comme type [page](https://content.nuxt.com/docs/collections/types#page-type){rel=""nofollow""} dans Nuxt Content. Elles suivent toutes la même structure avec les clés de frontmatter existantes : | | | | | | ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | - | | Clé | Type | Description | | | `title` | `string` | Titre de la page. Affiché en haut de la page. Utilisé comme titre SEO si la clé `seo` n'est pas fournie. | | | `description` | `string` | Description de la page. Affichée sous le titre en haut de la page. Utilisée comme description SEO si la clé `seo` n'est pas fournie. | | | `navigation` | `boolean` | Définit si la page est incluse dans la navigation latérale gauche. | | | `seo` | `{ title: string, description: string }` | Métadonnées SEO de votre page. | | # Configuration Docus vous permet de configurer votre documentation via le fichier [app.config.ts](https://nuxt.com/docs/guide/directory-structure/app-config){rel=""nofollow""} fourni par Nuxt. ::warning Un fichier `nuxt.config.ts` doit être existant pour surcharger votre app config. Sans le fichier Nuxt config, vos surcharges ne seront pas prises en compte. :: ## SEO Le SEO technique est complexe et fastidieux. Docus propose une configuration par défaut solide et optionnelle qui fonctionne immédiatement, tout en vous laissant la possibilité de personnaliser entièrement vos métadonnées SEO, des titres de page aux images de partage social. ### Métadonnées Docus offre une configuration flexible des métadonnées `SEO`, vous permettant de facilement surcharger les valeurs globalement ou page par page. #### Configuration globale Définissez les métadonnées `SEO` par défaut pour toute votre documentation dans `app.config.ts`. Ces valeurs seront utilisées comme valeurs de repli pour les pages qui ne spécifient pas leurs propres valeurs dans le frontmatter, comme décrit dans la section suivante. Vous pouvez aussi configurer la valeur `site.name` depuis votre fichier `nuxt.config.ts`, la valeur par défaut étant basée sur le nom de votre `package.json`. ::code-group ```ts [app.config.ts] export default defineAppConfig({ seo: { // Par défaut : `%s - ${site.name}` titleTemplate: '' // Par défaut : nom du package.json title: '', // Par défaut : description du package.json description: '' }, }) ``` ```ts [nuxt.config.ts] export default defineNuxtConfig({ site: { name: 'Docus', }, }) ``` :: #### Configuration par page Chaque fichier Markdown du dossier `content/` commence par un bloc frontmatter (`---`). Vous pouvez définir les métadonnées `SEO` par page en utilisant la clé `seo` : ```md [content/concepts/configuration.md] --- seo: title: 'Configuration' description: 'Personnalisez votre documentation Docus depuis le fichier de configuration Nuxt de l'application.' --- ``` ::tip{to="https://docus.dev/fr/concepts/edition#frontmatter"} Pour plus de détails sur le frontmatter, consultez le guide d'édition. :: ### **Image de partage social (OG)** Lorsque vous partagez un lien de votre documentation sur les réseaux sociaux ou certaines plateformes de chat, le lien est **déployé** (unfurled), c'est-à-dire qu'il affiche un aperçu avec un titre, une description et une image. Tout cela est géré par le **protocole Open Graph**. #### Pages de documentation Nous utilisons [Nuxt OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction){rel=""nofollow""} pour générer automatiquement une image OG pour chaque page de documentation à partir du titre et de la description fournis. Par exemple, l'image OG pour la page actuelle est : ![og image documentation page](https://docus.dev/_og/s/c_Docs,headline_Core+Concepts,title_Configuration,description_Customize+your+Docus+documentation+from+Nuxt+application+configuration+file.,p_Ii9lbi9jb25jZXB0cy9jb25maWd1cmF0aW9uIg.png) #### Page d'accueil Comme pour les pages de documentation, la page d'accueil utilise le même générateur d'image OG basé sur le titre et la description fournis. ![og image landing page](https://docus.dev/_og/s/c_Landing,title_Write+beautiful+docs+with+Markdown,description_Ship+fast+flexible+and+SEO-optimized+documentation+with+beautiful+design+out+of+the+box.+Docus+brings+together+the+best+of+the+Nuxt+ecosystem.+Powered+by+Nuxt+UI.,p_Ii9lbiI.png) Cependant, si vous souhaitez personnaliser l'image OG de votre page d'accueil, vous pouvez le faire en ajoutant un chemin **absolu** vers une image dans la clé `seo.ogImage` de votre frontmatter. ```md [content/index.md] --- seo: ogImage: '/social-card.png' --- ``` Nous recommandons d'utiliser une image **1280×640** pour un affichage optimal sur les plateformes sociales. ::tip Les images OG doivent être servies avec des URLs absolues. Par défaut, l'URL du site est déduite de votre plateforme de déploiement, mais vous pouvez la surcharger en définissant la variable d'environnement `NUXT_SITE_URL` . :: ::tip Puisque Docus est un [layer Nuxt](https://nuxt.com/docs/guide/going-further/layers){rel=""nofollow""}, vous pouvez surcharger les templates OG des pages de documentation ou de la page d'accueil en créant un fichier du même nom dans votre propre répertoire `components/OgImage/`. ```text components/ OgImage/ Docs.takumi.vue # surcharge l'image OG des pages de documentation Landing.takumi.vue # surcharge l'image OG de la page d'accueil ``` Votre composant reçoit `title`, `description` et `headline` (pages de documentation uniquement) en tant que props et peut utiliser n'importe quel style Tailwind CSS ou inline supporté par le [renderer Takumi](https://nuxtseo.com/docs/og-image/guides/renderers){rel=""nofollow""}. :: ### Sitemap Docus génère automatiquement un sitemap à `/sitemap.xml` contenant toutes les pages de votre documentation. Cela aide les moteurs de recherche à découvrir et indexer votre contenu. #### Exclure des pages Pour exclure une page spécifique du sitemap, ajoutez `sitemap: false` à son frontmatter : ```md [content/draft-page.md] --- sitemap: false --- Cette page n'apparaîtra pas dans le sitemap. ``` #### URL du site Pour des URLs de sitemap correctes, définissez la variable d'environnement `NUXT_SITE_URL` : ```bash NUXT_SITE_URL=https://votre-site.com ``` ## En-tête Configurez le `title` ou le `logo` de votre site de documentation : ```ts [app.config.ts] export default defineAppConfig({ header: { title: '', logo: { light: '', dark: '', alt: '', }, }, }) ``` ### Brand Assets Vous pouvez configurer des assets de marque additionnels pour votre logo. Un clic droit sur le logo dans l'en-tête ouvre un menu contextuel avec des actions de copie et de téléchargement. ```ts [app.config.ts] export default defineAppConfig({ header: { title: 'Mon Projet', logo: { light: '/logo/logo-dark.svg', dark: '/logo/logo-light.svg', alt: 'Logo Mon Projet', wordmark: { light: '/logo/wordmark-dark.svg', dark: '/logo/wordmark-light.svg', }, favicon: '/favicon.svg', brandAssetsUrl: 'https://example.com/brand', }, }, }) ``` | Champ | Description | | ------------------------------ | ----------------------------------------------------------------------- | | `logo.wordmark.light` / `dark` | Wordmark complet (icône + texte) pour chaque mode couleur. | | `logo.display` | Variante à afficher dans l'en-tête : `'logo'` (défaut) ou `'wordmark'`. | | `logo.class` | Classes CSS additionnelles sur l'image du logo (ex. `'h-8'`). | | `logo.favicon` | Chemin vers le fichier favicon. Par défaut `/favicon.ico`. | | `logo.brandAssetsUrl` | Lien vers votre page de brand assets, affiché dans le menu. | Quand le logo est un SVG, le menu contextuel propose des actions **Copier le logo** et **Copier le wordmark** qui copient le SVG brut avec des fills `currentColor`, prêt à coller dans Figma ou tout outil de design. Pour les formats non-SVG (PNG, etc.), seules les actions de téléchargement sont disponibles. ## Mode couleur Par défaut, Docus inclut un bouton de changement de mode couleur dans l'en-tête et le pied de page, permettant de basculer entre les modes clair et sombre. Si votre documentation n'utilise qu'un seul thème, vous pouvez le forcer en définissant l'option `colorMode` : ```ts [app.config.ts] export default defineAppConfig({ docus: { colorMode: 'dark' } }) ``` | Valeur | Comportement | | ------------- | ----------------------------------------- | | `''` (défaut) | Préférence système avec bouton de bascule | | `'light'` | Force le mode clair, masque le bouton | | `'dark'` | Force le mode sombre, masque le bouton | ### Raccourci clavier Appuyez sur :kbd{value="D"} pour basculer entre les modes clair et sombre lorsque le bouton de mode couleur est visible. Vous pouvez personnaliser ou désactiver ce raccourci dans `app.config.ts` : ```ts [app.config.ts] export default defineAppConfig({ docus: { shortcuts: { toggleColorMode: 'd', // Par défaut }, }, }) ``` Définissez `toggleColorMode` sur une chaîne vide pour désactiver le raccourci. Consultez la page [Assistant](https://docus.dev/fr/ai/assistant#raccourcis-clavier) pour le format des raccourcis (`meta_d`, `ctrl_shift_p`, etc.). Lorsqu'un mode couleur est forcé, le bouton de bascule est masqué de l'en-tête et du pied de page, et les commandes de mode couleur sont retirées de la palette de commandes. ## Navigation ### Sous-navigation Pour les sites de documentation avec de nombreuses sections, vous pouvez activer une sous-navigation qui divise vos dossiers de premier niveau en sections et filtre la barre latérale gauche pour n'afficher que les pages de la section active. Deux modes d'affichage sont disponibles : - **`header`** — affiche une barre d'onglets secondaire sous l'en-tête (desktop uniquement, avec un tiroir sur mobile) - **`aside`** — affiche des ancres de section en haut de la barre latérale gauche (avec un tiroir sur mobile) ```ts [app.config.ts] export default defineAppConfig({ navigation: { sub: 'header', // or 'aside' }, }) ``` :video{src="https://res.cloudinary.com/nuxt/video/upload/v1773263594/docus/subnav_idh2ae.mp4"} ::note Les onglets sont automatiquement générés à partir de vos dossiers de premier niveau dans `content/` . Le titre et l'icône de chaque dossier sont lus depuis son fichier `.navigation.yml` :: ## Recherche Docus inclut une recherche plein texte intégrée alimentée par [Nuxt UI ContentSearch](https://ui.nuxt.com/docs/components/content-search){rel=""nofollow""}. Par défaut, elle utilise le filtrage côté client avec [Fuse.js](https://www.fusejs.io/){rel=""nofollow""} qui charge toutes les sections de recherche au démarrage. ### Recherche plein texte FTS5 Vous pouvez passer à [SQLite FTS5](https://content.nuxt.com/docs/utils/use-search-collection){rel=""nofollow""} pour une recherche indexée plus rapide avec mise en évidence des extraits intégrée. Cela construit un index FTS5 dans le navigateur via SQLite WASM et n'exécute la recherche que lorsqu'une requête est saisie, au lieu de charger toutes les sections au démarrage. ```ts [app.config.ts] export default defineAppConfig({ search: { fts: true } }) ``` | Mode | Index | Vitesse | Tolérance aux fautes | Chargement initial | | ---------------- | -------------------- | ---------------- | -------------------- | ------------------- | | Fuse.js (défaut) | Scan JS en mémoire | O(n) par requête | Fuzzy complet | Toutes les sections | | FTS5 | Index inversé SQLite | O(log n) | Préfixe uniquement | Aucun | ## Liens sociaux Ajoutez vos liens de réseaux sociaux dans le pied de page en utilisant un `Record` où la clé correspond à une icône de la bibliothèque [Simple Icons](https://simpleicons.org/){rel=""nofollow""}. ```ts [app.config.ts] export default defineAppConfig({ socials: { x: 'https://x.com/nuxt_js', discord: 'https://discord.com/invite/ps2h6QT', nuxt: 'https://nuxt.com', } }) ``` ## Table des matières Vous pouvez personnaliser la table des matières dans la barre latérale droite de chaque page. ```ts [app.config.ts] export default defineAppConfig({ toc: { // Renommer le titre de la table des matières title: 'Sur cette page', // Ajouter une section en bas de la table des matières bottom: { title: 'Communauté', links: [{ icon: 'i-lucide-book-open', label: 'Docs Nuxt UI', to: 'https://ui.nuxt.com/getting-started/installation/nuxt', target: '_blank' }] } } }) ``` ## Locale Pour une documentation monolingue (sans le module complet `@nuxtjs/i18n`), vous pouvez configurer la locale via `app.config.ts` : ```ts [app.config.ts] export default defineAppConfig({ docus: { locale: 'fr', // Par défaut : 'en' } }) ``` Ceci définit la langue pour : - Les traductions des composants UI - Les attributs `lang` et `dir` sur la balise `` - Les chaînes d'interface intégrées de Docus ::tip{to="https://docus.dev/fr/concepts/internationalization"} Pour une documentation multilingue avec changement de langue, consultez le [guide d'internationalisation](https://docus.dev/fr/concepts/internationalization) . :: ## Intégration GitHub Docus lit votre dossier `.git/` pour obtenir l'`url` et la `branch` de votre dépôt afin d'ajouter : - Icône GitHub dans l'en-tête et le pied de page - Liens « Modifier cette page » et « Signaler un problème » dans le pied de page de chaque page. Vous pouvez personnaliser l'`url`, la `branch` et le `rootDir` de votre application docs en ajoutant la configuration suivante à votre fichier `app.config.ts` : ```ts [app.config.ts] export default defineAppConfig({ github: { url: 'https://github.com/nuxt-content/docus', branch: 'main', rootDir: 'docs' } }) ``` Si vous ne souhaitez pas utiliser GitHub, vous pouvez définir la clé `github` à `false` pour désactiver l'intégration GitHub. ```ts [app.config.ts] export default defineAppConfig({ github: false }) ``` ::tip{to="https://docus.dev/fr/getting-started/studio"} Ces configurations peuvent aussi être gérées dans l'éditeur Studio, essayez-le ! :: # Thème Docus est construit sur Nuxt UI et tire pleinement parti de Tailwind CSS v4 et des variables CSS. L'API Tailwind Variants offre un système de thème flexible et évolutif. ::tip{to="https://ui.nuxt.com/getting-started/theme"} Pour un aperçu complet du système de thème Nuxt UI, consultez la documentation Nuxt UI. :: ## Surcharger avec `@theme` Vous pouvez personnaliser votre thème avec des variables CSS à l'intérieur d'une directive `@theme` pour définir les tokens de design personnalisés de votre projet, comme les polices, couleurs et breakpoints. Pour surcharger le thème, créez un fichier `app/app.css` dans votre projet : ```css [app/app.css] @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` ::warning Docus importe automatiquement `app/app.css` — vous n'avez pas besoin de l'ajouter au tableau `css` dans `nuxt.config.ts` , et vous ne devez **pas** inclure `@import "tailwindcss"` dans ce fichier car Docus s'en charge pour vous. :: ## Couleurs Docus utilise des alias de couleurs préconfigurés qui servent à styliser les composants et à alimenter les props `color` dans toute l'UI. Chaque badge ci-dessous représente un alias par défaut : - :u-badge{label="primary" variant="outline"} → Couleur principale de la marque, utilisée par défaut pour les composants :br [(défaut : vert)]{.text-xs,text-muted} - :u-badge{color="secondary" label="secondary" variant="outline"} → Couleur secondaire pour compléter la couleur principale :br [(défaut : bleu)]{.text-xs,text-muted} - :u-badge{color="success" label="success" variant="outline"} → Utilisée pour les états de succès :br [(défaut : vert)]{.text-xs,text-muted} - :u-badge{color="info" label="info" variant="outline"} → Utilisée pour les états d'information :br [(défaut : bleu)]{.text-xs,text-muted} - :u-badge{color="warning" label="warning" variant="outline"} → Utilisée pour les avertissements :br [(défaut : jaune)]{.text-xs,text-muted} - :u-badge{color="error" label="error" variant="outline"} → Utilisée pour les erreurs de validation de formulaire :br [(défaut : rouge)]{.text-xs,text-muted} - :u-badge{color="neutral" label="neutral" variant="outline"} → Couleur neutre pour les fonds, textes, etc. :br [(défaut : ardoise)]{.text-xs,text-muted} Vous pouvez personnaliser ces couleurs globalement en mettant à jour le fichier `app.config.ts` sous la clé `ui.colors` : ```ts [app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'blue', neutral: 'zinc' } } }) ``` ## Composants Au-delà des couleurs, tous les [composants Nuxt UI](https://ui.nuxt.com/components){rel=""nofollow""} peuvent être thématisés globalement via `app.config.ts`. Vous pouvez surcharger l'apparence de n'importe quel composant en utilisant la même structure que l'objet de thème interne du composant (affiché [en bas de chaque page de composant](https://ui.nuxt.com/components/card#theme){rel=""nofollow""}). Par exemple, pour changer l'épaisseur de police de tous les boutons : ```ts [app.config.ts] export default defineAppConfig({ ui: { button: { slots: { base: 'font-bold' } } } }) ``` Dans cet exemple, la classe `font-bold` remplacera la classe par défaut `font-medium` sur tous les boutons. ::note{to="https://ui.nuxt.com/components/button#theme"} Pour explorer les options de thème disponibles pour chaque composant, consultez la section **Thème** dans la page de documentation Nuxt UI correspondante. :: ## Sous-composants Docus Docus utilise plusieurs composants Nuxt UI en interne pour la navigation, la table des matières et la sous-navigation. Vous pouvez personnaliser leurs variantes par défaut via `app.config.ts` en utilisant la clé `defaultVariants`, sans avoir à surcharger le composant entier. Les composants suivants sont configurables : | Composant | Clé | Défauts | | -------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------ | | [ContentToc](https://ui.nuxt.com/components/content-toc){rel=""nofollow""} | `ui.contentToc` | `highlight: true` | | [ContentNavigation](https://ui.nuxt.com/components/content-navigation){rel=""nofollow""} | `ui.contentNavigation` | `variant: 'link'`, `highlight: true` | | [NavigationMenu](https://ui.nuxt.com/components/navigation-menu){rel=""nofollow""} | `ui.navigationMenu` | `variant: 'pill'`, `highlight: true` | Par exemple, pour changer le style de surlignage de la table des matières en `circuit` et basculer la variante de la navigation latérale en `pill` : ```ts [app.config.ts] export default defineAppConfig({ ui: { contentToc: { defaultVariants: { highlightVariant: 'circuit', highlightColor: 'secondary' } }, contentNavigation: { defaultVariants: { variant: 'pill', highlight: false } } } }) ``` Chaque composant supporte les options de variantes suivantes : - **`highlight`** — Afficher une ligne d'indicateur actif (`true` ou `false`) - **`highlightColor`** — Couleur de l'indicateur (`primary`, `secondary`, `neutral`, etc.) - **`variant`** — Style visuel (`pill` ou `link`, selon le composant) - **`highlightVariant`** — Style de l'indicateur (`straight` ou `circuit`, ContentToc uniquement) - **`color`** — Couleur de base du lien actif # Personnalisation Docus est construit sur Nuxt 4 qui offre un système de couches de composants flexible permettant de surcharger certaines parties de l'UI en redéfinissant des composants spécifiques dans votre propre application. Cela facilite la personnalisation complète de l'apparence visuelle et du comportement de votre documentation sans toucher au thème principal. Pour surcharger un composant, créez simplement un fichier Vue du même nom dans le dossier `components/`. Docus utilisera automatiquement votre version à la place de celle par défaut. ## En-tête de l'application Vous pouvez personnaliser différentes parties du header en surchargant les composants suivants : ### `AppHeaderLogo` Pour des ajustements simples comme changer la taille du logo, vous pouvez utiliser l'option `logo.class` dans `app.config.ts` sans surcharger le composant (ex. `class: 'h-8'`). Pour remplacer entièrement le logo par défaut dans l'en-tête, créez le fichier `components/AppHeaderLogo.vue`. Votre composant remplacera celui fourni par le thème Docus. Vous pouvez utiliser le composable `useLogoAssets()` pour conserver le menu contextuel de clic droit avec les actions de copie et téléchargement. ![Visualisation du logo d'en-tête](https://docus.dev/documentation/app-header-logo.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/app/components/app/AppHeaderLogo.vue variant: link --- Code du composant par défaut :: ### `AppHeaderLeft` Le logo est placé dans un lien d'accueil par défaut. Pour modifier ce lien (URL, attributs) ou la mise en page autour de `AppHeaderLogo`, surchargez plutôt `components/AppHeaderLeft.vue`. ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderLeft.vue variant: link --- Code du composant par défaut :: ### `AppHeaderCTA` Pour personnaliser la zone d'appel à l'action dans l'en-tête (par exemple, ajouter un bouton « Commencer » ou un lien externe), surchargez le composant `components/AppHeaderCTA.vue`. ![Visualisation du CTA d'en-tête](https://docus.dev/documentation/app-header-cta.webp) ::note --- to: https://github.com/nuxt-content/docus/blob/docs/components/AppHeaderCTA.vue --- Par défaut, ce composant est vide mais vous pouvez voir comment nous le surchargeons sur la documentation Docus elle-même. :: ### `AppHeaderCenter` Pour personnaliser la zone centrale du header, surchargez le composant `components/AppHeaderCenter.vue`. Votre composant remplacera la barre de recherche fournie par le thème Docus. ![Visualisation du centre d'en-tête](https://docus.dev/documentation/app-header-center.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/app/components/app/AppHeaderCenter.vue variant: link --- Code du composant par défaut :: ### `AppHeaderBody` Par défaut, lorsque vous ouvrez le menu en vue mobile, Docus affiche l'arborescence de votre dossier `content/` comme menu avec le composant [ContentNavigation](https://ui.nuxt.com/components/content-navigation){rel=""nofollow""}. Vous pouvez surcharger ce menu avec le composant `components/AppHeaderBody.vue` et remplir le corps du menu (sous l'en-tête) en mobile. ![Visualisation du menu mobile](https://docus.dev/documentation/app-header-body.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/app/components/app/AppHeaderBody.vue variant: link --- Code du composant par défaut :: ### `AppHeaderBottomRight` Lorsque [`navigation.sub`](https://docus.dev/fr/concepts/configuration#sous-navigation) est défini sur `'header'`, Docus affiche une barre d'onglets secondaire sous l'en-tête. Pour ajouter du contenu personnalisé à droite de cette barre (ex. un toggle, un badge), créez un composant `components/AppHeaderBottomRight.vue`. ::note --- to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppHeaderBottom.vue --- Pour remplacer entièrement la barre de sous-navigation, surchargez le composant `AppHeaderBottom.vue` à la place. :: ::tip{to="https://docus.dev/fr/concepts/nuxt"} Si vous souhaitez personnaliser tout le header, vous devriez peut-être envisager d'utiliser un layout personnalisé. :: ## Footer Vous pouvez personnaliser différentes parties du footer en surchargant les composants suivants : ### `AppFooterLeft` Pour remplacer le côté gauche du footer, créez le fichier `components/AppFooterLeft.vue`. Votre composant remplacera celui par défaut fourni par le thème Docus. ![Visualisation du footer gauche](https://docus.dev/documentation/app-footer-left.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppFooterLeft.vue variant: link --- Code du composant par défaut :: ### `AppFooterRight` Pour personnaliser le côté droit du footer, surchargez le composant `components/AppFooterRight.vue`. ![Visualisation du footer droit](https://docus.dev/documentation/app-footer-right.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/main/layer/app/components/app/AppFooterRight.vue variant: link --- Code du composant par défaut :: ::tip{to="https://docus.dev/fr/concepts/nuxt"} Si vous souhaitez personnaliser tout le footer, vous devriez peut-être envisager d'utiliser un layout personnalisé. :: ## Docs Vous pouvez aussi personnaliser l'en-tête et les deux asides des pages de documentation. ### `DocsPageHeaderLinks` Dans la partie droite du header de votre page de documentation, le comportement par défaut de Docus est d'afficher un menu déroulant avec des actions rapides liées à la source Markdown de la page courante. Cela permet au lecteur de : - **Copier un lien direct** vers le fichier `.md` brut dans le presse-papiers. - **Voir la source Markdown** dans un nouvel onglet du navigateur. - **Ouvrir le contenu de la page dans ChatGPT ou Claude**, pré-rempli avec une invite pour analyser le fichier Markdown. Ces actions sont particulièrement utiles pour les contributeurs, lecteurs ou workflows assistés par IA, mais vous pouvez créer votre propre composant `components/DocsPageHeaderLinks.vue` pour le surcharger. ![App Page Header Links](https://docus.dev/documentation/app-page-header-links.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/app/components/docs/DocsHeaderRight.vue variant: link --- Code du composant par défaut :: ### `DocsAsideRightBottom` Pour personnaliser la partie basse de l'aside droit des pages de documentation, créez le composant `components/DocsAsideRightBottom.vue`. Votre composant remplacera la table des matières basse fournie par le thème Docus. ![Docs aside droit bas](https://docus.dev/documentation/docs-aside-right-bottom.webp) ::u-button --- color: neutral icon: i-lucide-code-xml to: https://github.com/nuxt-content/docus/blob/app/components/docs/DocsAsideRightBottom.vue variant: link --- Code du composant par défaut :: ### `DocsAsideLeftTop` Pour personnaliser la partie haute de l'aside gauche des pages de documentation, créez le composant `components/DocsAsideLeftTop.vue`. ![Docs Aside Left Top](https://docus.dev/documentation/docs-aside-left-top.webp) ::note --- to: https://github.com/nuxt/image/blob/docs/docus/docus/app/components/DocsAsideLeftTop.vue --- Par défaut, ce composant est vide mais vous pouvez voir comment nous le surchargeons sur la documentation Nuxt Image. :: ## Icônes personnalisées Docus utilise [Nuxt Icon](https://github.com/nuxt/icon){rel=""nofollow""} avec le fournisseur [Iconify](https://iconify.design/){rel=""nofollow""}, vous donnant accès à des milliers d'icônes prêtes à l'emploi (ex. `i-lucide-arrow-right`, `i-simple-icons-github`). Pour ajouter vos propres icônes, placez des fichiers SVG dans le dossier `assets/icons/` de votre application. Ils sont automatiquement enregistrés sous le préfixe `custom` et disponibles partout dans votre projet. ```text assets/ icons/ my-logo.svg ``` Vous pouvez ensuite les utiliser avec le préfixe `i-custom:` : ```md [content/getting-started.md] --- navigation: icon: i-custom:my-logo --- ``` ```ts [app.config.ts] export default defineAppConfig({ toc: { bottom: { links: [{ icon: 'i-custom:my-logo', label: 'Aperçu', to: '/preview' }] } } }) ``` ```vue [components/MyComponent.vue] ``` ::tip{to="https://iconify.design/docs/icons/icon-set-basics.html"} Les fichiers SVG doivent utiliser `currentColor` pour les remplissages et contours afin que l'icône s'adapte à la couleur du texte. :: # Internationalisation Docus introduit un **support d'internationalisation natif** basé sur le module `@nuxtjs/i18n`, vous permettant de créer une documentation en plusieurs langues avec un routage automatique et une gestion de contenu. ## Fonctionnalités - **Module i18n intégré** : Intégration native avec `@nuxtjs/i18n` - **Routage de locale dynamique** : Préfixage automatique des URL avec les codes de langue (`/en/docs`, `/fr/docs`) - **Collections de contenu par locale** : Gestion séparée du contenu pour chaque langue - **Sélecteur de langue** : Composant intégré pour basculer entre les locales - **Configuration monolingue** : Configuration simple de la locale pour les sites monolingues via `app.config.ts` ## Configuration monolingue Si vous créez une documentation dans une seule langue (sans le module complet `@nuxtjs/i18n`), vous pouvez configurer la locale via `app.config.ts`. Ceci est utile pour définir la langue des composants UI et localiser les chaînes intégrées. ```ts [app.config.ts] export default defineAppConfig({ docus: { locale: 'fr', // Définissez votre locale (par défaut : 'en') } }) ``` Cette configuration affecte : - Les traductions des composants UI (boutons, étiquettes, etc.) - Les attributs `lang` et `dir` sur la balise `` - Les chaînes d'interface intégrées de Docus ## Configuration multilingue Pour une documentation multilingue, utilisez l'intégration complète `@nuxtjs/i18n` comme décrit ci-dessous. ### Configurer un projet existant Pour activer l'i18n dans votre projet Docus, ajoutez le module `@nuxtjs/i18n` à votre `nuxt.config.ts` et définissez vos locales : ```typescript [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxtjs/i18n'], i18n: { defaultLocale: 'en', locales: [ { code: 'en', name: 'English' }, { code: 'fr', name: 'Français' }, ], } }) ``` ::warning Docus surcharge la stratégie `@nuxtjs/i18n` en `prefix` . :: ## Créer un nouveau projet avec le modèle i18n Lors de la création d'un nouveau projet, vous pouvez choisir le modèle i18n pour une internationalisation préconfigurée : ```bash [Terminal] npx create-docus my-docs -t i18n ``` ## Structure des répertoires Lorsque l'i18n est activé, organisez votre contenu par locale dans le répertoire `content/` : ```text content/ ├── en/ # Contenu anglais │ ├── index.md # Page d'accueil anglaise │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ └── guide/ │ └── advanced.md ├── fr/ # Contenu français │ ├── index.md # Page d'accueil française │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ └── guide/ │ └── advanced.md ``` ::warning Chaque locale doit refléter la même structure de répertoires pour maintenir une navigation cohérente entre les langues. :: # Nuxt ## Application Nuxt Docus est construit sur **Nuxt 4**, ce qui signifie que votre projet de documentation est une application Nuxt complète. Lorsque vous générez un projet avec le **CLI Docus**, il ajoute une couche par défaut vous offrant toute la flexibilité d'une application Nuxt standard. Par défaut, le starter Docus ne contient qu'un dossier `content/`, un dossier `public/` et un `package.json`. C'est tout ce dont vous avez besoin pour commencer à rédiger votre documentation. Vous pouvez aller plus loin et utiliser n'importe quelle fonctionnalité d'un projet Nuxt, du [nuxt.config.ts](https://nuxt.com/docs/guide/directory-structure/nuxt-config){rel=""nofollow""} aux [components](https://nuxt.com/docs/guide/directory-structure/nuxt-config){rel=""nofollow""} ou [plugins](https://nuxt.com/docs/guide/directory-structure/plugins){rel=""nofollow""}. ::note Vous pouvez utiliser la [nouvelle structure de répertoires de Nuxt 4](https://nuxt.com/docs/getting-started/upgrade#new-directory-structure){rel=""nofollow""} fournie par la [version de compatibilité 4 .]() Tous les fichiers liés au code front vont dans le dossier `app/` pour une organisation plus claire et de meilleures performances IDE. :: ## Modules Nuxt Vous souhaitez enrichir votre documentation avec des fonctionnalités personnalisées ? Vous pouvez installer et configurer des [modules Nuxt](https://nuxt.com/modules){rel=""nofollow""} comme dans toute application Nuxt. Pour ajouter [Vercel Web Analytics](https://vercel.com/docs/analytics){rel=""nofollow""} à votre documentation : ::steps ### Installez `@vercel/analytics` ```bash [Terminal] npm install @vercel/analytics ``` ### Activez Web Analytics dans `nuxt.config.ts` Pour Nuxt, vous pouvez activer Vercel Analytics sans configuration supplémentaire en utilisant la déclaration de module inline : ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@vercel/analytics/nuxt/module'], }) ``` :: ## Composants personnalisés Grâce à la puissance de `Nuxt Content` et `Nuxt UI`, et avec l'aide de la syntaxe `MDC`, vous pouvez utiliser les [composants Nuxt UI](https://docus.dev/fr/essentials/components) directement dans votre Markdown sans configuration supplémentaire. Cependant, vous n'êtes pas limité aux composants préconçus. Docus facilite la création de vos propres composants Vue dans votre application Nuxt et leur utilisation dans votre contenu. Voici un exemple simple d'un composant personnalisé `BrowserFrame` créé dans le dossier `components` de votre application Nuxt et intégré dans du Markdown : ::tabs :::tabs-item{.my-5 icon="i-lucide-code" label="Code"} ```vue [components/content/BrowserFrame.vue] ``` ::: :::tabs-item{icon="i-simple-icons-markdown" label="Markdown"} ```mdc ::browser-frame{title="Les Alpes"} ![paysage de montagnes](/mountains.webp) :: ``` ::: :::tabs-item{icon="i-lucide-eye" label="Aperçu"} ::::browser-frame{title="Les Alpes"} ![paysage de montagnes](https://docus.dev/documentation/mountains.webp) :::: ::: :: Cette approche vous permet de créer une documentation dynamique propulsée par les composants Nuxt en Markdown. ## Vue Pages En plus des pages Markdown, vous pouvez également créer des pages Vue dans le répertoire `pages/`. ```vue [pages/hello.vue] ``` Vous pouvez également utiliser la fonction `definePageMeta` pour définir les métadonnées de la page, comme l'utilisation du layout `default` ou `docs`, mais aussi pour définir si la page doit afficher l'en-tête et le pied de page : ```vue [pages/hello.vue] ``` ## Layouts personnalisées Docus utilise deux layouts : - Le layout `default` pour la page d'accueil et les pages Vue personnalisées - Le layout `docs` pour les pages de documentation Si vous souhaitez utiliser une mise en page différente, vous pouvez en créer une dans le répertoire `app/layouts/`. ```vue [app/layouts/custom.vue] ``` # Syntaxe Markdown ## Titres Utilisez des titres pour introduire les sections principales. Ils structurent votre documentation et aident les utilisateurs à naviguer dans le contenu. ::code-preview --- class: "[&>div]:*:my-0" --- ## Titres #code ```mdc ## Titres ``` :: ### Sous-titres Utilisez des sous-titres pour diviser davantage les sections. Ils créent une hiérarchie de contenu plus détaillée pour une meilleure lisibilité. ::code-preview --- class: "[&>div]:*:my-0" --- ### Sous-titres #code ```mdc ### Sous-titres ``` :: ::tip Chaque titre et sous-titre crée une ancre et apparaît automatiquement dans la table des matières. :: ## Mise en forme du texte Docus prend en charge la plupart des options de mise en forme Markdown. | Style | Syntaxe | Résultat | | -------- | ------------ | ---------- | | Gras | `**gras**` | **Gras** | | Italique | `*italique*` | *Italique* | | Barré | `~~barré~~` | ~~Barré~~ | Combinez les styles pour enrichir le texte et mettre en valeur des éléments. | Style | Syntaxe | Résultat | | -------------- | --------------------- | ------------------- | | Gras Italique | `**_gras italique_**` | ***Gras Italique*** | | Gras Barré | `~~**gras**~~` | ~~**Gras**~~ | | Italique Barré | `~~*italique*~~` | ~~*Italique*~~ | ## Liens Les liens relient différentes parties de votre documentation et des ressources externes, essentiels pour la navigation et les références. Pour créer un lien, entourez le texte du lien avec des crochets `[]()`. ::code-preview --- class: "[&>div]:*:my-0" --- [Nuxt UI](https://ui.nuxt.com/getting-started/installation/nuxt){rel=""nofollow""} #code ```mdc [Nuxt UI](https://ui.nuxt.com/getting-started/installation/nuxt) ``` :: ### Liens internes Pour lier des pages de votre documentation, utilisez des chemins relatifs à la racine comme `/getting-started/installation`. ::code-preview --- class: "[&>div]:*:my-0" --- [Installation](https://docus.dev/fr/getting-started/installation) #code ```mdc [Installation](/fr/getting-started/installation) ``` :: ## Listes Organisez des éléments liés dans un format structuré et lisible. Markdown prend en charge les listes non ordonnées, ordonnées et imbriquées pour divers besoins. ### Non ordonnée Utilisez des listes non ordonnées pour des éléments sans ordre particulier. Commencez chaque élément par un symbole `-`. ::code-preview --- class: "[&>div]:*:my-0" --- - Je suis un élément de liste. - Je suis un autre élément de liste. - Je suis le dernier élément de liste. #code ```mdc - Je suis un élément de liste. - Je suis un autre élément de liste. - Je suis le dernier élément de liste. ``` :: ### Ordonnée Utilisez des listes ordonnées lorsque l'ordre des éléments est important, comme des étapes d'un processus. Commencez chaque élément par un numéro. ::code-preview --- class: "[&>div]:*:my-0" --- 1. Je suis un élément de liste. 2. Je suis un autre élément de liste. 3. Je suis le dernier élément de liste. #code ```mdc 1. Je suis un élément de liste. 2. Je suis un autre élément de liste. 3. Je suis le dernier élément de liste. ``` :: ### Imbriquée Créez des listes hiérarchiques avec des sous-éléments pour des structures complexes. Indentez les sous-éléments de quatre espaces pour l'imbrication. ::code-preview --- class: "[&>div]:*:my-0" --- - Je suis un élément de liste. - Je suis un élément de liste imbriqué. - Je suis un autre élément de liste imbriqué. - Je suis un autre élément de liste. #code ```mdc - Je suis un élément de liste. - Je suis un élément de liste imbriqué. - Je suis un autre élément de liste imbriqué. - Je suis un autre élément de liste. ``` :: ## Tableaux Présentez des données structurées en lignes et colonnes. Les tableaux sont idéaux pour comparer des données ou lister des propriétés. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- | Prop | Défaut | Type | | ------- | --------- | -------- | | `name` | | `string` | | `size` | `md` | `string` | | `color` | `neutral` | `string` | #code ```mdc | Prop | Défaut | Type | |---------|-----------|--------------------------| | `name` | | `string`{lang="ts-type"} | | `size` | `md` | `string`{lang="ts-type"} | | `color` | `neutral` | `string`{lang="ts-type"} | ``` :: ## Citations Mettez en avant des citations, références ou textes importants. Les citations distinguent visuellement le contenu cité. ### Une ligne Les citations sur une seule ligne sont idéales pour des citations courtes et percutantes. Ajoutez un `>` devant un paragraphe. Idéal pour les citations courtes. ::code-preview --- class: "[&>div]:*:my-0" --- > Nuxt UI est une collection de composants Vue, de composables et d'utilitaires construits sur Nuxt UI, orientés structure et layout, conçus comme des blocs de construction pour votre application. #code ```mdc > Nuxt UI est une collection de composants Vue, de composables et d'utilitaires construits sur Nuxt UI, orientés structure et layout, conçus comme des blocs de construction pour votre application. ``` :: ### Multiligne Les citations multiligne conviennent aux citations plus longues ou pour inclure plusieurs paragraphes dans une seule citation. ::code-preview --- class: "[&>div]:*:my-0" --- > Nuxt UI est une collection de composants Vue, de composables et d'utilitaires construits sur Nuxt UI, orientés structure et layout, conçus comme des blocs de construction pour votre application. > > Créez de belles applications Vue réactives et accessibles avec Nuxt UI. #code ```mdc > Nuxt UI est une collection de composants Vue, de composables et d'utilitaires construits sur Nuxt UI, orientés structure et layout, conçus comme des blocs de construction pour votre application. > > Créez de belles applications Vue réactives et accessibles avec Nuxt UI. ``` :: # Blocs de code ## Basique ### Code en ligne Utilisez le code en ligne pour afficher des extraits de code dans les paragraphes. Idéal pour référencer des éléments de code directement dans les phrases. ::code-preview --- class: "[&>div]:*:my-0" --- `code en ligne` #code ```mdc `code en ligne` ``` :: ### Blocs de code Utilisez les blocs de code pour afficher des extraits de code multi-lignes avec coloration syntaxique. Les blocs de code sont essentiels pour présenter clairement des exemples de code. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` #code ````mdc ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` ```` :: Lorsque vous écrivez un bloc de code, vous pouvez spécifier un nom de fichier qui sera affiché au-dessus du bloc. Une icône sera automatiquement affichée selon l'extension ou le nom. Les noms de fichiers aident les utilisateurs à comprendre l'emplacement et le but du code dans un projet. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` #code ````mdc ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` ```` :: Chaque bloc de code possède un bouton de copie intégré qui permet de copier le code dans le presse-papiers. ::tip{to="https://ui.nuxt.com/getting-started/icons/nuxt#theme"} Les icônes sont déjà définies par défaut, mais vous pouvez les personnaliser dans votre `app.config.ts` : ```ts [app.config.ts] export default defineAppConfig({ ui: { prose: { codeIcon: { terminal: 'i-ph-terminal-window-duotone' } } } }) ``` :: ## Avancé ### CodeGroup Groupez des blocs de code dans des onglets avec `code-group`. `code-group` est parfait pour montrer des exemples de code dans plusieurs langages ou gestionnaires de paquets. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-group{.w-full} ```bash [pnpm] pnpm add @nuxt/ui ``` ```bash [yarn] yarn add @nuxt/ui ``` ```bash [npm] npm install @nuxt/ui ``` ```bash [bun] bun add @nuxt/ui ``` ::: #code ````mdc ::code-group ```bash [pnpm] pnpm add @nuxt/ui ``` ```bash [yarn] yarn add @nuxt/ui ``` ```bash [npm] npm install @nuxt/ui ``` ```bash [bun] bun add @nuxt/ui ``` :: ```` :: ### CodeTree Affichez des blocs de code dans une vue arborescente avec `code-tree`. `code-tree` est excellent pour présenter des structures de projet et des relations de fichiers. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-tree{default-value="app/app.config.ts"} ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@nuxt/ui'], css: ['~/assets/css/main.css'] }) ``` ```css [app/assets/css/main.css] @import "tailwindcss"; @import "@nuxt/ui"; ``` ```ts [app/app.config.ts] export default defineAppConfig({ ui: { colors: { primary: 'sky', colors: 'slate' } } }) ``` ```vue [app/app.vue] ``` ```json [package.json] { "name": "nuxt-app", "private": true, "type": "module", "scripts": { "build": "nuxt build", "dev": "nuxt dev", "generate": "nuxt generate", "preview": "nuxt preview", "postinstall": "nuxt prepare", "lint": "eslint .", "lint:fix": "eslint --fix ." }, "dependencies": { "@iconify-json/lucide": "^1.2.18", "@nuxt/ui": "^4.0.0", "nuxt": "^4.1.0" }, "devDependencies": { "eslint": "^9.34.0", "typescript": "^5.9.3", "vue-tsc": "^3.0.6" } } ``` ```json [tsconfig.json] { "extends": "./.nuxt/tsconfig.json" } ``` ````md [README.md] # Nuxt 4 Minimal Starter Consultez la [documentation Nuxt 4](https://nuxt.com/docs/getting-started/introduction) pour en savoir plus. ## Installation Assurez-vous d'installer les dépendances : ```bash # npm npm install # pnpm pnpm install # yarn yarn install # bun bun install ``` ## Serveur de développement Démarrez le serveur de développement sur `http://localhost:3000` : ```bash # npm npm run dev # pnpm pnpm run dev # yarn yarn dev # bun bun run dev ``` ## Production Construisez l'application pour la production : ```bash # npm npm run build # pnpm pnpm run build # yarn yarn build # bun bun run build ``` Prévisualisez localement la build de production : ```bash # npm npm run preview # pnpm pnpm run preview # yarn yarn preview # bun bun run preview ``` Consultez la [documentation de déploiement](https://nuxt.com/docs/getting-started/deployment) pour plus d'informations. ```` ::: :: ### `CodePreview` Utilisez `code-preview` pour afficher le résultat du code à côté du code. `code-preview` est idéal pour les exemples interactifs et la démonstration de résultats de code. Écrivez le code à prévisualiser dans le slot `default` et le code réel dans le slot `code`. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" label: Aperçu --- :::code-preview --- class: "[&>div]:*:my-0" --- `code en ligne` #code ```mdc `code en ligne` ``` ::: #code ````mdc ::code-preview `code en ligne` #code ```mdc `code en ligne` ``` :: ```` :: ### `CodeCollapse` Utilisez `code-collapse` pour les longs blocs de code afin de garder les pages propres. `code-collapse` permet aux utilisateurs de déplier les blocs de code uniquement si besoin, améliorant ainsi la lisibilité. ::code-preview --- class: "[&>div]:*:my-0 [&>div]:*:w-full" --- :::code-collapse --- class: "[&>div]:my-0" --- ```css [main.css] @import "tailwindcss"; @import "@nuxt/ui"; @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` ::: #code ````mdc ::code-collapse ```css [main.css] @import "tailwindcss"; @import "@nuxt/ui"; @theme { --font-sans: 'Public Sans', sans-serif; --breakpoint-3xl: 1920px; --color-green-50: #EFFDF5; --color-green-100: #D9FBE8; --color-green-200: #B3F5D1; --color-green-300: #75EDAE; --color-green-400: #00DC82; --color-green-500: #00C16A; --color-green-600: #00A155; --color-green-700: #007F45; --color-green-800: #016538; --color-green-900: #0A5331; --color-green-950: #052E16; } ``` :: ```` :: # Composants Markdown Les composants prose sont des remplacements pour les balises de typographie HTML. Ils offrent un moyen simple de personnaliser votre interface lors de l'utilisation de Markdown. **Docus et Nuxt UI** fournissent un ensemble de composants prose stylés et élégants pour vous aider à rédiger votre documentation avec la [syntaxe MDC](https://content.nuxt.com/docs/files/markdown#mdc-syntax){rel=""nofollow""}. ::note{to="https://ui.nuxt.com/getting-started"} Cette page met en avant uniquement les composants prose les plus adaptés à la rédaction de documentation. Cependant, vous pouvez utiliser **n'importe quel composant Nuxt UI** dans votre Markdown. Pour la liste complète des composants disponibles, consultez la documentation Nuxt UI. :: ### `Accordion` Utilisez les composants `accordion` et `accordion-item` pour afficher un [Accordion](https://ui.nuxt.com/components/accordion){rel=""nofollow""} dans votre contenu. ::tabs :::tabs-item{icon="i-lucide-eye" label="Aperçu"} ::::accordion :::::accordion-item --- icon: i-lucide-circle-help label: Qu'est-ce que Docus et quelles sont ses fonctionnalités clés ? --- Docus est une solution de documentation entièrement intégrée construite avec Nuxt UI. C'est un thème inspiré du template de documentation Nuxt UI qui fournit un visuel prêt à l'emploi. L'utilisateur peut se concentrer sur le contenu en utilisant Markdown et la syntaxe MDC. ::::: :::::accordion-item --- icon: i-lucide-circle-help label: Comment démarrer avec Docus ? --- La seule chose dont vous avez besoin pour démarrer un projet Docus est un dossier `content/` . Consultez le starter pour un démarrage rapide. ::::: :::::accordion-item{icon="i-lucide-circle-help" label="Qu'est-ce que Nuxt UI ?"} Nuxt UI est une collection de composants Vue premium, de composables et d'utilitaires construits sur [Nuxt UI](https://ui.nuxt.com/){rel=""nofollow""} . Nuxt UI est gratuit en développement, mais nécessite une licence pour la production. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::accordion :::accordion-item{label="Qu'est-ce que Docus et quelles sont ses fonctionnalités clés ?" icon="i-lucide-circle-help"} Docus est une solution de documentation entièrement intégrée construite avec Nuxt UI. C'est un thème inspiré du template de documentation Nuxt UI qui fournit un visuel prêt à l'emploi. L'utilisateur peut se concentrer sur le contenu en utilisant Markdown et la syntaxe MDC. ::: :::accordion-item{label="Comment démarrer avec Docus ?" icon="i-lucide-circle-help"} La seule chose dont vous avez besoin pour démarrer un projet Docus est un dossier `content/`. Consultez le starter pour un démarrage rapide. ::: :::accordion-item{label="Qu'est-ce que Nuxt UI ?" icon="i-lucide-circle-help"} Nuxt UI est une collection de composants Vue premium, de composables et d'utilitaires construits sur [Nuxt UI](https://ui.nuxt.com/). Nuxt UI est gratuit en développement, mais nécessite une licence pour la production. ::: :: ``` ::: :: ### `Badge` Utilisez du markdown dans le slot par défaut du composant `badge` pour afficher un [Badge](https://ui.nuxt.com/components/badge){rel=""nofollow""} dans votre contenu. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ::::badge **v3.0.0** :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::badge **v3.0.0** :: ``` ::: :: ### `Callout` Utilisez du markdown dans le slot par défaut du composant `callout` pour ajouter un contexte visuel à votre contenu. Utilisez les props `icon` et `color` pour le personnaliser. Vous pouvez aussi passer n'importe quelle propriété du composant ``. Vous pouvez également utiliser les raccourcis `note`, `tip`, `warning` et `caution` avec des icônes et couleurs prédéfinies. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ::::div{.flex.flex-col.gap-4.w-full} :::::note{.w-full.my-0} Voici des informations supplémentaires pour vous. ::::: :::::tip{.w-full.my-0} Voici une suggestion utile. ::::: :::::warning{.w-full.my-0} Faites attention à cette action car elle pourrait avoir des résultats inattendus. ::::: :::::caution{.w-full.my-0} Cette action est irréversible. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::note Voici des informations supplémentaires. :: ::tip Voici une suggestion utile. :: ::warning Faites attention à cette action car elle pourrait avoir des résultats inattendus. :: ::caution Cette action est irréversible. :: ``` ::: :: ### `Card` et `CardGroup` Utilisez du markdown dans le slot par défaut du composant `card` pour mettre en avant votre contenu. Utilisez les props `title`, `icon` et `color` pour le personnaliser. Vous pouvez aussi passer n'importe quelle propriété du composant ``. Regroupez vos composants `card` avec le composant `card-group` pour les afficher en grille. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ::::card-group{.w-full.my-0} :::::card --- icon: i-simple-icons-github target: _blank title: Tableau de bord to: https://github.com/nuxt-ui-templates/dashboard --- Un tableau de bord avec une mise en page multi-colonnes. ::::: :::::card --- icon: i-simple-icons-github target: _blank title: SaaS to: https://github.com/nuxt-ui-templates/saas --- Un template avec landing, pricing, docs et blog. ::::: :::::card --- icon: i-simple-icons-github target: _blank title: Docs to: https://github.com/nuxt-ui-templates/docs --- Une documentation avec `@nuxt/content` . ::::: :::::card --- icon: i-simple-icons-github target: _blank title: Landing to: https://github.com/nuxt-ui-templates/landing --- Une page d'accueil à utiliser comme point de départ. ::::: :::: ::: :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ```mdc :::card-group ::card --- title: Tableau de bord icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/dashboard target: _blank --- Un tableau de bord avec une mise en page multi-colonnes. :: ::card --- title: SaaS icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/saas target: _blank --- Un template avec landing, pricing, docs et blog. :: ::card --- title: Docs icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/docs target: _blank --- Une documentation avec `@nuxt/content`. :: ::card --- title: Landing icon: i-simple-icons-github to: https://github.com/nuxt-ui-templates/landing target: _blank --- Une page d'accueil à utiliser comme point de départ. :: ::: ``` ::: :: ### `Collapsible` Enveloppez votre contenu avec le composant `collapsible` pour afficher un [Collapsible](https://ui.nuxt.com/components/collapsible){rel=""nofollow""} dans votre contenu. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ::::collapsible | Prop | Défaut | Type | | ------- | --------- | -------- | | `name` | | `string` | | `size` | `md` | `string` | | `color` | `neutral` | `string` | :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::collapsible | Prop | Défaut | Type | |---------|-----------|--------------------------| | `name` | | `string`{lang="ts-type"} | | `size` | `md` | `string`{lang="ts-type"} | | `color` | `neutral` | `string`{lang="ts-type"} | :: ``` ::: :: ### `Field` et `FieldGroup` Un `field` est une prop ou un paramètre à afficher dans votre contenu. Vous pouvez les regrouper avec `field-group` dans une liste. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ::::field-group{.my-0} :::::field{name="analytics" type="boolean"} Par défaut à `false` \- Active l'analytics pour votre projet (bientôt disponible). ::::: :::::field{name="blob" type="boolean"} Par défaut à `false` \- Active le stockage blob pour stocker des assets statiques, comme des images, vidéos et plus. ::::: :::::field{name="cache" type="boolean"} Par défaut à `false` \- Active le cache pour mettre en cache les réponses de vos routes serveur ou fonctions avec `cachedEventHandler` et `cachedFunction` de Nitro. ::::: :::::field{name="database" type="boolean"} Par défaut à `false` \- Active la base de données SQL pour stocker les données de votre application. ::::: :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::field-group ::field{name="analytics" type="boolean"} Par défaut à `false` - Active l'analytics pour votre projet (bientôt disponible). :: ::field{name="blob" type="boolean"} Par défaut à `false` - Active le stockage blob pour stocker des assets statiques, comme des images, vidéos et plus. :: ::field{name="cache" type="boolean"} Par défaut à `false` - Active le cache pour mettre en cache les réponses de vos routes serveur ou fonctions avec `cachedEventHandler` et `cachedFunction` de Nitro. :: ::field{name="database" type="boolean"} Par défaut à `false` - Active la base de données SQL pour stocker les données de votre application. :: :: ``` ::: :: ### `Icon` Utilisez le composant `icon` pour afficher une [Icône](https://ui.nuxt.com/components/icon){rel=""nofollow""} dans votre contenu. ::code-preview :icon{name="i-simple-icons-nuxtdotjs"} #code ```mdc :icon{name="i-simple-icons-nuxtdotjs"} ``` :: ### `Kbd` Utilisez le composant `kbd` pour afficher un [Kbd](https://ui.nuxt.com/components/kbd){rel=""nofollow""} dans votre contenu. ::code-preview #code ```mdc :kbd{value="meta"} :kbd{value="K"} ``` :: ### `Tabs` Utilisez les composants `tabs` et `tabs-item` pour afficher des [Onglets](https://ui.nuxt.com/components/tabs){rel=""nofollow""} dans votre contenu. ::code-preview :::tabs{.w-full} ::::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. :: ``` :::: ::::tabs-item{icon="i-lucide-eye" label="Aperçu"} :::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. ::::: :::: ::: #code ````mdc ::tabs{.w-full} :::tabs-item{icon="i-lucide-code" label="Code"} ```mdc ::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. :::: ``` :::: :::tabs-item{icon="i-lucide-eye" label="Aperçu"} :::::callout Lorem velit voluptate ex reprehenderit ullamco et culpa. ::::: ::: :: ```` :: ### `Steps` Enveloppez vos titres avec le composant Steps pour afficher une liste d'étapes. Utilisez la prop `level` pour définir quel titre sera utilisé pour les étapes. ::tabs :::tabs-item{.my-5 icon="i-lucide-eye" label="Aperçu"} ::::steps{level="4"} #### Démarrer un nouveau projet ```bash [Terminal] npm create nuxt@latest -- -t github:nuxt-content/docus ``` #### Lancer le CLI docus pour démarrer votre serveur de dev ```bash [Terminal] docus dev ``` :::: ::: :::tabs-item{icon="i-lucide-code" label="Code"} ````mdc ::steps{level="4"} #### Démarrer un nouveau projet ```bash [Terminal] npm create nuxt@latest -- -t github:nuxt-content/docus ``` #### Lancer le CLI docus pour démarrer votre serveur de dev ```bash [Terminal] docus dev ``` :: ```` ::: :: # Images et intégrations ## Markdown Affichez des images ou des vidéos en utilisant la syntaxe Markdown standard. ### Images ::code-preview ![Image Nuxt Social](https://nuxt.com/new-social.jpg) #code ```mdc ![Image Nuxt Social](https://nuxt.com/new-social.jpg) ``` :: Ou avec vos images locales ::code-preview ![Montagnes enneigées dans une mer de nuages au coucher du soleil](https://docus.dev/mountains.webp) #code ```mdc ![Montagnes enneigées dans une mer de nuages au coucher du soleil](/mountains.webp) ``` :: ::note{to="https://image.nuxt.com/"} Docus utilisera le composant `` sous le capot à la place de la balise native `img` . :: ### Vidéos ::code-preview :video{autoplay controls loop src="https://res.cloudinary.com/dcrl8q2g3/video/upload/v1745404403/landing_od8epr.mp4"} #code ```mdc :video{autoplay controls loop src="https://res.cloudinary.com/dcrl8q2g3/video/upload/v1745404403/landing_od8epr.mp4"} ``` :: ### # Assistant ## À propos de l'Assistant L'assistant répond aux questions sur votre documentation via des requêtes en langage naturel. Il est intégré directement dans votre site de documentation, permettant aux utilisateurs de trouver rapidement des réponses. Lorsque les utilisateurs posent des questions, l'assistant : - **Recherche et récupère** le contenu pertinent de votre documentation en utilisant un [serveur MCP](https://docus.dev/fr/ai/mcp). - **Cite les sources** avec des liens navigables vers les pages référencées. - **Génère des exemples de code** copiables pour aider les utilisateurs à implémenter les solutions. ## Comment ça fonctionne L'assistant utilise une architecture multi-agents : 1. **Agent principal** - Reçoit les questions des utilisateurs et décide quand rechercher dans la documentation 2. **Agent de recherche** - Utilise les outils du [serveur MCP](https://docus.dev/fr/ai/mcp) pour trouver le contenu pertinent 3. **Génération de réponse** - Synthétise les informations en réponses utiles et conversationnelles Par défaut, l'assistant se connecte au serveur MCP intégré de votre documentation à `/mcp`, lui donnant accès à toutes vos pages sans configuration supplémentaire. Vous pouvez également vous connecter à un serveur MCP externe si nécessaire. ## Démarrage rapide ### 1. Installer les dépendances ::code-group ```bash [npm] npm install ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt ``` ```bash [pnpm] pnpm add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt ``` ```bash [yarn] yarn add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt ``` :: ### 2. Configurer l'authentification AI Gateway Choisissez **une** de ces méthodes : **Clé API** — Créez une clé dans [Vercel AI Gateway](https://vercel.com/~/ai/api-keys){rel=""nofollow""} et ajoutez-la à votre environnement : ```bash [.env] AI_GATEWAY_API_KEY=votre-cle-api ``` **OIDC (uniquement sur Vercel)** — `VERCEL_OIDC_TOKEN` est injecté automatiquement. Rien à ajouter en production. En local, lancez `vercel env pull` sur un [projet lié](https://vercel.com/docs/cli/link){rel=""nofollow""}. ### 3. Déployer Déployez votre site — l'assistant est disponible dès que l'authentification est configurée. ## Utiliser l'Assistant Les utilisateurs peuvent interagir avec l'assistant de plusieurs façons : ### Input flottant Sur les pages de documentation, un champ de saisie flottant apparaît en bas de l'écran. Les utilisateurs peuvent taper leurs questions directement et appuyer sur Entrée pour obtenir des réponses. ::tip Utilisez le raccourci clavier :kbd{value="meta"} :kbd{value="I"} pour activer l'input flottant. :: ### Expliquer avec l'IA Chaque page de documentation inclut un bouton **Explain with AI** dans la barre latérale de la table des matières. Cliquer sur ce bouton ouvre l'assistant avec la page actuelle comme contexte. ### Chat en panneau latéral Lorsqu'une conversation commence, un panneau coulissant s'ouvre sur le côté droit de l'écran. Ce panneau affiche l'historique de la conversation et permet aux utilisateurs de continuer à poser des questions. ## Configuration Configurez l'assistant via `app.config.ts` : ```ts [app.config.ts] export default defineAppConfig({ assistant: { // Afficher l'input flottant sur les pages de documentation floatingInput: true, // Afficher le bouton "Expliquer avec l'IA" dans la barre latérale explainWithAi: true, // Questions FAQ à afficher quand le chat est vide faqQuestions: [], // Raccourcis clavier shortcuts: { focusInput: 'meta_i' }, // Icônes personnalisées icons: { trigger: 'i-lucide-sparkles', explain: 'i-lucide-brain' } } }) ``` ### Questions FAQ Affichez des questions suggérées quand le chat est vide. Cela aide les utilisateurs à découvrir ce qu'ils peuvent demander. #### Format simple ```ts [app.config.ts] export default defineAppConfig({ assistant: { faqQuestions: [ 'Comment installer Docus ?', 'Comment personnaliser le thème ?', 'Comment ajouter des composants à mes pages ?' ] } }) ``` #### Format avec catégories Organisez les questions en catégories : ```ts [app.config.ts] export default defineAppConfig({ assistant: { faqQuestions: [ { category: 'Démarrage', items: [ 'Comment installer Docus ?', 'Quelle est la structure du projet ?' ] }, { category: 'Personnalisation', items: [ 'Comment changer les couleurs du thème ?', 'Comment ajouter un logo personnalisé ?' ] } ] } }) ``` #### Format multilingue Pour une documentation multilingue, fournissez les questions FAQ par locale : ```ts [app.config.ts] export default defineAppConfig({ assistant: { faqQuestions: { en: [ { category: 'Getting Started', items: ['How do I install?'] } ], fr: [ { category: 'Démarrage', items: ['Comment installer ?'] } ] } } }) ``` ## Raccourcis clavier Configurez le raccourci clavier pour activer l'input flottant : ```ts [app.config.ts] export default defineAppConfig({ assistant: { shortcuts: { // Par défaut : 'meta_i' (Cmd+I sur Mac, Ctrl+I sur Windows) focusInput: 'meta_k' // Changer pour Cmd/Ctrl+K } } }) ``` Le format de raccourci utilise des underscores pour séparer les touches. Exemples courants : - `meta_i` - Cmd+I (Mac) / Ctrl+I (Windows) - `meta_k` - Cmd+K (Mac) / Ctrl+K (Windows) - `ctrl_shift_p` - Ctrl+Shift+P ## Icônes personnalisées Personnalisez les icônes utilisées par l'assistant : ```ts [app.config.ts] export default defineAppConfig({ assistant: { icons: { // Icône pour le bouton déclencheur et l'en-tête du panneau trigger: 'i-lucide-bot', // Icône pour le bouton "Expliquer avec l'IA" explain: 'i-lucide-lightbulb' } } }) ``` Les icônes utilisent le format [Iconify](https://iconify.design/){rel=""nofollow""} (ex: `i-lucide-sparkles`, `i-heroicons-sparkles`). ## Internationalisation Tous les textes de l'interface sont automatiquement traduits selon la locale de l'utilisateur. Docus inclut des traductions intégrées pour l'anglais et le français. Les textes suivants sont traduits : - Titre et placeholder du panneau - Textes des infobulles - Libellés des boutons ("Effacer le chat", "Fermer", "Expliquer avec l'IA") - Messages de statut ("Réflexion...", "Le chat est effacé au rechargement") ## Désactiver des fonctionnalités ### Désactiver l'input flottant Masquez l'input flottant en bas des pages de documentation : ```ts [app.config.ts] export default defineAppConfig({ assistant: { floatingInput: false } }) ``` ### Désactiver "Explain with AI" Masquez le bouton "Explain with AI" dans la barre latérale de documentation : ```ts [app.config.ts] export default defineAppConfig({ assistant: { explainWithAi: false } }) ``` ### Désactiver l'assistant entièrement L'assistant est désactivé quand aucune authentification n'est disponible. Pour le désactiver explicitement, supprimez `AI_GATEWAY_API_KEY` de votre environnement : ```bash [.env] # AI_GATEWAY_API_KEY=votre-cle-api ``` Sur Vercel avec OIDC, supprimez la variable d'environnement système auto-injectée dans les paramètres de votre projet. ## Configuration avancée Configurez les options avancées dans `nuxt.config.ts` sous `docus.assistant`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { // Modèle IA (utilise le format AI SDK Gateway) model: 'google/gemini-3-flash', // Serveur MCP (chemin ou URL) mcpServer: '/mcp', // Chemin de l'endpoint API apiPath: '/__docus__/assistant' } } }) ``` ### Configuration du serveur MCP L'assistant utilise un serveur MCP pour accéder à votre documentation. Vous avez deux options : #### Utiliser le serveur MCP intégré (par défaut) Par défaut, l'assistant utilise le serveur MCP intégré de Docus à `/mcp` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { mcpServer: '/mcp' } } }) ``` ::warning Assurez-vous que le serveur MCP est activé dans votre configuration. Si vous avez personnalisé le chemin MCP, mettez à jour `mcpServer` en conséquence. :: #### Utiliser un serveur MCP externe Connectez-vous à n'importe quel serveur MCP externe en fournissant une URL complète : ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { mcpServer: 'https://autre-docs.exemple.com/mcp' } } }) ``` C'est utile lorsque vous voulez que l'assistant réponde aux questions d'une autre source de documentation, ou lors de la connexion à une base de connaissances centralisée. ### Modèle IA personnalisé L'assistant utilise `google/gemini-3-flash` par défaut. Vous pouvez le changer pour n'importe quel modèle supporté par AI SDK Gateway : ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { assistant: { model: 'anthropic/claude-opus-4.5' } } }) ``` ### Nom du site dans les réponses L'assistant utilise automatiquement le nom de votre site dans ses réponses. Configurez le nom du site dans `nuxt.config.ts` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ site: { name: 'Ma Documentation' } }) ``` Cela permet à l'assistant de répondre en tant qu'"assistant de Ma Documentation" et de parler avec autorité sur votre produit spécifique. ## Accès programmatique Utilisez le composable `useAssistant` pour contrôler l'assistant programmatiquement : ```vue ``` ### API du composable | Propriété | Type | Description | | -------------------------------- | ---------------------- | -------------------------------------------------------------------------------- | | `isEnabled` | `ComputedRef` | Si l'assistant est activé (`AI_GATEWAY_API_KEY` ou `VERCEL_OIDC_TOKEN` au build) | | `isOpen` | `Ref` | Si le panneau est ouvert | | `open(message?, clearPrevious?)` | `Function` | Ouvrir l'assistant, optionnellement avec un message | | `close()` | `Function` | Fermer le panneau de l'assistant | | `toggle()` | `Function` | Basculer l'assistant ouvert/fermé | | `clearMessages()` | `Function` | Effacer l'historique de conversation | # Serveur MCP ## À Propos des Serveurs MCP Le [Model Context Protocol (MCP)](https://modelcontextprotocol.io/){rel=""nofollow""} est un protocole ouvert qui crée des connexions standardisées entre les applications IA et les services externes, comme la documentation. Chaque instance Docus inclut un serveur MCP intégré, préparant votre contenu pour l'écosystème IA plus large où n'importe quel client MCP (comme Claude, Cursor, VS Code, et autres) peut se connecter à votre documentation. ### Comment Fonctionnent les Serveurs MCP Lorsqu'un serveur MCP est connecté à un outil IA, le LLM peut décider d'utiliser les outils de votre documentation pendant la génération de réponse : - Le LLM peut **rechercher proactivement dans votre documentation** pendant qu'il génère une réponse, pas seulement quand on lui demande explicitement. - Le LLM détermine **quand utiliser les outils** en fonction du contexte de la conversation et de la pertinence de votre documentation. - Chaque appel d'outil se produit **pendant le processus de génération**, permettant au LLM d'incorporer des informations en temps réel de votre documentation dans sa réponse. Par exemple, si un utilisateur pose une question de code et que le LLM détermine que votre documentation est pertinente, il peut rechercher dans vos docs et inclure ces informations dans la réponse sans que l'utilisateur demande explicitement votre documentation. ## Accéder à Votre Serveur MCP Votre serveur MCP est automatiquement disponible au chemin `/mcp` de l'URL de votre documentation. ::note Par exemple, si votre documentation est hébergée à `https://docs.example.com` , l'URL de votre serveur MCP est `https://docs.example.com/mcp` . :: ## Désactiver le Serveur MCP Si vous souhaitez désactiver le serveur MCP, vous pouvez le faire dans votre `nuxt.config.ts` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ mcp: { enabled: false, }, }) ``` ## Outils Intégrés Docus fournit deux outils par défaut qui permettent à n'importe quel LLM de découvrir et lire votre documentation : ### `list-pages` Liste toutes les pages de documentation avec leurs titres, chemins et descriptions. Les assistants IA doivent appeler cet outil en premier pour découvrir le contenu disponible. | Paramètre | Type | Description | | --------- | ------------------ | ---------------------------- | | `locale` | string (optionnel) | Filtrer les pages par locale | ### `get-page` Récupère le contenu markdown complet d'une page de documentation spécifique. | Paramètre | Type | Description | | --------- | --------------- | ------------------------------------------------------------- | | `path` | string (requis) | Le chemin de la page (ex: `/fr/getting-started/installation`) | ## Configuration Le serveur MCP Docus utilise le transport HTTP et peut être installé dans différents assistants IA. ### Claude Code Ajoutez le serveur en utilisant la commande CLI : ```bash claude mcp add --transport http my-docs https://docs.example.com/mcp ``` ### Cursor :install-button{ide="cursor" label="Installer dans Cursor" url="https://docs.example.com/mcp"} Ou créez/modifiez manuellement `.cursor/mcp.json` à la racine de votre projet : ```json [.cursor/mcp.json] { "mcpServers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Visual Studio Code Assurez-vous d'avoir les extensions GitHub Copilot et GitHub Copilot Chat installées. :install-button{ide="vscode" label="Installer dans VS Code" url="https://docs.example.com/mcp"} Ou créez/modifiez manuellement le fichier `.vscode/mcp.json` : ```json [.vscode/mcp.json] { "servers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Windsurf 1. Ouvrez Windsurf et naviguez vers **Settings** > **Windsurf Settings** > **Cascade** 2. Cliquez sur le bouton **Manage MCPs**, puis sélectionnez l'option **View raw config** 3. Ajoutez la configuration suivante : ```json [.codeium/windsurf/mcp_config.json] { "mcpServers": { "my-docs": { "type": "http", "url": "https://docs.example.com/mcp" } } } ``` ### Zed 1. Ouvrez Zed et allez dans **Settings** > **Open Settings** 2. Naviguez vers le fichier de paramètres JSON 3. Ajoutez la configuration de serveur de contexte suivante : ```json [.config/zed/settings.json] { "context_servers": { "my-docs": { "source": "custom", "command": "npx", "args": ["mcp-remote", "https://docs.example.com/mcp"], "env": {} } } } ``` ## Personnalisation Puisque Docus utilise le module `@nuxtjs/mcp-toolkit`, vous pouvez étendre le serveur MCP avec des outils, ressources, prompts et handlers personnalisés. ### Ajouter des Outils Personnalisés Créez de nouveaux outils dans le répertoire `server/mcp/tools/` : ```ts [server/mcp/tools/search.ts] import { z } from 'zod' export default defineMcpTool({ description: 'Rechercher dans la documentation par mot-clé', inputSchema: { query: z.string().describe('La requête de recherche'), }, handler: async ({ query }) => { const results = await searchDocs(query) return { content: [{ type: 'text', text: JSON.stringify(results) }], } }, }) ``` ### Ajouter des Ressources Exposez des fichiers ou sources de données comme ressources MCP dans le répertoire `server/mcp/resources/`. La façon la plus simple est d'utiliser la propriété `file` : ```ts [server/mcp/resources/changelog.ts] export default defineMcpResource({ file: 'CHANGELOG.md', metadata: { description: 'Journal des modifications du projet', }, }) ``` Cela gère automatiquement la génération d'URI, la détection du type MIME et la lecture du fichier. ### Ajouter des Prompts Créez des prompts réutilisables pour les assistants IA dans le répertoire `server/mcp/prompts/` : ```ts [server/mcp/prompts/migration-help.ts] import { z } from 'zod' export default defineMcpPrompt({ description: 'Obtenir de l\'aide pour migrer entre versions', inputSchema: { fromVersion: z.string().describe('Version actuelle'), toVersion: z.string().describe('Version cible'), }, handler: async ({ fromVersion, toVersion }) => { return { messages: [{ role: 'user', content: { type: 'text', text: `Aidez-moi à migrer de la version ${fromVersion} vers ${toVersion}. Quels sont les changements breaking et les étapes à suivre ?`, }, }], } }, }) ``` ### Ajouter des Handlers Personnalisés Les handlers permettent de créer des endpoints MCP séparés avec leurs propres outils, ressources et prompts. C'est utile pour exposer différentes capacités sur différentes routes. Par exemple, vous pourriez avoir : - `/mcp` - Serveur MCP principal de documentation - `/mcp/migration` - Serveur MCP dédié à l'assistance à la migration ```ts [server/mcp/migration.ts] import { z } from 'zod' const migrationTool = defineMcpTool({ name: 'migrate-v3-to-v4', description: 'Migrer du code de la version 3 vers la version 4', inputSchema: { code: z.string().describe('Le code à migrer'), }, handler: async ({ code }) => { // Logique de migration return { content: [{ type: 'text', text: migratedCode }], } }, }) export default defineMcpHandler({ route: '/mcp/migration', name: 'Assistant Migration', version: '1.0.0', tools: [migrationTool], }) ``` ### Surcharger les Outils Intégrés Vous pouvez remplacer les outils par défaut `list-pages` ou `get-page` en créant un outil avec le même nom dans votre projet : ```ts [server/mcp/tools/list-pages.ts] import { z } from 'zod' export default defineMcpTool({ description: 'Implémentation personnalisée de list pages', inputSchema: { locale: z.string().optional(), category: z.string().optional(), }, handler: async ({ locale, category }) => { const pages = await getCustomPageList(locale, category) return { content: [{ type: 'text', text: JSON.stringify(pages) }], } }, }) ``` ::tip{to="https://mcp-toolkit.nuxt.dev/"} Consultez la documentation MCP Toolkit pour plus d'informations sur les outils, ressources, prompts, handlers et la configuration avancée. :: # Agent Skills ## À propos des Agent Skills Docus découvre automatiquement les skills dans votre dossier `skills/` et les sert à `/.well-known/skills/`, en suivant la [RFC Agent Skills Discovery de Cloudflare](https://github.com/cloudflare/agent-skills-discovery-rfc){rel=""nofollow""}. Vos skills sont ainsi installables depuis n'importe quelle URL de documentation avec une seule commande. Les [Agent Skills](https://agentskills.io/){rel=""nofollow""} sont un format ouvert et léger pour donner aux agents IA des connaissances spécialisées et des workflows. Un skill est un fichier `SKILL.md` avec un frontmatter YAML qui décrit ce que les agents peuvent faire avec votre produit, accompagné de fichiers de référence optionnels. ::note{to="https://docus.dev/.well-known/skills/index.json"} Voir les skills publiés sur ce site de documentation. :: ## Démarrage rapide ::steps ### Créer un skill Ajoutez un dossier `skills/` à la racine de votre projet Docus avec un sous-dossier contenant un fichier `SKILL.md` : ```bash my-docs/ └── skills/ └── my-product/ └── SKILL.md ``` ### Écrire votre SKILL.md Suivez la [spécification agentskills.io](https://agentskills.io/specification){rel=""nofollow""}. Le seul champ frontmatter obligatoire est `description` — `name` prend par défaut le nom du dossier s'il est omis : ```md [skills/my-product/SKILL.md] --- name: my-product description: Build and deploy apps with My Product. Use when creating projects, configuring settings, or troubleshooting issues. --- # My Product ## Getting Started Create a new project: \`\`\`bash npx create-my-product my-app \`\`\` ``` ### Déployer Déployez votre documentation. Docus sert automatiquement vos skills à `/.well-known/skills/`. ### Partager avec vos utilisateurs Les utilisateurs peuvent installer vos skills avec une seule commande : ```bash npx skills add https://your-docs-domain.com ``` Le CLI détecte les agents installés (Claude Code, Cursor, Windsurf, et autres) et installe le skill pour chacun. :: ## Structure du dossier Un dossier de skill peut contenir des fichiers de support en plus du `SKILL.md` : ```bash skills/ └── my-product/ ├── SKILL.md # Requis : instructions + métadonnées ├── references/ # Optionnel : documentation additionnelle │ ├── api.md │ └── configuration.md ├── scripts/ # Optionnel : code exécutable │ └── setup.sh └── assets/ # Optionnel : templates, schémas └── config.template.yaml ``` Tous les fichiers sont automatiquement listés dans le catalogue `index.json` et servis à leurs chemins respectifs sous `/.well-known/skills/{skill-name}/`. ::tip Gardez votre `SKILL.md` principal sous 500 lignes. Déplacez le matériel de référence détaillé dans des fichiers séparés dans `references/` — les agents les chargent à la demande, donc des fichiers plus petits signifient moins d'utilisation de contexte. :: ## Configuration Par défaut, Docus cherche les skills dans le dossier `skills/` à la racine de votre projet. Vous pouvez modifier cela avec `docus.skills.dir` dans votre `nuxt.config.ts` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ docus: { skills: { dir: 'agent-skills' } } }) ``` ## Exigences pour les noms Les noms de skills doivent suivre la [spécification de nommage Agent Skills](https://agentskills.io/specification#name-field){rel=""nofollow""} : - 1-64 caractères - Lettres minuscules, chiffres et tirets uniquement (`a-z`, `0-9`, `-`) - Ne doit pas commencer ou finir par un tiret - Ne doit pas contenir de tirets consécutifs (`--`) - Le champ `name` dans le frontmatter doit correspondre au nom du dossier parent ::note Les skills qui échouent à la validation sont ignorés — vérifiez la sortie de votre build pour les avertissements. :: ## Skills multiples Vous pouvez publier plusieurs skills depuis un seul site de documentation : ```bash skills/ ├── my-product/ │ └── SKILL.md ├── create-project/ │ ├── SKILL.md │ └── references/ │ └── templates.md └── migration-guide/ └── SKILL.md ``` Tous les skills apparaissent dans le catalogue `index.json` et sont installables indépendamment. ## Prévisualisation et versioning Comme les skills vivent dans votre dépôt aux côtés de votre documentation, ils bénéficient de votre workflow Git existant : - **Previews de branches** : Testez les modifications de skills sur des déploiements de preview avant de merger. Sur Vercel, chaque pull request obtient une URL de preview où vous pouvez vérifier que vos skills fonctionnent correctement : ```bash npx skills add https://my-docs-git-feat-new-skill.vercel.app ``` - **Contrôle de version** : Suivez les changements de skills avec l'historique Git, reviewez les diffs dans les pull requests, et revenez en arrière si nécessaire. - **CI/CD** : Les skills sont build et déployés automatiquement avec votre documentation — pas d'étape de publication séparée. ::tip Utilisez les URLs de preview pour tester les skills avec vos outils d'IA avant de passer en production. Cela garantit que les instructions de vos skills fonctionnent correctement avec de vrais agents. :: ## Fonctionnement de la découverte Cette fonctionnalité implémente la [RFC Agent Skills Discovery de Cloudflare](https://github.com/cloudflare/agent-skills-discovery-rfc){rel=""nofollow""}, qui étend la [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615){rel=""nofollow""} (le même standard `.well-known` derrière la validation de certificats ACME et `security.txt`). Docus scanne votre dossier `skills/` au moment du build et génère deux types d'endpoints : ### Index de découverte ```text GET /.well-known/skills/index.json ``` Retourne un catalogue JSON listant tous les skills disponibles avec leurs descriptions et fichiers : ```json { "skills": [ { "name": "my-product", "description": "Build and deploy apps with My Product.", "files": ["SKILL.md", "references/api.md"] } ] } ``` ### Fichiers de skills ```text GET /.well-known/skills/{skill-name}/SKILL.md GET /.well-known/skills/{skill-name}/references/api.md ``` Les fichiers individuels sont servis avec les types de contenu appropriés (`text/markdown` pour les `.md`, `application/json` pour les `.json`, etc.). ## Comparaison avec llms.txt `llms.txt` et les Agent Skills aident les outils d'IA à travailler avec votre documentation, mais ils servent des objectifs différents : | | llms.txt | Agent Skills | | -------------- | ----------------------------------------------- | -------------------------------------------------------- | | **Objectif** | Répertoire de toutes les pages de documentation | Résumé des capacités avec des instructions actionnables | | **Contenu** | Titres, descriptions et liens des pages | Workflows étape par étape, exemples de code, contraintes | | **Chargé** | Au moment de la découverte | À la demande, quand le skill est activé | | **Format** | Texte brut avec des liens | Markdown avec frontmatter YAML | | **Idéal pour** | Aider les agents à trouver de l'information | Apprendre aux agents comment utiliser votre produit | ::tip Utilisez les deux ensemble : `llms.txt` indique aux agents où trouver l'information, tandis que les skills leur indiquent ce qu'ils peuvent accomplir et comment. :: # Intégration LLMs Docus intègre `nuxt-llms` par défaut pour préparer votre contenu aux Large Language Models (LLMs). Toutes vos pages de documentation sont injectées et les fichiers `/llms.txt` et `/llms-full.txt` sont automatiquement générés et pré-rendus. ::note{to="https://docus.dev/llms.txt"} Consultez le fichier `/llms.txt` généré pour la documentation Docus elle-même. :: ## Valeurs par défaut Voici les valeurs par défaut utilisées pour générer le fichier `/llms.txt` : - `domain` → calculé en fonction de votre plateforme de déploiement (ou via la variable d'environnement `NUXT_SITE_URL`) - `title` → extrait de votre `package.json` - `description` → extrait de votre `package.json` - `full.title` → extrait de votre `package.json` - `full.description` → extrait de votre `package.json` ## Personnalisation Vous pouvez surcharger vos données LLMs depuis le `nuxt.config.ts` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { domain: 'https://votre-site.com', title: 'Nom de votre site', description: 'Une brève description de votre site', full: { title: 'Nom de votre site', description: 'Une brève description de votre site', }, }, }) ``` ## Accès au Markdown brut Lorsque `nuxt-llms` est activé, Docus expose également un endpoint markdown brut permettant aux agents IA de récupérer les fichiers source prêts pour les LLMs sans passer par le pipeline de rendu complet. Cela réduit l'utilisation de tokens et améliore la vitesse de réponse pour les outils IA consommant votre documentation. ### Fonctionnement - **Endpoint** : `/raw/.md` — utilisez le même chemin que l'URL de la page, supprimez le `/index` final et conservez l'extension `.md` - **Content-Type** : `text/markdown; charset=utf-8` - **Enrichissement automatique** : si le document demandé n'a pas de titre ou de description de premier niveau, la route ajoute automatiquement le titre et la description au début du corps markdown - **Intégration LLMs.txt** : les liens des documents dans `llms.txt` sont automatiquement réécrits vers l'endpoint `/raw/...md`, afin que les agents récupèrent du markdown compact au lieu du HTML complet ::note{to="https://docus.dev/raw/fr/ai/llms.md"} Essayez d'accéder à la version Markdown brute de cette page. :: ### Configuration Vous pouvez personnaliser le comportement du markdown brut depuis votre `nuxt.config.ts` : ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { contentRawMarkdown: { // Empêcher l'exposition de certaines collections de pages excludeCollections: ['blog'], // Conserver les liens llms.txt pointant vers les pages rendues plutôt que le markdown brut rewriteLLMSTxt: false, }, }, }) ``` Pour désactiver complètement l'accès au markdown brut : ```ts [nuxt.config.ts] export default defineNuxtConfig({ llms: { contentRawMarkdown: false, }, }) ``` ## Redirection Markdown ::note Cette fonctionnalité n'est disponible que lorsque Docus est déployé sur Vercel. Nous pourrons la rendre agnostique une fois que Nitro v3 prendra en charge les réécritures globales pour plusieurs fournisseurs. :: Lorsqu'il est déployé sur Vercel, Docus configure automatiquement un routage intelligent pour servir du contenu markdown aux agents IA et aux outils en ligne de commande. ### Pourquoi ? Les agents comme Claude Code utilisent les en-têtes `Accept: text/markdown` par défaut, retourner du Markdown brut permet d'économiser beaucoup de transfert de données et de tokens dans le processus. ### Comment ? Docus détecte les requêtes provenant d'agents IA et d'outils en ligne de commande à l'aide des en-têtes HTTP : - **En-tête Accept** : Les requêtes avec `Accept: text/markdown` sont automatiquement redirigées - **Détection du user-agent** : Les requêtes `curl` en tant qu'agents sont automatiquement redirigées ### Règles de redirection - **Chemin racine** : `/` → `/llms.txt` - **Pages de documentation** : `/{chemin}` → `/raw/{chemin}.md` ### Exemple d'utilisation ```bash # Obtenir llms.txt depuis la page d'accueil curl -H "Accept: text/markdown" https://docus.dev/ # Obtenir llms.txt depuis la page d'accueil localisée curl -H "Accept: text/markdown" https://docus.dev/fr # Obtenir le markdown brut d'une page de documentation curl -H "Accept: text/markdown" https://docus.dev/fr/ai/llms ``` Toutes ces commandes retourneront du contenu markdown au lieu de HTML. ::tip{to="https://github.com/nuxt-content/nuxt-llms"} Consultez la documentation nuxt-llms pour plus d'informations sur le module. ::