Skip to main content

Add a new repo

Your goal is to create the canonical repo docs that people open first in docs_ui. That means the repo needs a clear home, useful pages, accurate links, and a verification pass before anyone treats the new section as trusted documentation.

1. Decide whether this is a new project or part of an existing one​

Start by answering two questions:

  • Does the repo deserve its own project section under docs/<project>/...?
  • Or is it better documented as part of an existing project, example, or reference page?

Use a new project section when the repo has its own mental model, workflows, and navigation needs. Use an existing project when the repo mainly supports an already-documented product surface.

2. Gather the first-pass structure before writing pages​

Before creating files, collect:

  • the repo path inside the workspace, such as momentum-online/triggers-sdk-go
  • the short project label that should appear in the docs UI
  • the default page that newcomers should hit first
  • the Bitbucket repo URL you want exposed from the project chip or page links
  • the source docs you may want to import instead of rewriting by hand

If any of those are still fuzzy, stop and work through Collect source material first.

3. Create the project shell​

For a new project, create a docs folder that mirrors the published information architecture:

docs/<project>/
docs/<project>/start-here/
docs/<project>/build/
docs/<project>/observe/
docs/<project>/reference/
docs/<project>/examples/

Then add _category_.json files for the folders you want grouped in the sidebar.

Use curated pages for:

  • overviews
  • quickstarts
  • step-by-step maintainer guidance
  • pages that synthesize multiple source repos into one docs story

4. Register the project in the UI​

Update these files when the repo becomes a first-class project:

  • src/data/projects.ts
    • add the project label
    • set the default route
    • add the Bitbucket link
  • sidebars.ts
    • wire the new docs pages into the published sidebar
  • docusaurus.config.ts
    • only if the top navbar should expose the new project directly

If the repo belongs inside an existing project, update only the relevant project metadata and sidebar entries instead of adding a brand-new shell.

5. Import repo-owned docs only when they already work as references​

If the source repo already has strong reference material, add it to scripts/doc-metadata.mjs so the sync pipeline can copy it into the right target route.

That file controls:

  • source path inside the workspace
  • destination path inside docs_ui
  • public slug
  • title and description
  • whether the page should remain unlisted

After editing the import manifest, run:

make sync

This regenerates the imported markdown files under docs/<project>/reference/... or docs/<project>/examples/....

6. Write the curated pages that tie the repo into the site​

Even when you import reference docs, you usually still need curated pages for:

  • an overview
  • a quickstart or getting-started page
  • the "why this repo matters" explanation
  • cross-links to examples, runbooks, and related repos

Those are the pages that make the docs site readable. Imported pages are supporting material, not the whole experience.

7. Verify before handing off​

At minimum, run:

make sync
make build
make verify

When navigation, search, or route layout changed, also run:

make smoke

Then preview the section locally on http://localhost:8877 and click through the first-time-user path yourself.

Finish​