Overture Docs

Overture Docs is a centralized documentation site built with Docusaurus that aggregates and renders Markdown content from /docs directories across our GitHub repositories. It transforms distributed documentation into a cohesive and easy to navigate knowledge base.

Note

This repository is documented in detail on the Overture Docs site linked here (to be linked once live)

Getting Started

Running it Locally

1. Clone the repository with the submodules:

git clone --recurse-submodules https://github.com/overture-stack/docs.git

Tip

Already cloned the repo? You can still get the submodules by running: git submodule update --init --recursive

2. Install required dependencies from the website directory:

cd website
npm ci

3. Start the server:

npm start

Important

Docusaurus requires node version 18 or higher. All npm commands run from website/; there is no package manifest at the repository root.

How Overture Docs Works

• Docusaurus: We use Docusaurus to render the site, providing a sleek and navigable interface for our documentation.

• Four documentation sections: The site is organized around what a reader is trying to do, rather than around our repository layout. Each section is a separate Docusaurus docs plugin instance with its own content directory, route, and sidebar:

  Section	Content	Route	Sidebar
  Develop	website/docs/develop-docs/	/develop	developSidebars.ts
  Deploy	website/docs/deploy-docs/	/deploy	deploySidebars.ts
  Use	website/docs/use-docs/	/use	useSidebars.ts
  Community	website/docs/community-docs/	/community	communitySidebars.ts

• Markdown Files: All documentation content is stored as Markdown (or MDX) files under website/docs/, within the section it belongs to.

• Git Submodules: We use Git submodules to store and track all our GitHub repositories within one main repository. All submodules can be found in the submodules folder.

• Symlinks: Only the necessary documentation files are symlinked from the submodules into website/docs/. This allows us to import only the required Markdown content that Docusaurus needs. The symlinks are generated by symlinker.sh, which is the source of truth for what gets surfaced; run ./symlinker.sh from the repository root after changing which submodule docs the site includes.

• Redirects: Legacy URLs are preserved through @docusaurus/plugin-client-redirects, configured in website/docusaurus.config.ts, so older links and bookmarks continue to resolve.

• Interactive components: Some pages embed browser-based tooling (the configuration generator, the Lectern dictionary playground, and the Song schema playground) built as React components under website/src/components/.

Repository structure

.
├── /submodules/                # Core Repository Submodules
│   ├── /.github/               # GitHub configurations, workflows and standards docs
│   ├── /arranger/              # Arranger repository
│   ├── /lectern/               # Lectern repository
│   ├── /lyric/                 # Lyric repository
│   ├── /maestro/               # Maestro repository
│   ├── /score/                 # Score repository
│   ├── /song/                  # Song repository
│   └── /stage/                 # Stage repository
│        └── /docs/             # Repository-specific documentation (found in every submodule repo)
│
├── symlinker.sh                # Regenerates the submodule doc symlinks under /website/docs/
│
└── /website/                   # Documentation Website
    ├── /docs/                  # All documentation content, split by reader journey
    │   ├── /develop-docs/      # Per-component developer docs (symlinked from submodules)
    │   ├── /deploy-docs/       # Prelude and deployment documentation
    │   ├── /use-docs/          # Guides, workshop, administration, playgrounds
    │   └── /community-docs/    # Community resources, guidelines and standards
    ├── /remark/                # Custom remark plugins applied to vendored content
    ├── /src/                   # Website source code
    │   ├── /components/        # React components
    │   ├── /css/               # Component-specific styles
    │   ├── /theme/             # Global theme configuration and styling
    │   └── /pages/             # Static page content
    ├── /static/                # Static assets served as-is
    ├── docusaurus.config.ts    # Site config: plugin instances, navbar, redirects
    └── *Sidebars.ts            # One sidebar file per documentation section

Key Directories

• /submodules/: Contains all Overture core repositories as Git submodules
• /website/: Houses the Docusaurus-powered documentation website
  • /docs/develop-docs/: Component-level documentation, automatically linked from repository submodules
  • /docs/deploy-docs/: How to stand up and configure an Overture deployment
  • /docs/use-docs/: Task-oriented content for people working with a running platform
  • /docs/community-docs/: Community-focused content, including the org-wide documentation standards linked from the .github submodule
  • /src/: Website implementation files including custom components, styling, and page content

Important

Documentation content is owned by the submodules, not by this repository. Where a page under website/docs/ is a symlink, edit the source file in submodules/<project>/docs/ and land the change through that project's own repository.

Benefits of this Setup

• A Centralized Resource for Decentralized Documentation: A single, easy-to-navigate hub displaying all our developer documentation while keeping all documentation markdown files within their respective repositories.

• Consistent: Enables us to easily ensure all documentation follows the same standards across different projects.

• Easy to Maintain: Updates to any of the individual project repositories /docs folders are automatically reflected here.

• Robust Error Handling: Docusaurus has excellent error catching, particularly for broken and missing links, reducing the need for manual testing.

Tip

The Overture Docs repo contains everything, therefore finding & tracking links and content across all our repos has never been easier.