--- sidebar_label: Best Practices sidebar_position: 1 --- # Docusaurus Best Practices & Guidelines Recommended practices for writing high-quality Docusaurus documentation using MDX format. ## File Format Always use `.mdx` extension for Docusaurus documentation files, even if not currently using JSX components. **Benefits:** - Enables use of Docusaurus MDX components (Tabs, Admonitions, etc.) - Provides consistency across the documentation - Makes files less portable but more powerful within Docusaurus ecosystem ``` ✅ quick-start.mdx ❌ quick-start.md ``` ## Frontmatter Frontmatter fields are optional but useful for customization. | Field | Purpose | Example | |-------|---------|---------| | `sidebar_label` | Shorter sidebar title or add icons | `sidebar_label: 🚀 Quick Start` | | `sidebar_position` | Override alphabetical ordering | `sidebar_position: 1` | | `title` | Override H1 as page title | `title: Getting Started Guide` | Use `sidebar_label` when your H1 heading is too long for the sidebar, or to add emoji/icons for visual distinction. **Alternative to `sidebar_position`:** Prefix filenames with numbers like `01-introduction.mdx`, `02-installation.mdx`, `03-configuration.mdx`. ## Component Imports Always place imports immediately after frontmatter: ````mdx --- sidebar_label: Examples --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Examples and Usage ```` ## Heading Structure Never skip heading levels – maintain logical document structure for accessibility. ```mdx ✅ Good # Main Title (H1) ## Section (H2) ### Subsection (H3) #### Detail (H4) ❌ Bad # Main Title (H1) ### Subsection (H3) ← Skipped H2 ``` Don't create sections with only one sub-heading – it creates awkward TOC entries. ```mdx ❌ Bad ## Configuration ### Database Setup ← Only one H3 under H2 ✅ Better - Remove sub-header ## Database Setup ✅ Better - Add more sub-headers ## Configuration ### Database Setup ### Cache Setup ### Logging Setup ``` Adjust TOC depth using frontmatter if using many H4 headings: ```mdx --- tableOfContents: maxHeadingLevel: 3 --- # My Page ``` ## Code Blocks Always specify the language for proper syntax highlighting: ````mdx ✅ Good ```bash npm install ``` ❌ Bad ``` npm install ``` ```` Use `title` attribute for known filenames or configuration files: ````mdx ```json title="package.json" { "name": "my-app", "version": "1.0.0" } ``` ```` Highlight specific lines when showing modifications: ````mdx ```typescript title="app.ts" {3-5} function greet(name: string) { // highlight-next-line console.log(`Hello, ${name}!`); return `Welcome, ${name}`; } ``` ```` Use backslash `\` for lengthy commands to improve readability: ```bash docker run -d \ --name my-container \ --publish 8080:80 \ --volume $(pwd):/app \ nginx:latest ``` For multiple commands, use one of these approaches: ````mdx Option 1: Separate blocks ```bash npm install ``` ```bash npm run dev ``` Option 2: Chain with && ```bash npm install && npm run dev ``` Option 3: Use comments ```bash # Install dependencies npm install # Start development server npm run dev ``` ```` ## Inline Code vs Code Blocks Use inline code for short, single-line references: - File paths: `src/components/Header.tsx` - Variables: `API_KEY` - Functions: `getUserById()` - Small values: `true`, `null`, `"production"` - Commands when mentioned in text: "Run `npm install` to get started" Use code blocks for: - Commands in step-by-step instructions or when you expect readers to copy - Complete commands with options - Configuration files - Function/class implementations - Multi-step procedures ## MDX Components Don't use markdown headers inside Tabs components – they appear in the TOC. Use bold text or `

` tags instead. ````mdx ❌ Bad ### Using npm ← Appears in TOC ```bash npm install ``` ✅ Good - Use bold text **Using npm** ```bash npm install ``` ✅ Good - Use

tag

Using npm

```bash npm install ``` ```` Maintain proper indentation for nested HTML/JSX: ````mdx
Click to expand

Nested content should be indented

  • Item 1
  • Item 2
```` ## Admonitions Admonitions steal focus (intentionally) – use only for important information. Limit to 1-2 per page section. ````mdx :::note General information or context ::: :::tip Helpful shortcuts or best practices ::: :::warning Potential pitfalls or deprecated features ::: :::danger Destructive actions or critical warnings ::: :::info Additional context or related information ::: ```` **When to use:** - `:::note` – Additional context that's helpful but not critical - `:::tip` – Efficiency shortcuts or recommended approaches - `:::warning` – Potential issues, deprecated features, or gotchas - `:::danger` – Data loss risks, breaking changes, security concerns - `:::info` – Related resources or background information ## Tables Use markdown tables for structured data like command options, configuration parameters, comparison matrices, or property documentation. ````mdx | Option | Type | Default | Description | |--------|------|---------|-------------| | `port` | number | `3000` | Server port | | `host` | string | `localhost` | Server host | ```` Keep column count reasonable and use concise headers for readability. ## Collapsible Sections Hide advanced or supplementary information behind collapsible sections using `
`: ````mdx
Advanced configuration options Content here is hidden by default and revealed on click. ```json { "advanced": true } ```
```` **When to use:** - Advanced configuration options - Detailed explanations for specific edge cases - Lengthy reference information - Optional troubleshooting steps ## Directory Structure Consider adding an `index.mdx` landing page in directories when the category needs an overview, navigation to sub-pages, or general context. ``` guides/ ├── index.mdx ← Landing page for guides section ├── installation.mdx ├── configuration.mdx └── deployment.mdx ``` ## Links Markdown links are useful but require careful consideration. **Pros:** - Great for connecting related documentation - Improve content discoverability - Enable quick navigation **Cons:** - Break when files are moved or renamed - Create maintenance burden in large projects - Can cause build errors if targets are deleted **Guideline:** - Use links in `index.mdx` landing pages for navigation - Avoid excessive cross-linking in regular content pages - Prefer sidebar navigation over inline links when possible - Keep external links (to official docs, resources) – they're valuable ````mdx ✅ Good - Landing page with curated links # Getting Started - [Installation Guide](./installation.mdx) - [Configuration](./configuration.mdx) ✅ Good - External resource See the [official Docker documentation](https://docs.docker.com) ⚠️ Use sparingly - Cross-references between regular pages For database setup, see [Configuration Guide](../config/database.mdx) ```` ## Images & Assets Store page-specific images in `.assets/` directory alongside the MDX file: ``` guides/ ├── installation.mdx └── .assets/ ├── install-step1.png └── install-step2.png ``` Store shared resources in `/static/img/` for logos, icons, and reused graphics: ``` static/ └── img/ ├── logo.svg ├── docker-icon.png └── common/ └── warning-icon.svg ``` Always include descriptive alt text for images: ````mdx ✅ Good ![Docker container architecture diagram showing layers](./assets/docker-architecture.png) ❌ Bad ![](./assets/image.png) ```` **Performance tips:** - Prefer SVG for logos and icons (smaller, scalable) - Optimize PNG/JPG images before adding to repository - Use appropriate image dimensions (don't scale down huge images with HTML)