Site Maintenance Guide

This site is built on VitePress, but it uses a custom "Auto-Sidebar" logic to make your life easier. You do not need to edit specific config files for every single page you create.

The Golden Rule

Filesystem = Structure. If you want to change the order of the sidebar, you change the filename on the disk.

1. Adding a New Page

To add a new topic to an existing section (e.g., Architecture), simply create a Markdown file in that folder.

The Naming Convention: We use a Number-Name format to control the sort order.

• 01-Core-Architecture.md (Appears 1st)
• 02-Etcd-Datastore.md (Appears 2nd)
• 99-My-New-Topic.md (Appears last)

Action:

1. Create docs/architecture/07-My-New-Topic.md.
2. The Sidebar will automatically strip the 07- and dashes, displaying it as "My New Topic".

2. Moving or Renaming Pages

If you want to move a page from Workloads to Operations:

1. Move the physical file: mv docs/workloads/04-Autoscaling.md docs/operations/
2. Rename it to fit the new sequence: mv docs/operations/04-Autoscaling.md docs/operations/08-Autoscaling.md
3. Restart the dev server (sometimes required for structure changes): npm run docs:dev

3. Adding a New Section

If you want a brand new folder (e.g., docs/certifications), you must do one configuration step because we manually define the order of sections.

Step A: Create the folder and file. mkdir docs/certificationstouch docs/certifications/01-CKA-Prep.md

Step B: Edit docs/.vitepress/config.mts. Add your new section to the sections array:

const sections = [
  { dir: 'foundations', title: 'Linux Foundations' },
  { dir: 'architecture', title: 'Architecture' },
  { dir: 'certifications', title: 'Certifications' }, // <-- Add this
  // ...
]

4. Editorial Style Guide

To maintain the "Premium Journal" look, use these HTML snippets.

The Question Header (H1) Used for the main title of every page.

<h1 class="q-header">How do I fix a CrashLoopBackOff?</h1>

The Drop Cap (First Paragraph) Used for the opening summary.

<p class="editorial-dropcap">
This is the first letter that will be huge.
</p>