Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,13 @@

## Sidebar pattern

Every section uses a dedicated sidebar function in `docs/.vitepress/config.mts` instead of the generic `generateSidebar` call. The function filters out `index.md` from the generated items and prepends it manually as a pinned "Overview" entry at the top.
Every section's sidebar in `docs/.vitepress/config.mts` is built so its top entry is a named group whose header matches the section name. The group filters out `index.md` from the generated items and prepends it manually as a pinned "Overview" entry at the top.

Sections using this pattern: Storage, Observability, Network, OpenStack, Overview.
This is produced by the universal `sectionSidebar(path, title, extra?)` helper (which itself uses `sectionItems()` to generate and filter items). The `sidebar` object spreads one `sectionSidebar(...)` call per section.

When adding a new section, add a dedicated `<name>Sidebar()` function following the same shape, remove the section from the raw `generateSidebar` array, and spread the new function into the `sidebar` object.
When adding a new section, add a `...sectionSidebar('<path>', '<Title>')` line to the `sidebar` object — nothing else is needed. Pass vitepress-sidebar overrides (e.g. `excludePattern`) as the third `extra` argument.

Two sections are special cases that build their groups inline rather than via `sectionSidebar`:

- `operationsSidebar()` — the Operations Manual nests Platform, Observability, and Sustainability under one shared header across four routes.
- `documentationSidebar()` — the Documentation nav links to About and shares one "Documentation" header across all seven documentation routes (About, Getting Started, Bare Metal, Compute, Storage, Network, OpenStack), each nested as a collapsible group with its own Overview + child pages. The Storage group preserves the `excludePattern: ['observability/**']` override.
214 changes: 114 additions & 100 deletions bun.lock

Large diffs are not rendered by default.

292 changes: 102 additions & 190 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -2,135 +2,45 @@ import { withMermaid } from "vitepress-plugin-mermaid";
import { generateSidebar } from 'vitepress-sidebar';
import { fileURLToPath, URL } from 'node:url'

function storageSidebar() {
// Generate the raw items for a section, with index.md filtered out so it can be
// re-added manually as a pinned "Overview" entry.
function sectionItems(scanStartPath: string, resolvePath: string, extra: Record<string, any> = {}) {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'storage',
resolvePath: '/storage/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
excludePattern: ['observability/**'],
}]);
const items = generated['/storage/'].items.filter((i: any) => i.link !== 'index.md');
return {
'/storage/': {
base: '/storage/',
items: [
{ text: 'Storage', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
],
},
};
}

function networkSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'network',
resolvePath: '/network/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);
const items = generated['/network/'].items.filter((i: any) => i.link !== 'index.md');
return {
'/network/': {
base: '/network/',
items: [
{ text: 'Network', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
],
},
};
}

function openstackSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'openstack',
resolvePath: '/openstack/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);
const items = generated['/openstack/'].items.filter((i: any) => i.link !== 'index.md');
return {
'/openstack/': {
base: '/openstack/',
items: [
{ text: 'OpenStack', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
],
},
};
}

function overviewSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'overview',
resolvePath: '/overview/',
scanStartPath,
resolvePath,
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
...extra,
}]);
const items = generated['/overview/'].items.filter((i: any) => i.link !== 'index.md');
const showroomEntry = { text: 'Showroom', link: 'showroom/', base: '/' };
const overviewItems = [
{ text: 'About CobaltCore', items: [{ text: 'Overview', link: '/overview/' }, ...items.map((i: any) => ({ ...i, link: '/overview/' + i.link })), showroomEntry] },
];
return {
'/overview/': { items: overviewItems },
'/showroom/': { items: overviewItems },
};
return generated[resolvePath].items.filter((i: any) => i.link !== 'index.md');
}

function observabilitySidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'observability',
resolvePath: '/observability/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);
const items = generated['/observability/'].items.filter((i: any) => i.link !== 'index.md');
// Universal sidebar pattern: a named section header matching the section name,
// with a pinned "Overview" entry at the top followed by the generated items.
// Every section uses this; the header text is the banner shown in the sidebar.
function sectionSidebar(path: string, title: string, extra: Record<string, any> = {}) {
const resolvePath = `/${path}/`;
const items = sectionItems(path, resolvePath, extra);
return {
'/observability/': {
base: '/observability/',
[resolvePath]: {
base: resolvePath,
items: [
{ text: 'Observability', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
{ text: title, items: [{ text: 'Overview', link: 'index.md' }, ...items] },
],
},
};
}

// Special case: the Operations Manual nests Platform, Observability and
// Sustainability under a single shared header across four routes.
function operationsSidebar() {
const genSection = (scanStartPath: string, resolvePath: string) => generateSidebar([{
documentRootPath: '/docs/',
scanStartPath,
resolvePath,
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);

const platformItems = genSection('operations/platform', '/operations/platform/')['/operations/platform/'].items
.filter((i: any) => i.link !== 'index.md');
const observabilityItems = genSection('observability', '/observability/')['/observability/'].items
.filter((i: any) => i.link !== 'index.md');
const sustainabilityItems = genSection('sustainability', '/sustainability/')['/sustainability/'].items
.filter((i: any) => i.link !== 'index.md');
const platformItems = sectionItems('operations/platform', '/operations/platform/');
const observabilityItems = sectionItems('observability', '/observability/');
const sustainabilityItems = sectionItems('sustainability', '/sustainability/');

const sharedItems = [
{
Expand All @@ -141,7 +51,7 @@ function operationsSidebar() {
text: 'Platform',
collapsed: true,
base: '/operations/platform/',
items: [{ text: 'Overview', link: '/platform/' }, ...platformItems],
items: [{ text: 'Overview', link: 'index.md' }, ...platformItems],
},
{
text: 'Observability',
Expand All @@ -167,25 +77,84 @@ function operationsSidebar() {
};
}

function governanceSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'governance',
resolvePath: '/governance/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);
const items = generated['/governance/'].items.filter((i: any) => i.link !== 'index.md');
return {
'/governance/': {
base: '/governance/',
// Special case: the Documentation nav links to About and shares a single sidebar
// across all seven documentation sections, nesting each (other than About) under
// a collapsible group with its own Overview + child pages.
function documentationSidebar() {
const gettingStartedItems = sectionItems('getting-started', '/getting-started/');
const controlPlaneItems = sectionItems('control-plane', '/control-plane/');
const bareMetalItems = sectionItems('bare-metal', '/bare-metal/');
const computeItems = sectionItems('compute', '/compute/');
const storageItems = sectionItems('storage', '/storage/', { excludePattern: ['observability/**'] });
const networkItems = sectionItems('network', '/network/');
const openstackItems = sectionItems('openstack', '/openstack/');
const aboutItems = sectionItems('about', '/about/');

const sharedItems = [
{
text: 'Documentation',
items: [
{ text: 'Governance', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
{
text: 'About CobaltCore',
collapsed: true,
base: '/about/',
items: [{ text: 'Overview', link: 'index.md' }, ...aboutItems],
},
{
text: 'Getting Started',
collapsed: true,
base: '/getting-started/',
items: [{ text: 'Overview', link: 'index.md' }, ...gettingStartedItems],
},
{
text: 'Control Plane',
collapsed: true,
base: '/control-plane/',
items: [{ text: 'Overview', link: 'index.md' }, ...controlPlaneItems],
},
{
text: 'Network',
collapsed: true,
base: '/network/',
items: [{ text: 'Overview', link: 'index.md' }, ...networkItems],
},
{
text: 'Bare Metal Management',
collapsed: true,
base: '/bare-metal/',
items: [{ text: 'Overview', link: 'index.md' }, ...bareMetalItems],
},
{
text: 'Compute',
collapsed: true,
base: '/compute/',
items: [{ text: 'Overview', link: 'index.md' }, ...computeItems],
},
{
text: 'Storage',
collapsed: true,
base: '/storage/',
items: [{ text: 'Overview', link: 'index.md' }, ...storageItems],
},
{
text: 'OpenStack',
collapsed: true,
base: '/openstack/',
items: [{ text: 'Overview', link: 'index.md' }, ...openstackItems],
},
],
},
];

return {
'/about/': { items: sharedItems },
'/getting-started/': { items: sharedItems },
'/control-plane/': { items: sharedItems },
'/bare-metal/': { items: sharedItems },
'/compute/': { items: sharedItems },
'/storage/': { items: sharedItems },
'/network/': { items: sharedItems },
'/openstack/': { items: sharedItems },
};
}

Expand Down Expand Up @@ -227,24 +196,11 @@ export default withMermaid({
{ text: 'Home', link: '/' },
{
text: 'Documentation',
items: [
{ text: 'About CobaltCore', link: '/overview/' },
{ text: 'Getting Started', link: '/getting-started/' },
{ text: 'Bare Metal Management', link: '/bare-metal/' },
{ text: 'Compute', link: '/compute/' },
{ text: 'Storage', link: '/storage/' },
{ text: 'Network', link: '/network/' },
{ text: 'OpenStack', link: '/openstack/' },
],
link: '/about/',
},
{
text: 'Operations Manual',
items: [
{ text: 'Overview', link: '/operations/' },
{ text: 'Platform', link: '/platform/' },
{ text: 'Observability', link: '/observability/' },
{ text: 'Sustainability', link: '/sustainability/' },
],
link: '/operations/',
},
{ text: 'Blog', link: '/blog/' },
{ text: 'Community', link: '/community/' },
Expand All @@ -267,54 +223,10 @@ export default withMermaid({
},

sidebar: {
...generateSidebar([
{
documentRootPath: '/docs/',
scanStartPath: 'bare-metal',
resolvePath: '/bare-metal/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
},
{
documentRootPath: '/docs/',
scanStartPath: 'getting-started',
resolvePath: '/getting-started/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
},
{
documentRootPath: '/docs/',
scanStartPath: 'compute',
resolvePath: '/compute/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
},
{
documentRootPath: '/docs/',
scanStartPath: 'community',
resolvePath: '/community/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
},
]),
...storageSidebar(),
...networkSidebar(),
...openstackSidebar(),
...overviewSidebar(),
...sectionSidebar('community', 'Community'),
...sectionSidebar('governance', 'Governance'),
...documentationSidebar(),
...operationsSidebar(),
...governanceSidebar(),
},

socialLinks: [
Expand Down
File renamed without changes.
4 changes: 2 additions & 2 deletions docs/overview/index.md → docs/about/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,6 @@ order: 1
## How to navigate these docs

- **[Getting Started](/getting-started/)** - start here if you want to deploy CobaltCore
- **[Architecture](/overview/architecture)** - understand how the layers fit together
- **[Showroom](/showroom/)** - live examples and demos of CobaltCore in action
- **[Architecture](/about/architecture)** - understand how the layers fit together
- **[Showroom](/about/showroom/)** - live examples and demos of CobaltCore in action
- Layer sections (**Platform**, **Compute**, **OpenStack**, **Storage**, **Networking**, **Observability**, **Management**) - deep-dive reference for each part of the stack.
2 changes: 1 addition & 1 deletion docs/showroom/index.md → docs/about/showroom/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Showroom
order: 1
order: 3
---

# Showroom
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,4 +45,4 @@ CobaltCore is both a production implementation of Apeiro and a direct contributi

---

*Want to run it yourself? See the [Getting Started guide](/getting-started/) or the [Architecture overview](/overview/architecture).*
*Want to run it yourself? See the [Getting Started guide](/getting-started/) or the [Architecture overview](/about/architecture).*
Loading
Loading