Skip to main content

Contributing to the documentation

This page explains how to contribute to the FirstBreath documentation (Docusaurus site in apps/docs).

Where to write​

  • English (source): apps/docs/docs/ — add or edit .md files in the appropriate section (backend, frontend, vision, mobile, showcase, infrastructure, qa).
  • French: apps/docs/i18n/fr/docusaurus-plugin-content-docs/current/ — mirror the same folder structure and translate the content.

Structure and conventions​

  • Use Markdown (and MDX if needed). Diagrams: Mermaid (supported by the theme).
  • Each doc should have a frontmatter with at least sidebar_position (and optionally title, last_update: { date: "YYYY-MM-DD" }).
  • Avoid broken links: internal links use paths like /docs/backend/overview/intro. Run npm run build to catch broken links (onBrokenLinks: 'throw').

Editing from the site​

Each documentation page has an "Edit this page" link (or equivalent) that points to the repository. It uses the editUrl in docusaurus.config.ts (e.g. FirstBreath/FirstBreath-Platform/tree/main/apps/docs). Use it to open the right file on GitHub.

Local preview​

From apps/docs:

npm install
npm run start

Open http://localhost:3000. For French: npm run start -- --locale fr then http://localhost:3000/fr/.

Adding a new doc​

  1. Create the .md file in docs/ under the right section (e.g. docs/backend/guides/my-feature.md).
  2. The sidebar is autogenerated from the folder structure; use _category_.json in a folder to set its label and order.
  3. If the doc is in French, add or update the corresponding file under i18n/fr/docusaurus-plugin-content-docs/current/ with the same path.

Full repo contributing​

See CONTRIBUTING.md in apps/docs for clone, branch, and PR workflow specific to the docs app.