Skip to content

Docusaurus configuration files

Jump to bottom
Nirav Nikhil edited this page Dec 31, 2024 · 2 revisions

SignalWire Documentation Configuration Guide

This document provides a technical overview of the main configuration files used in the SignalWire documentation.

Core Configuration Files

Site Identity and Navigation

branding.js

Controls the core identity and presentation of the documentation site. This includes site title, URLs, logos, and primary navigation elements.

Location: /config/branding.js

Used by: docusaurus.config.js

Technical Reference: Docusaurus Config


Example branding.js

The below example demonstrates the basic configuration for the branding.js file. The websites title, url, and logo are defined here.


module.exports = {
  title: "Your Site Title",
  url: "https://your-domain.com",
  baseUrl: "/",
  favicon: "img/favicon.ico",
  navbar: {
    logo: {
      alt: "Site Logo",
      src: "img/logo.svg",
      href: "/",
    }
  }
};

navbar.js

Defines the structure and content of the site's navigation bar, including dropdowns, links, and their positioning. Manages all top-level navigation elements and their organization.

Location: /config/navbar.js

Used by: branding.js

Technical Reference: Docusaurus Navbar


Example navbar.js

The below example demonstrates the basic configuration for the navbar.js file. Top level navigation items are objects that are defined at the top level of the array. They can also include dropdowns, which are defined as objects within the items property.


module.exports = [
  { 
    to: "/section", 
    label: "Section Name", 
    position: "left" 
  },
  
  {
    type: "dropdown",
    label: "Category",
    position: "left",
    items: [
      {
        label: "Item 1",
        to: "/category/item-1",
      },
      {
        label: "Item 2",
        to: "/category/item-2",
      },
    ],
  },
];

Theme and Styling

themeConfig/config.js

Controls the visual appearance and behavior of the platform, including color schemes, code highlighting, and interactive elements. Centralizes all theme-related configurations.

Location: /config/themeConfig/config.js

Used by: docusaurus.config.js

Technical Reference: Docusaurus Theme Config


Example config.js

The below example demonstrates the basic configuration for the config.js file.

The footer object is used to define the footer content and can be found in the footer.js file.


module.exports = {
  footer: require("./footer"),
  docs: {
    sidebar: {
      autoCollapseCategories: true,
      hideable: true,
    }
  },
  prism: {
    theme: lightCodeTheme,
    darkTheme: darkCodeTheme,
    additionalLanguages: [/* language list */]
  },
  colorMode: {
    defaultMode: "light",
    disableSwitch: true,
  }
};

stylesheets.js

Manages external stylesheet resources and font imports for the documentation platform. Currently handles the loading of custom fonts used throughout the site.

Location: /config/stylesheets.js

Used by: docusaurus.config.js

Technical Reference: Docusaurus Stylesheets


Example stylesheets.js

The below example demonstrates the basic configuration for the stylesheets.js file. In the below example, we are importing a font from Google Fonts.


module.exports = [
  "https://fonts.googleapis.com/css2?family=YourFont:wght@400;700&display=swap",
];

Documentation Structure

sidebarsConfig/index.ts

Defines the organization and hierarchy of documentation content through sidebar configurations, making content discoverable and accessible. Serves as the main entry point for all navigation structures.

Location: /config/sidebarsConfig/index.ts

Used by: presets.js

Technical Reference: Docusaurus Sidebars


Example index.ts

The below example demonstrates the basic configuration for the index.ts file. The sidebar objects are defined in seperate files and imported into the main SidebarsConfig object within the index.ts file.


import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
import sidebarOne from './sidebar-one';
import sidebarTwo from './sidebar-two';

const sidebars: SidebarsConfig = {
  ...sidebarOne,
  ...sidebarTwo,
};

export default sidebars;

Additional Information

Learn more about our sidebar configuration.

Plugin and Preset Management

pluginsConfig/index.ts

Manages the integration of Docusaurus plugins that extend the platform's functionality, from OpenAPI documentation to SASS processing. Acts as the central registry for all plugin configurations.

Location: /config/pluginsConfig/index.ts

Used by: docusaurus.config.js

Technical Reference: Docusaurus Plugins


Example index.ts

The below example demonstrates the basic configuration for the index.ts file. The plugins are defined in seperate files and imported into the main PluginConfig object within the index.ts file.


import { PluginConfig } from '@docusaurus/types';
import customPluginOne from './custom-plugin-one';
import customPluginTwo from './custom-plugin-two';
import customPluginThree from './custom-plugin-three';

const plugins: PluginConfig[] = [
  customPluginOne,
  customPluginTwo,
  customPluginThree,
];

export default plugins;

Additional Information

Learn more about our plugin configuration.

presets.js

Handles bundled plugins and themes through Docusaurus presets, providing the foundation for documentation features and appearance. Manages the classic preset configuration and its associated plugins.

Location: /config/presets.js

Used by: docusaurus.config.js

Technical Reference: Docusaurus Presets


Example presets.js

The below example demonstrates the basic configuration for the presets.js file. The remarkPlugins are required imports that are defined in the /plugins directory. The customCss is a required import that is defined in the /src/css/index.scss file. The analytics object is used to define the Google Analytics tracking ID.


module.exports = [
  ["classic", {
    docs: {
      remarkPlugins: [
        [require("../plugins/remark-plugin-one"), { sync: true }],
        [require("../plugins/remark-plugin-two"), { sync: false }],
      ],
    },
    theme: {
      customCss: require.resolve("../src/css/index.scss"),
    },
    analytics: {
      trackingID: "TRACKING-ID",
    }
  }]
];

External Integrations

typesense.js

Manages the Typesense search functionality, enabling efficient content discovery across the documentation. Configures search server settings and parameters.

Location: /config/typesense.js

Used by: docusaurus.config.js

Technical Reference: Docusaurus Typesense


Example typesense.js

The below example demonstrates the basic configuration for the typesense.js file. The searchCollectionName is the name of the Typesense collection that will be used for the search functionality. The serverConfig object is used to define the Typesense server configuration. The apiKey is the API key for the Typesense server.


module.exports = {
  searchCollectionName: "your-collection",
  serverConfig: {
    nodes: [{
      host: "search.your-domain.com",
      protocol: "https",
      port: 443,
    }],
    apiKey: "YOUR-API-KEY"
  },
  searchParameters: {},
  contextualSearch: true,
};

includedScripts.js

Handles the integration of external scripts and services, including analytics, customer support, and marketing tools. Manages script loading and security settings.

Location: /config/includedScripts.js

Used by: docusaurus.config.js

Technical Reference: Docusaurus Included Scripts


Example includedScripts.js

The below example demonstrates the basic configuration for the includedScripts.js file. The scripts are defined in the static/scripts directory.


module.exports = [
  {
    src: "/scripts/analytics.js",
    async: true,
    nonce: "YOUR-CSP-NONCE"
  },
  {
    src: "/scripts/chat.js",
    async: true,
    nonce: "YOUR-CSP-NONCE"
  },
];

Environment Variables

The root of the repository contains a .env.example file. It should be renamed to .env and edited in case you need to configure TypeSense or Google Analytics.

  1. Set GTAG to your Google Analytics tag if you'd like to enable Google Analytics for the documentation.

  2. Fill in the TypeSense variables if you have a self-hosted TypeSense server to enable search.

Configuration Flow

The documentation platform uses a hierarchical configuration system where:

  1. docusaurus.config.js (Root)

    • Imports and uses all main configuration files
    • Sets up the core documentation structure

  2. Main Configuration Files

    • Each handles a specific aspect of the documentation
    • Export configurations used by the root config

  3. Directory-based Configurations

    • pluginsConfig/ - Plugin-specific configurations
    • sidebarsConfig/ - Navigation structure configurations
    • themeConfig/ - Theme and styling configurations

Best Practices

  1. File Organization

    • Keep main configuration files in the root /config directory
    • Use subdirectories for related configurations
    • Maintain clear file naming conventions

  2. Configuration Management

    • Use TypeScript for type safety where possible
    • Keep configurations modular and focused
    • Document configuration options inline

  3. Security

    • Use environment variables for sensitive data
    • Implement proper CSP nonces

Troubleshooting

When debugging configuration issues:

  1. Check the main configuration file first
  2. Verify imports and exports
  3. Validate configuration syntax
  4. Check Docusaurus build logs
Clone this wiki locally