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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

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

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

Install required dependencies from the website directory:

cd website
npm ci

Start the server for whichever of the two sites you are working on:

npm start # docs.overture.bio, the documentation site
npm run start:marketing # overture.bio, the marketing site

Both serve on port 3000, so to run them side by side give one of them another port: npm run start:marketing -- --port 3001.

Important

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

Tip

One repository, two sites. npm start serves the documentation with its homepage at /; npm run start:marketing serves the marketing site with its homepage at /. Neither contains the other's routes. Two builds, one branch explains how the switch works.

Checking your work

Three commands are worth running before you open a pull request, all from website/:

npm run typecheck # tsc across website/src/
npm run build # the documentation site
npm run build:marketing # the marketing site

onBrokenLinks is set to throw, so a link to a page that does not exist fails the build rather than shipping a 404. Run both builds even when a change looks like it belongs to one site: src/theme/, the emitted stylesheet and docusaurus.config.ts are shared, so a change there can break the site you were not looking at.

The dev server is client-rendered and will not catch either of those. To see what Netlify actually serves, build and serve the output: npm run serve for the documentation site, npm run serve:marketing for the marketing one.

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/.
Two sites from one repository: this repository builds both docs.overture.bio and the overture.bio marketing site, selected by the OVERTURE_SITE environment variable. See The overture.bio marketing pages and Deployment.

The overture.bio marketing pages

The marketing site was ported into this repository so that one codebase serves both hostnames. The code is complete and both sites build; what is left is the Netlify and DNS work described under Deployment, which is what actually moves visitors from the Gatsby site to this one.

Where the code lives: everything is under website/src/marketing/. Routes are pages/, one directory apiece (collaborate, impact, privacy, products, terms-conditions) plus pages/index.tsx, which is the home page. Components, constants, case-study data and stylesheets sit alongside them.
Two builds, one branch: docusaurus.config.ts reads OVERTURE_SITE. Unset, it builds the documentation site exactly as before. Set to marketing, it builds overture.bio: the documentation plugin instances and the redirect table are dropped, and the pages plugin points at src/marketing/pages/ so the marketing home is served at /. Search stays on both sites, against the same index, with the marketing build configured to send results cross-host. Neither site contains the other's routes, so neither hostname serves a second copy of the other.
The two sites have separate navigation: the marketing build carries its own navbar and footer so a reader can tell which of the two sites they are on. website/src/theme/Navbar/ and website/src/theme/Footer/ pick one using useIsMarketingSite, which reads the build mode rather than the route. Adding a marketing nav item means editing MarketingNavbar.tsx, not the site config.
Styles are Sass, and they are scoped: the marketing pages carry their own styling, which would otherwise fight the documentation theme. Every stylesheet is imported inside a .marketing block by website/src/marketing/styles/index.scss, and only MarketingPage.tsx imports that file. If you are adding marketing styles, add a partial and import it there rather than importing a stylesheet from a component.
Assets live in website/static/img/marketing/ and are referenced by path, not imported.

Note

The staged copy of the Gatsby site that lived here during the port was deleted once the pages were rebuilt. overture-stack/website still serves overture.bio until DNS is cut over, so until then a change that has to reach the live site goes there, not here.

Deployment

Both sites are Netlify sites building this repository from the same branch. They differ only in one environment variable and the publish directory.

	docs.overture.bio	overture.bio
Base directory	`website`	`website`
Build command	`npm ci && npm run build`	`npm ci && npm run build:marketing`
Publish directory	`website/build`	`website/build-marketing`
`OVERTURE_SITE`	unset	`marketing`
`NODE_VERSION`	`20`	`20`

Neither site needs a netlify.toml, and adding one would be a mistake: a single file on a single branch cannot say different things to two sites. Everything that would go in one is expressed per site instead.

Redirects live in website/static-docs/_redirects and website/static-marketing/_redirects. Each is copied into its own build's output by the staticDirectories setting, so each host serves only the rules it owes. Netlify combines them with any rules configured in the site UI, applying the UI rules first.
robots.txt is per host for the same reason, next to each _redirects.
sitemap.xml is generated for each build from the url in docusaurus.config.ts, so it always names the host it is served from.
Submodules are fetched by Netlify automatically: every URL in .gitmodules is public HTTPS. The documentation symlinks under website/docs/ are committed as git symlinks with relative targets, so symlinker.sh does not need to run during a build.

Because submodule pointers are pinned commits, a documentation change landed in a component repository does not reach the deployed site until a submodule bump is committed here.

Running either site locally is covered under Running it Locally.

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
│ ├── /marketing/ # Components, data and Sass for the overture.bio pages
│ ├── /theme/ # Global theme configuration and styling
│ │ └── /pages/ # The overture.bio routes; index.tsx is its home page
│ └── /pages/ # Documentation homepage
├── /static-docs/ # robots.txt and _redirects for docs.overture.bio only
├── /static-marketing/ # robots.txt and _redirects for overture.bio only
├── /static/ # Static assets served as-is
│ └── /img/marketing/ # Images and icons for the marketing pages
├── 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
- /src/marketing/: The overture.bio marketing site, rebuilt from the Gatsby site, routes included
- /static-docs/, /static-marketing/: The files each host serves alone, robots.txt and _redirects. See Deployment

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.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as the rest of the Overture stack. See LICENSE for the full text, and the licensing page for an overview.

Documentation content vendored from the submodules/ repositories remains under the license of its own repository.

Name		Name	Last commit message	Last commit date
submodules		submodules
website		website
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
preview.png		preview.png
symlinker.sh		symlinker.sh

Name		Name	Last commit message	Last commit date
submodules		submodules
website		website
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
preview.png		preview.png
symlinker.sh		symlinker.sh

Name		Name	Last commit message	Last commit date
submodules		submodules
website		website
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
preview.png		preview.png
symlinker.sh		symlinker.sh

Name		Name	Last commit message	Last commit date
submodules		submodules
website		website
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
preview.png		preview.png
symlinker.sh		symlinker.sh

Name		Name	Last commit message	Last commit date
submodules		submodules
website		website
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
preview.png		preview.png
symlinker.sh		symlinker.sh

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Overture Docs

Getting Started

Running it Locally

Checking your work

How Overture Docs Works

The overture.bio marketing pages

Deployment

Repository structure

Key Directories

Benefits of this Setup

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Overture Docs

Getting Started

Running it Locally

Checking your work

How Overture Docs Works

The overture.bio marketing pages

Deployment

Repository structure

Key Directories

Benefits of this Setup

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Overture Docs

Getting Started

Running it Locally

Checking your work

How Overture Docs Works

The overture.bio marketing pages

Deployment

Repository structure

Key Directories

Benefits of this Setup

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases