-
Notifications
You must be signed in to change notification settings - Fork 2
Sidebars Configuration
This document explains how sidebars are configured and managed in the SignalWire documentation platform. Consult the Docusaurus Sidebar reference for more information.
The sidebar configuration is managed through multiple files:
-
config/sidebarsConfig/index.ts
- Main sidebar registration - Individual sidebar configuration files in
config/sidebarsConfig/
- Auto-generated sidebar files from OpenAPI documentation
- Integration through
config/presets.js
Sidebars are integrated into Docusaurus through the config/presets.js
configuration:
// config/presets.js
module.exports = [
[
"classic",
({
docs: {
sidebarPath: require.resolve("./sidebarsConfig"),
// ... other configurations
},
}),
],
];
Our documentation uses several types of sidebars:
- Homepage Sidebar - Sidebar for homepage. Shows product overviews and more.
- API Reference Sidebars - Auto-generated from OpenAPI specs and manually configured sections
- SDK Reference Sidebars - For SDK documentation
- Technical Reference Sidebars - For technical specifications
Sidebars are registered through a two-step process:
- Create a sidebar configuration file in
/config/sidebarsConfig/
- Import and add the sidebar to
index.ts
// config/sidebarsConfig/index.ts
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
import productSpecificSidebars from './product-specific-sidebar';
import apiSidebar from './rest-api-sidebar';
// ... other imports
const sidebars: SidebarsConfig = {
...productSpecificSidebars,
...apiSidebar,
// ... other sidebars
};
export default sidebars;
For REST API documentation, sidebars are generated alongside the API docs with the OpenAPI Docs plugin.
- Plugin generates documentation from OpenAPI specs
- Sidebar files are created in specified output directories
- Generated sidebars are imported into main REST API configuration
// Example of importing generated sidebar
{
type: "category",
label: "REST Endpoints",
items: require("../../docs/rest/compatibility-api/endpoints/sidebar")
}
Location: /config/sidebarsConfig/product-specific-sidebar.ts
- Handles product documentation navigation
- Includes sections for Voice, Video, Messaging, etc.
- Uses a common header generator function
function getProductSidebarHeader(productName: string) {
return [
{
type: "html",
value: `<div class="menu-html-category-header">${productName}</div>`,
},
// ... other header elements
];
}
Location: /config/sidebarsConfig/rest-api-sidebar.ts
- Combines manually configured sections with auto-generated content
- Generated sections include:
- Compatibility API endpoints
- SignalWire REST API endpoints (Calling, Chat, Voice, etc.)
- Plugin configuration specifies output directories:
{
outputDir: "docs/rest/compatibility-api/endpoints"
}
Location:
/config/sidebarsConfig/client-sdk-sidebar.ts
/config/sidebarsConfig/relay-browser-sidebar.ts
/config/sidebarsConfig/relay-realtime-sidebar.ts
Handles SDK documentation navigation including:
- Browser SDK
- Realtime SDK
- Client SDKs
- Previous SDK versions
Location:
/config/sidebarsConfig/swml-sidebar.ts
/config/sidebarsConfig/call-flow-builder-sidebar.ts
Sidebars can contain several types of items:
- Autogenerated Categories
{
type: "autogenerated",
dirName: "guides/voice-api"
}
- Manual Categories
{
type: "category",
label: "Overview",
items: [/* ... items ... */]
}
- Direct Links
{
type: "link",
href: "/guides",
label: "ᐸ Go back to all guides"
}
- HTML Elements
{
type: "html",
value: `<div class="menu-html-category-header">Voice</div>`
}
- Generated Index Pages
{
type: "category",
label: "REST Endpoints",
link: {
type: "generated-index",
title: "Available SignalWire REST Endpoints",
description: "API endpoint documentation",
slug: "/rest/signalwire-rest/endpoints"
}
}
- Create a new file in
/config/sidebarsConfig/
:
// config/sidebarsConfig/new-sidebar.ts
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
const newSidebar: SidebarsConfig = {
newSidebar: [
{
type: "category",
label: "New Section",
items: [/* ... items ... */]
}
]
};
export default newSidebar;
- Import and add to
index.ts
:
import newSidebar from './new-sidebar';
const sidebars: SidebarsConfig = {
...existingSidebars,
...newSidebar,
};
- Configure the OpenAPI plugin with the output directory
- Generate the documentation and sidebar files
- Import the generated sidebar into your configuration:
{
items: require("../../docs/your-api/endpoints/sidebar")
}
- Keep sidebar configurations modular and separate
- Use consistent naming conventions
- Leverage autogeneration where possible
- Group related content together
- Maintain clear category hierarchies
- Use descriptive labels and slugs
- Keep OpenAPI specifications and generated docs in sync
- Maintain consistent directory structure for generated content
If a sidebar isn't working:
- Check the sidebar configuration file
- Verify the import in
index.ts
- Ensure the directory structure matches autogenerated paths
- Check for duplicate sidebar IDs
- Verify the presets configuration
- For OpenAPI sidebars:
- Verify the documentation was generated
- Check the output directory structure
- Regenerate documentation if API specs changed