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:

npm ci

Start the server

npm start

[!IMPORTANT] Docusaurus requires node version 18 or higher

How Overture Docs Works

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

• Markdown Files: All documentation content is stored as markdown files in the /website/docs directory.

• 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 submodule folder.

• Symlinks: Only the necessary documentation files are symlinked from the submodules in the submodule folder to the /website/docs directory. This allows us to import only the required markdown content that Docusaurus needs.

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)
│
└── /website/                  # Documentation Website
    ├── /community/           # Community resources and guidelines
    ├── /docs/                # Aggregated documentation (symlinked from submodules)
    ├── /guides/              # Overture platform user guides
    └── /src/                 # Website source code
        ├── /components/      # React components
        ├── /css/            # Component-specific styles
        ├── /theme/          # Global theme configuration and styling
        └── /pages/          # Static page content

Key Directories

• /submodules/: Contains all Overture core repositories as Git submodules
• /website/: Houses the Docusaurus-powered documentation website
  • /community/: Community-focused content and resources
  • /docs/: Central location for all documentation, automatically linked from repository submodules
  • /guides/: Comprehensive platform guides and tutorials
  • /src/: Website implementation files including custom components, styling, and page content

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.