This repository contains the website including the documentation of metal-stack.io.
The used framework to generate docs is docusaurus.
├── blog # blogs folder structured by year
│ ├── 2019
│ ├── 2021
│ ├── 2022
│ ├── 2023
│ ├── 2024
│ └── 2025
├── docs # docs folder split by different scopes
│ ├── 08-References # auto-generated references of components and apis
├── community # guidelines for contributors and information about the community
│ ├── 04-Proposals # metal-stack enhancement proposals
├── scripts # custom scripts (e.g: resolving component documentation)
├── src # custom routes and react
│ ├── components
│ ├── css
│ ├── pages
│ └── plugins
├── versioned_docs # versioned docs (full copy of docs-folder)
│ ├── version-v0.21.4
│ └── version-v0.21.5
├── versioned_sidebars # versioned sidebars
├── docusaurus.config.ts # main docusaurus config
├── sidebars.ts # handle sidebar navigation structure
└── versions.json # list of versions
- Prioritize the
conceptsection. If this is about a MEP, you likely already have the contents for this. - Use the
generalsection to distribute users to their sections or to the deeper concept. - user, operator or developer specific sections would be nice, but are optional.
- Roles and Permissions
- Concept: explains all roles, permissions and sessions
- For operators: OIDC, creation in CI, ... How to / Explanation
- For users: how to guide to create tokens and edit permissions
- General: base concept, links to How to guides and deeper Concept
- CISO / Compliance: minimal need to know Principle Explanation / Concept
In order to not break links of posts, blog articles and shared documents we want to provide full backwards-compatibility. This means we need to ensure existing links still work with the new documentation.
The file /static/_redirects contains a list of all paths of the old docs-sites. The file is formatted to create server-side-redirects on netlify, following the documentation here: https://docs.netlify.com/routing/redirects/
In order to add new docs you need to be aware of 2 cases:
If you want to have your new document in the root-folder of the scope just add it with the following format:
---
slug: /your-doc-url
title: Title of document
position: <Position in sidebar as number>
---
<HERE YOUR DOCS>If you want to have a new document in the sub-folder of the scope just add it the same as before, but make sure you have a _category_.json.
This file is used to generate the sidebar.
{
"position": 2,
"label": "Overview"
}When adding images, SVGs, or similar assets, ensure they remain readable in both dark and light mode. For images containing text, consider adding a background to improve contrast and overall readability.
⚠️ referenced.drawio.svgimages throw warnings because of unsupported file-types. We save.drawiofiles separately and export them assvg. Issue is also known in docusaurus
Some svgs still can have problems e.g:
drawio.svgfiles pulled by references- too large svg
For this we have a pre-commit hook, which optimizes them with svgo
In order to add a blog-post follow this template. If a new author is referenced you have to add the author to the authors.yaml.
---
title: Your Title
watermark: "Blog"
date: 2025-02-03T10:00:00+02:00
description: short description of the post
authors: [gerrit91]
type: "blog"
categories:
- "Conferences"
tags:
- "News"
- "Conferences"
---
<SOME PREVIEW TEXT FOR BLOG LIST VIEW>
<!-- truncate -->
<YOUR ARTICLE>Requires Bun as .js runtime.
Run the following command to install dependencies:
bun installTo generate a local preview use:
bun run startTo update the dependencies for the Reference pages:
bun run fetch-readmesEnsure first, that all files in the docs folder are updated and ready to freeze. Also execute bun run fetch-readmes to update files from components and apis with the release-vector file from the main branch.
It is also possible to use bun run fetch-readmes v0.20.8 to use the release-vector file with a specific tag (i.E. v0.20.8).
All components are referenced in the /scripts/components.json file. Use this minimal template to add a new component:
The tag property will be updated automatically from the release-vector file.
You create a new version with:
bun run docusaurus docs:version v0.22Now, the new version will be create and the latest files will be copied to the "versioned" folders.
This, however, is usually done by the metal-robot through an automatically generated pull request.
The release notes can be synced from GitHub with the GitHub API. Therefore, ensure that a valid access token is created and set on the GitHub Runner or local machine with the name GITHUB_TOKEN.
To run the synchronization, run the following command:
bun run create-release-notesIf you run this before the build step, also the release notes get indexed.
{ "name": "metalctl", // name of the component, will appear in the navigation "releasePath": "binaries.metal-stack.metalctl.version", // json-path of the version or tag in the release-vector "branch": "main", // branch name. Some old repositories use 'master' "repo": "metal-stack/metalctl", // component repository, "tag": "v0.18.1", // latest release tag of the component repository "position": 1, // use this property to sort the navigation subdirectories "withDocs": true // set to true to retrieve further .md files from a /docs folder. With false, only the README.md will be retrieved. }