Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Sidebar Reorg Requirements

The Uvilo OS site must preserve the existing sidebar hierarchy while exposing project structure more faithfully and making project contents readable and navigable.

Required outcome

  • Maintain a list of project holder folders. A folder is a project folder if and only if it is one level below a project holder folder.
  • The current project holder folder list contains: Product/Projects, Forge/Projects, Forge/Skills
  • Every project folder must have a README.md landing page.
  • Each project README.md must be auto-generated and kept up to date.
  • Each project README.md must contain:
    • a title
    • a short overview (auto-generated; preserved on regeneration if customized)
    • Parent Project (manually added; preserved on regeneration; omitted by default)
    • Sub-projects (manually added; preserved on regeneration; omitted by default)
    • a clickable folder structure
  • The existing sidebar hierarchy must remain in place.
  • README.md pages are added to the hierarchy; they do not replace the project’s other files in the sidebar.
  • The folder structure must link to all readable files in the project.
  • Supported non-Markdown text/code files must be readable through auto-generated file-view pages.
  • SKILL.md files are treated as non-Markdown source files for file-view purposes, since they use a skill-specific format incompatible with Starlight frontmatter. They are rendered as syntax-highlighted read-only file-view pages, not as native Starlight content pages.
  • Those auto-generated file-view pages must appear in the project’s visible navigation hierarchy rather than remaining hidden.
  • If a folder or sub-folder contains images, generate a single MEDIA.md page for that folder instead of one readable page per image.
  • MEDIA.md must list all images in that folder with previews and download links.
  • The site should follow the repository’s existing folder structure directly and add nothing beyond the defined README structure and generated file-view/media pages.

Ideal final outcome

  • A reader can enter any project through its README.md.
  • A reader can also navigate the project through the existing sidebar hierarchy, which remains intact.
  • A reader can understand the project’s place in the project hierarchy through Parent Project and Sub-projects.
  • A reader can browse the project through its folder structure without leaving the site’s information architecture.
  • A reader can open supported non-Markdown files as readable pages.
  • A reader can inspect image folders through generated MEDIA.md pages.
  • Important project contents are no longer hidden simply because they are not Markdown.