Skip to main content

Docusaurus Configuration Guidelines

This document provides conventions and best practices for configuring Docusaurus in the ProvLabs documentation website.

Configuration Structure​

Main Configuration File​

  • docusaurus.config.ts contains all site configuration
  • Use TypeScript for type safety and better IDE support
  • Import types from Docusaurus packages for proper typing
  • Separate configuration sections logically

Type Imports​

import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import type * as Redocusaurus from 'redocusaurus';

Site Metadata​

Basic Configuration​

const config: Config = {
  title: 'ProvLabs Documentation',
  tagline: 'Documentation for ProvLabs APIs',
  favicon: 'favicon.svg',
  url: 'https://docs.nuvalabs.com',
  baseUrl: '/',
  organizationName: 'provlabs',
  projectName: 'docs-website',
};

Error Handling​

  • Set onBrokenLinks: 'throw' to catch broken internal links
  • Use onBrokenMarkdownLinks: 'warn' for markdown link issues
  • Configure appropriate error levels for development vs production

Preset Configuration​

Classic Preset​

[
  'classic',
  {
    docs: {
      sidebarPath: './sidebar.ts',
      routeBasePath: '/', // Serve docs at root
    },
    blog: false, // Disable blog functionality
    theme: {
      customCss: './src/css/custom.css',
    },
  } satisfies Preset.Options,
];

Redocusaurus Integration​

[
  'redocusaurus',
  {
    id: 'pcapi',
    openapi: {
      path: './openapi',
      routeBasePath: '/api',
    },
    specs: [
      {
        spec: 'openapi/openapi.yaml',
        id: 'provlabs-apis',
        route: '/api',
      },
      {
        spec: 'openapi/noderpc.openapi.yaml',
        id: 'node-rpc',
        route: '/node',
      },
    ],
  },
] satisfies Redocusaurus.PresetEntry;

Plugin Configuration​

TailwindCSS Integration​

plugins: [
  async function myPlugin(context, options) {
    return {
      name: 'docusaurus-tailwindcss',
      configurePostCss(postcssOptions) {
        postcssOptions.plugins.push(require('postcss-import'));
        postcssOptions.plugins.push(require('@tailwindcss/postcss'));
        return postcssOptions;
      },
    };
  },
];

Additional Plugins​

  • Use official Docusaurus plugins when available
  • Configure plugins with proper TypeScript typing
  • Document custom plugin functionality
  • Test plugin compatibility with Docusaurus updates

Theme Configuration​

navbar: {
  title: '',
  hideOnScroll: false,
  logo: {
    alt: 'ProvLabs Logo',
    src: 'img/provlabs-logo.svg',
    href: '/',
    target: '_self',
  },
  items: [
    {
      label: 'API',
      to: 'api',
    },
    {
      label: 'Node RPC',
      to: 'node',
    },
    // External link with custom HTML
    {
      href: 'https://github.com/provenance-io/provenance',
      html: `<svg>...</svg>`,
      position: 'right',
    },
  ],
}
footer: {
  links: [
    {
      items: [
        {
          html: `<a href="https://provlabs.com"><img src="/img/provlabs-logo.svg" alt="ProvLabs Logo"></a>`,
        },
      ],
    },
    {
      title: 'Documentation',
      items: [
        {
          label: 'ProvConnect',
          href: 'https://connect.provlabs.com',
        },
        {
          label: 'REST API',
          to: 'api',
        },
      ],
    },
  ],
  copyright: `Copyright ${new Date().getFullYear()} Provenance Blockchain Labs, Inc.`,
}

Styling Integration​

TailwindCSS Configuration​

  • Configure TailwindCSS through PostCSS plugin
  • Use @tailwindcss/postcss for optimal integration
  • Import PostCSS plugins in correct order
  • Test build process with styling changes

Custom CSS​

  • Place custom styles in src/css/custom.css
  • Use CSS custom properties for theme variables
  • Maintain responsive design principles
  • Follow Docusaurus styling conventions

Content Configuration​

Docs Configuration​

docs: {
  sidebarPath: './sidebar.ts',
  routeBasePath: '/',
  sidebar: {
    autoCollapseCategories: true,
  },
}
  • Define sidebar structure in separate sidebar.ts file
  • Use TypeScript for sidebar configuration
  • Organize content hierarchically
  • Implement collapsible categories for better UX

Internationalization​

i18n Setup​

i18n: {
  defaultLocale: 'en',
  locales: ['en'],
}

Future Localization​

  • Structure configuration for easy locale addition
  • Use locale-aware routing patterns
  • Consider content organization for translations
  • Plan for locale-specific customizations

Development Configuration​

Environment-Specific Settings​

  • Use environment variables for deployment-specific values
  • Configure different settings for development vs production
  • Test configuration changes locally before deployment
  • Document environment requirements

Performance Optimization​

  • Configure bundle analysis for large sites
  • Optimize asset loading and caching
  • Use code splitting for large documentation sets
  • Monitor build performance metrics

Markdown Configuration​

Mermaid Integration​

markdown: {
  mermaid: true,
}

Additional Markdown Features​

  • Configure syntax highlighting languages
  • Enable/disable specific markdown features
  • Customize rendering behavior
  • Test markdown processing with complex content

Theme Extensions​

Additional Themes​

themes: ['@you54f/theme-github-codeblock', '@docusaurus/theme-mermaid'];

Custom Theme Components​

  • Swizzle components when necessary
  • Maintain compatibility with theme updates
  • Document customizations clearly
  • Test theme changes across different content types

SEO and Meta Configuration​

Meta Tags​

  • Configure appropriate meta descriptions
  • Set up social media sharing tags
  • Include favicon and app icons
  • Test SEO configuration with various tools

Sitemap Configuration​

  • Enable automatic sitemap generation
  • Configure URL patterns appropriately
  • Test sitemap accessibility
  • Update robots.txt as needed

Build and Deployment​

Build Configuration​

  • Optimize for production builds
  • Configure asset optimization
  • Set up proper caching headers
  • Test build output thoroughly

Static Asset Management​

  • Organize assets in static/ directory
  • Optimize images for web delivery
  • Use appropriate file formats
  • Implement asset versioning strategy