Foxino Internal Documentation

Internal technical and functional documentation of the Foxino platform: domain concepts, architecture and infrastructure.

Contributing

The documentation lives in the foxino-docs-internal git repository. It is written in AsciiDoc and built with Antora. Every commit to main is built by GitLab CI and published to GitLab Pages automatically.

Why git and not Notion

Documentation is treated like code:

  • Versioning — the docs are versioned alongside the systems they describe, and any past state can be checked out and built.

  • History — every change has an author, a date and a commit message explaining why it was made. git log and git blame answer "who changed this and why".

  • No random overwrites — changes go through merge requests, so nobody silently overwrites someone else’s work, and conflicting edits have to be resolved explicitly.

  • Review — changes can be discussed and approved in merge requests before they are published.

  • Tooling — plain text files work with any editor, can be searched with grep, and diagrams (Mermaid) are kept as text next to the pages.

How to contribute

  1. Clone the repository:

    git clone git@gitlab.dev.foxino.com:apps/foxino-docs-internal.git

  2. Create a branch and edit or add pages:

    • Pages are in modules/<module>/pages/*.adoc.

    • New pages must be added to the module navigation in modules/<module>/nav.adoc.

    • Mermaid diagrams and other reusable fragments go to modules/<module>/partials/.

  3. Build and preview the site locally (requires Node.js and Python 3):

    make serve

    Then open http://localhost:8000.

  4. Push the branch and open a merge request into main. Once it is merged, the site is rebuilt and published.