This project builds the RIPE Database documentation site from markdown files using internal components.
We welcome updates to the documentation. This project is developed internally via GitLab, but is mirrored to GitHub. Contributions are welcome via GitLab merge requests or GitHub pull requests, or by creating an issue.
It is recommended to follow the current structure.
For consistency we recommend using # symbol to reference a section within the link.
This project uses Mermaid for diagrams. To add a diagram, place your .mmd file in docs/public/imgs/diagrams/. The diagrams are rendered automatically at build time.
GitLab has a handy built-in editor that understands most of the markdown that is in the markdown files. There are a few exceptions that are particular to VitePress:
| Gitlab markdown | Vitepress markdown |
|---|---|
| collapsible sections are rendered with <details><summary></summary><content></content></details> | collapsible sections rendered same as gitlab OR by ::: details summaryText contentText ::: |
| Embedded vite components are ignored | Embedded vue components (like <RestRepl />) are recognized and rendered |
Once you download the repository in your local machine you can run the service using NPM or Docker.
Do not use yarn, it has problems with some dependencies.
We recommend the Docker approach for testing. Running npm run docs:build modifies the docs by updating the last-updated header.
The VitePress configuration and build scripts are maintained in a separate internal repository. Before running locally with NPM, you need to clone them:
git clone --depth 1 https://gitlab.ripe.net/swe-database-team/ripe-database-documentation-components.git docs-components
mv docs-components/.vitepress .
mv docs-components/vpscripts .
rm -rf docs-componentsThen install dependencies and start the dev server:
npm install
npm run docs:devThis will launch a local server; the port will be shown in the console.
Use docker build and run
docker build --no-cache -f docker/Dockerfile -t ripe-database-documentation . && docker run --rm -p 8080:8080 ripe-database-documentationor use docker compose (preferred option)
docker compose -f docker/compose.yml up --buildThis project depends on VitePress to build the static site from Markdown.
The VitePress configuration and components are kept in a separate internal repository (ripe-database-documentation-components) and are fetched during the build process. See the NPM section for how to set them up locally.
IMPORTANT! Any change done to legal, T&C or AUP require approval from Legal. So please don't edit those files unless you have the permission from Legal.
The documentation is covered by the terms of the license.