Nimiq VitePress Theme

A modern, beautiful VitePress theme with Nimiq branding and design patterns.

Features

• 🎨 Modern, clean design with Nimiq branding

• 🌙 Dark mode support

• 📱 Fully responsive layout

• 🔍 Advanced search functionality

• 🧭 Smart navigation with breadcrumbs

• 📝 Rich typography and code highlighting

• 🎯 Custom components (NqCard, NqGrid, NqHeadline, etc.)

• 🚨 Beautiful custom 404 error page

Components

Built-in Components

• NqCard - Flexible card component with optional icons and links
• NqGrid - Responsive grid layout
• NqHeadline - Structured headline component
• NqLargeCard - Large featured card component
• NqModulesGrid - Grid for displaying modules

Error Page

The theme includes a custom 404 error page with:

• Friendly error message with random emojis
• Quick navigation options (Go Back, Go Home)
• Integrated search functionality
• Quick links to common pages
• Display of available modules
• Responsive design for mobile and desktop

Installation

npm install nimiq-vitepress-theme

Usage

// .vitepress/config.ts
import { defineNimiqVitepressConfig } from 'nimiq-vitepress-theme'

export default defineNimiqVitepressConfig({
  title: 'Your Documentation',
  description: 'Your description',
  themeConfig: {
    modules: [
      {
        text: 'Getting Started',
        defaultPageLink: '/getting-started',
        description: 'Learn the basics'
      }
    ]
  }
})

Theme Configuration

The theme supports various configuration options:

interface NimiqVitepressThemeConfig {
  modules: NimiqVitepressThemeNav[]
  links?: {
    icon: string
    link: string
    label: string
  }[]
  showLastUpdated?: boolean
  showEditContent?: boolean
  search?: { provider: 'local' }
  outlineActions?: OutlineAction[]
  pageFooterLeftText?: false | string
}

Configuration Options

• modules (required): Array of navigation modules for your documentation
• links: Social and external links displayed in the navigation
• showLastUpdated: Show last updated timestamp for pages (default: true)
• showEditContent: Show "Edit this page" link (default: true)
• search: Enable local search (set to { provider: 'local' })
• outlineActions: Custom actions displayed in the page outline
• pageFooterLeftText: Customize page footer text. Set to false to hide, or provide a string (supports markdown). Can be overridden per-page via frontmatter

Layout Slots

The theme provides layout slots for extending functionality:

layout-bottom

A slot rendered at the bottom of the layout, useful for mounting global components like modals or notification systems.

Example usage:

import type { Theme } from 'vitepress'
// .vitepress/theme/index.ts
import { defineNimiqThemeConfig } from 'nimiq-vitepress-theme/theme'
import { h } from 'vue'
import MyGlobalModal from './components/MyGlobalModal.vue'

const baseTheme = defineNimiqThemeConfig({
  enhanceApp({ app }) {
    // your app enhancements
  },
})

export default {
  extends: baseTheme,
  Layout: () => {
    return h(baseTheme.Layout!, null, {
      'layout-bottom': () => h(MyGlobalModal),
    })
  },
} satisfies Theme

This slot is ideal for:

• Global modals and dialogs
• Feedback widgets
• Cookie consent banners
• Analytics components
• Any component that needs to be available across all pages

Testing the 404 Page

To test the custom 404 error page:

1. Start your development server
2. Navigate to any non-existent page (e.g., /non-existent-page)
3. The custom error page will display with:
   • Random emoji
   • Friendly error message
   • Navigation options
   • Search functionality
   • Quick links and module exploration

Development

# Install dependencies
pnpm install

# Build the theme
pnpm build

# Development
pnpm dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Git Data Performance

The git data feature fetches information about files from git history, which can be slow for large repositories. To improve performance, the script implements:

1. Caching: File information is cached in .vitepress/cache/git-data-cache.json
2. Change detection: Only files that have been modified since the last run are processed

Debugging

To enable debug logs for the git data script, run VitePress with:

DEBUG=true npm run dev

Configuration

You can adjust the concurrency level by modifying the CONCURRENCY constant in git.data.ts.