Redesign of the Docs Reference Section

[vknabel]

Description

What's the issue?

On our documentation we have a reference section that essentially contains markdown documentation from other repositories. As one case let's head to metal-images. Here the README is linked to the menu entry itself. Here we currently traverse every linked document and add it as a child entry like the ARCHITECTURE.md to the link docs/references/ARCHITECTURE.

Now if we had another ARCHITECTURE.md in any other repo, these slugs would collide.
As we only respect files that are explicitly linked, other resources like a DEVELOPMENT.md or a whole docs/ folder would be missing.

Next: while all-caps file names are fine inside a repo, they feel really weird on websites.

Which files to sync?

• sync all *.md files, keep paths
• only referenced files (start by README)
• README + docs

Which titles?

• file names or in case of README, folder name
• the name of the link to that file
• the title of the file
• use frontmatter

Which reference structure?

• flat?
• nested? how deep in nav?
• curated?
• combine multiple files into one?

What should the urls look like?

• nested?
• flat?

[vknabel]

Want to have a look into this after the next planning meeting

[vknabel]

Edit: I'll add more context and details on the algorithm later today 2026-01-26. ✔️

Here is my proposal to approach this:

• best would be to sync README.md and docs/
  • This eliminates potential error sources
  • eventually add a few more like DEVELOPMENT.md
  • linked documents outside the whitelist and docs are will link to GitHub
• for the title:
  • md files in docs/ can use frontmatter directly
  • README and other whitelisted can be handled explicitly
• Filename itself:
  • README -> name of the repo
  • all in docs as is
• keep nested paths as is, but prefixed with path to reference component
  • like /docs/references/metal-images/image-store
• all non-md-file links outside docs/ should point to the repo itself
• for assets we should adhere to the same principles if it makes sense

In practice this should minimize potential link errors and should reduce the complexity of the syncing process.

Migration Strategy

• Implement the new approach (for testing)
• add docs/references/... and docs/next/references/... redirects to static/_redirects (beware that old versions still keep the old URL!)
• for every repo in references
  • consider moving markdown files from root to docs
  • consider if a new special case is required
  • consider to add frontmatter to docs
  • test in the docs PR
• prepare everything before a metal-stack release
• then merge and release the components
• then merge and release the website (next would now be up to date)