nuxt-awesome-docs

Beautiful, filesystem-based documentation system for Nuxt applications.

• Release Notes

Features

• Filesystem-based: Organize your docs as markdown files in content/docs/
• Hierarchical Navigation: Support for nested categories and subcategories
• Optional Frontmatter: Works with plain markdown - auto-extracts titles from headings
• Automatic Ordering: Use numeric prefixes (01.getting-started/) for ordering
• Beautiful UI: Built on Nuxt UI v3 for a modern, polished look
• Search: Full-text search across all documentation
• Dark Mode: Automatic dark mode support
• Responsive: Mobile-friendly design with collapsible sidebar
• Table of Contents: Auto-generated TOC from headings
• Previous/Next Navigation: Navigate between docs seamlessly
• Reading Time: Automatic reading time estimates
• Markdown Extensions: Support for callouts (info, tip, warning, danger)

Quick Setup

Install the module:

npx nuxi module add nuxt-awesome-docs

Add to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@nuxt/ui', 'nuxt-awesome-docs'],

  awesomeDocs: {
    basePath: '/docs',
    title: 'My Documentation',
    description: 'Documentation for my project',
    version: '1.0.0',
    github: 'https://github.com/daviunx/nuxt-awesome-docs'
  }
})

Create your docs in content/docs/:

content/
  docs/
    _config.yml
    01.getting-started/
      01.introduction.md
      02.installation.md
    02.guides/
      01.configuration.md

Configuration

Module Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | basePath | string | '/docs' | Base URL path for documentation | | contentDir | string | 'content/docs' | Directory containing markdown files | | title | string | 'Documentation' | Site title | | description | string | 'Documentation for your project' | Site description | | version | string | '1.0.0' | Version string | | github | string | '' | GitHub repository URL | | tableOfContents | boolean | true | Show table of contents | | previousNext | boolean | true | Show prev/next navigation | | feedback | boolean | true | Show feedback section | | readingTime | boolean | true | Show reading time | | search | boolean | true | Enable search |

Content Structure

Use numeric prefixes to control ordering:

• 01.getting-started/ appears before 02.guides/
• 01.introduction.md appears before 02.installation.md

The numeric prefix is stripped from URLs.

Frontmatter (Optional)

Frontmatter is optional. If not provided, the module will:

• Extract the title from the first # Heading in the document
• Extract the description from the first paragraph after the heading
• Use default values for other fields

---
title: Page Title
description: Brief description
icon: i-heroicons-document-text
tags:
  - tag1
  - tag2
lastUpdated: 2025-01-15
---

Index Files

Both index.md and README.md are treated as index pages for their directory:

guides/
  README.md       # Index page for /docs/guides
  configuration.md

Callouts

Use callout blocks in your markdown:

:::info
Informational note
:::

:::tip
Helpful tip
:::

:::warning
Warning message
:::

:::danger
Critical warning
:::

Components

The module provides auto-imported components:

• DocsHeader - Page header with breadcrumbs
• DocsSidebar - Navigation sidebar
• DocsMarkdown - Markdown renderer
• DocsCallout - Alert/callout component
• DocsTableOfContents - Table of contents
• DocsNavCategory - Navigation category

Composables

useDocs()

const {
  docs,           // All documentation items
  categories,     // Category tree
  currentDoc,     // Currently viewed document
  isLoading,      // Loading state
  error,          // Error state
  loadDocs,       // Load all docs
  loadDoc,        // Load single doc
  searchDocs,     // Search docs
} = useDocs()

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

License

MIT License