configs

Updating root README.md

3 min read

The repo README.md is the topic/folder-level overview of the whole repo (not just the vault). It is coarser than the MOC: it lists topics and folder counts, not every note. Keep it in English (the README is an English artifact even though some vault notes are Ukrainian).

Always read the current README.md before editing.

Structure

SectionContentTouch when…
# configs + introone-line repo descriptionrarely
## StructureASCII tree of top-level dirs with # inline commentsa folder is added/removed/renamed, or a note count in a comment changes
## Obsidian Vault → ### Configurationstable: Category | Topic | Descriptiona config topic/folder is added
## Obsidian Vault → ### Certificationsbold cert name + table Section | Topicsa cert section/topic is added
## Obsidian Vault → ### Studyingtable: Topic | Notes (with note counts)a study topic is added, or a count changes
## Blueprints / ## Dotfiles / ## VS Code / ## Bookstables for the non-vault areasthe matching folder changes

Granularity — important

  • Adding a single note inside an existing topic usually means only: bump a count (18 notes → 19 notes) and, if the scope shifted, tweak that row’s description. The README does not get a row per note.
  • Adding a new topic folder → add one table row in the right ### subsection, and update the ## Structure tree.
  • Adding a new top-level area → add a new ## section + tree entry.

Compare against the MOC: MOC changes on every note; README changes mostly on topics/folders and counts.

Table conventions

  • Keep columns aligned (pad cells with spaces) and match the style of existing rows.
  • Link to the folder (or the MOC), not individual notes, e.g. [Cisco Networking Basics](obsidian/studying/cisco/).
  • URL-encode spaces in paths: obsidian/configs/starrocks/disaster%20recovery/.
  • Descriptions are terse, English, noun-phrase style — mirror neighboring rows.

ASCII tree

Under ## Structure, keep the tree in sync with real folders. Match the existing comment style (aligned # comments). Example row:

│   └── studying/              # Active study notes
│       ├── cisco/             # Networking basics (18 notes, Ukrainian)
│       └── observability/     # Metrics, logs, traces, profiles

When a folder’s note count appears in a comment (e.g. 18 notes), update it when notes are added/removed.

Procedure

  1. Read README.md. Identify which section(s) the change affects (often just ## Structure + one ### table).
  2. Make the minimal edit: new row, new tree line, or a count/description tweak. Keep alignment.
  3. Do not restyle unrelated rows or rewrite descriptions that didn’t change.
  4. If the change also adds/renames a note, remember the MOC needs the per-note update too (see update-moc.md).

Worked example — a new studying topic kubernetes-patterns with 3 notes

  1. ## Structure tree — add under studying/: 
    │       ├── cisco/             # Networking basics (18 notes, Ukrainian)
│       ├── kubernetes-patterns/ # Workload & scaling patterns (3 notes)
│       └── observability/     # Metrics, logs, traces, profiles
  2. ### Studying table — add a row: 
    | Kubernetes Patterns | [kubernetes-patterns](obsidian/studying/kubernetes-patterns/) — 3 notes: … |
  3. Leave every other row and section untouched.

Graph View

Backlinks