Nimiq Vitepress Theme ​

Use this theme to style your VitePress documentation pages with the Nimiq brand.

Vitepress is a static page generator powered by Vite. It is a great solution for creating documentation pages with minimal configuration. We have created a theme that you can use to style your documentation pages with the Nimiq brand. This entire documentation page uses the Nimiq Vitepress theme 💅.

Installation ​

pnpm add nimiq-vitepress-theme

npm install nimiq-vitepress-theme

yarn add nimiq-vitepress-theme

bun add nimiq-vitepress-theme

Usage ​

Start a vitepress project if you haven't already:

Update your config ​

Instead of using defineConfig, you will need to use defineConfigWithTheme:

import type { NimiqVitepressThemeConfig } from 'nimiq-vitepress-theme'
import { defineConfigWithTheme } from 'nimiq-vitepress-theme'
import { themeConfig } from './themeConfig'

export default defineConfigWithTheme<NimiqVitepressThemeConfig>({ 
  themeConfig // The config structure is different from Vitepress

  // The rest of your config like title, description, etc.
})

export const themeConfig = {
  modules: [
    {
      subpath: '/vitepress-theme',

      // This will be set as a class on a div element. This works great for UnoCSS Icons preset. Let me know if you need help with other icon libraries.
      icon: 'i-local:nimiq-css',

      // This will be the default page link when the user clicks on the selector
      defaultPageLink: '/your-submodule/getting-started',

      // Text displayed in the selector
      text: 'Vitepress Theme',
      description: 'Your Viteprss with Nimiq',

      // Each module have their own sidebar
      sidebar: [
        {
          label: 'Guide',
          items: [
            { text: 'Getting started', link: '/your-submodule/getting-started', icon: 'i-tabler:arrow-guide ', },
            {
              text: 'My awesome accordion',
              icon: 'i-tabler:binary-tree ',
              items: [
                { text: 'Look I am Item 1', link: '/your-submodule/getting-started', },
                { text: 'Now I am Item 2', link: '/your-submodule/layers/preflights', },
              ]
            },
          ]
        }
      ]
    },
    // You can create as many submodules as you want.
  ],
  links: [
    // Any icon with link you want
    { icon: 'i-nimiq:logos-github-mono', link: 'https://github.com/onmax/nimiq-ui' }
  ],

  // Options for the bottom of the page
  showLastUpdated: true, // Default is true
  showEditContent: true, // Default is true
}

You can use the config used for this documentation for reference.

Import the layout and CSS ​

Remove the default Vitepress Theme and instead use defineNimiqThemeConfig from nimiq-vitepress-theme:

import { defineNimiqThemeConfig } from 'nimiq-vitepress-theme'

export default defineNimiqThemeConfig({
  enhanceApp({ app }) {
    // The rest of your config
  },
})

This will install the layout and will register the Nimiq Components globally.

Configure the Vite plugin ​

The theme provides a Vite plugin that adds Git changelog functionality and source code features:

import { NimiqVitepressVitePlugin } from 'nimiq-vitepress-theme/vite'
import { defineConfig } from 'vite'

export default defineConfig(() => {
  return {
    plugins: [
      NimiqVitepressVitePlugin({
        // GitHub repository URL (required for source code features)
        repoURL: 'https://github.com/your-org/your-repo',

        // Content directory path relative to repository root
        // Use this if your docs are not in the repository root
        contentPath: 'docs', // Optional, defaults to ''

        // Git changelog configuration (optional)
        // If not provided, will use repoURL as default
        // Set to false to disable changelog
        gitChangelog: {
          repoURL: 'https://github.com/your-org/your-repo' // Can be different from main repoURL
        }
      })
    ]
  }
})

Plugin Options ​

The plugin automatically:

• Configures Git changelog functionality using the provided repository URL
• Enables source code viewing and copying features
• Constructs proper URLs for "View Source" and "Edit Page" links

Register the theme as internal dependency ​

This step is optional and only needed if you want to use the Vue components from nimiq-vitepress-theme in your project.

In Vitepress, dependencies are "externalized" from Vite's SSR transform module system. This means that you need to tell Vite that you are using a component from an external module:

import { defineConfig } from 'vite'

export default defineConfig(() => {
  return {
    ssr: { 
      noExternal: [ 
        'nimiq-vitepress-theme', 
      ], 
    }, 
  }
})

For more information about why configure this, please refer to the Server-Side Rendering | Vite documentation.

Customization ​

This theme has not been developed with customatization in mind. In fact, it has the least possible amount of options on purpose as we want to keep it simple.

We can always discuss about adding more options if you need them. Open an issue and let's talk about it.

Credits ​

• The layout has been heavily inspired by the Fumadocs theme.
• Inspired by the work of the Nimiq Hub documentation.
• Using Tabler Icons and Nimiq Icons.