configs

House style — note formatting

5 min read

Exact anatomy of a vault note, the callout vocabulary, and the highlight color system. All examples are drawn from real notes in this vault.

1. Note anatomy, top to bottom

Line 1 — tags line

Literal tags: followed by space-separated #kebab-case inline tags. This is the very first line. It is not YAML frontmatter — do not wrap it in --- and do not convert it.

tags: #cisco #networking #client-server #p2p #peer-to-peer
  • Lowercase, hyphenated. Hierarchical tags use / (e.g. #en/noun) — but those belong to the vocab tooling; normal notes use flat tags.
  • 4–7 tags is typical: the topic (#cisco, #aws, #k8s), plus the note’s key concepts.
  • Reuse existing tag names so the colored-tags plugin keeps colors stable (see SKILL.md for the lookup command).

Line 2 — blank

Opener callout

One blank line after tags, then an opener that orients the reader. Pick by note type:

  • Study / multi-section note → > [!abstract] Contents with a table of contents of [[#heading]] links:

    > [!abstract] Contents
>
> - [[#Сервери]]
> - [[#Клієнти]]
> - [[#Однорангові мережі (P2P)]]
>   - [[#Переваги]]
>   - [[#Недоліки]]

    Sub-headings are indented with a tab. Link text must match the heading exactly.

  • Guide / runbook → > [!abstract] Goal with a one-line statement of intent:

    > [!abstract] Goal
> Safely upgrade Karpenter on an EKS cluster. Version-agnostic — substitute your own source/target versions.

  • Optional extra openers, collapsed by default with -, e.g. external references:

    > [!info]- Official docs
>
> - [Upgrade guide](https://karpenter.sh/docs/upgrading/upgrade-guide/)

Separator

A --- on its own line after the opener callout(s), before the body.

Body

  • Headings: ## (H2) for sections, ### (H3) for subsections. Never # (H1). The note title comes from the filename, so an H1 inside the note is wrong.
  • A short lead paragraph may sit between the --- and the first ## (see 1. Типи мереж.md, which defines Інтернет before the first section).
  • Images: ![[filename|width]], e.g. ![[Screenshot 2026-04-28 at 10.42.53.png|697]].
  • Lists, tables, and code fences as the content needs. Keep existing ones; don’t restructure content to fit a template.

Callout vocabulary used in this vault

CalloutUse
[!abstract]Opener — Contents (TOC) or Goal
[!info]-Collapsed supporting block — links, prerequisites, reference
[!important]A caveat the reader must not miss
[!success]-Embedded certificate PDF (mostly in MOC)
[!summary]-Summaries block (MOC only)
[!example]+ / [!tip]+Topic wrappers (MOC only)

+ = expanded by default, - = collapsed, neither = expanded and non-foldable. Match the existing convention; don’t invent new callout types.

2. Highlight system

Syntax

Always HTML <mark> with an inline background, never ==…== (so the color is explicit and stable):

<mark style="background: #FFF3A3A6;">key term</mark>

Palette (Obsidian native, A6 = ~65% alpha — readable on light and dark themes)

RoleColorHex
Primary term being definedyellow#FFF3A3A6
Related / secondary conceptblue#ADCCFFA6
Pros / benefits / recommended / “do”green#BBFABBA6
Cons / risks / warnings / deprecated / “don’t”red#FF5582A6
Protocol / standard / named technologypurple#D2B3FFA6
Values / numbers / ranges (ports, sizes, IPs)cyan#ABF7F7A6
Commands / actions / process stepsorange#FFB86CA6
Contrasting alternative to the primarypink#FFB8EBA6

Rules

  1. Highlight key theses only. Roughly the one term being defined per paragraph or section — the word a reader would underline. Not whole sentences, not every noun. If half the paragraph is highlighted, none of it stands out.
  2. One color = one concept group. Terms that belong together share a color: a term and its definition, synonyms, or items of the same category. Highlighting the same recurring term keeps its color throughout the note.
  3. Unrelated concepts get different colors. This is the upgrade from the legacy single-yellow notes — when two highlighted theses are not related, give them distinct colors so the eye separates them.
  4. Contrast pairs use opposites. Advantages green ↔ drawbacks red; recommended green ↔ deprecated red; allowed green ↔ denied red.
  5. Restraint. ~2–4 colors per note is normal. Reach for the extended roles (purple/cyan/orange/pink) only when the content genuinely has that many distinct groups.

Worked example — studying/cisco/Основи роботи в мережі/4. Клієнти та сервери.md

This note currently uses one yellow for three unrelated concepts. Recolor by role:

Before:

<mark style="background: #FFF3A3A6;">Сервери</mark> – це хости з встановленим програмним забезпеченням…
 
<mark style="background: #FFF3A3A6;">Клієнти</mark> – це комп'ютери…
 
Мережі такого типу називають <mark style="background: #FFF3A3A6;">одноранговими мережами (peer-to-peer, P2P)</mark>.

After — three distinct concepts, three colors:

<mark style="background: #FFF3A3A6;">Сервери</mark> – це хости з встановленим програмним забезпеченням…
 
<mark style="background: #ADCCFFA6;">Клієнти</mark> – це комп'ютери…
 
Мережі такого типу називають <mark style="background: #D2B3FFA6;">одноранговими мережами (peer-to-peer, P2P)</mark>.

Сервери = primary term (yellow), Клієнти = its paired/related concept (blue), P2P = a distinct network model (purple). The prose is byte-for-byte unchanged — only the background hex differs. The Переваги / Недоліки lists, being a pros/cons contrast, are good candidates for green/red if you choose to highlight items there.

3. Do / Don’t

Do

  • Preserve every word, every fact, the original language, and the order of content.
  • Reuse existing tags; keep the line-1 tags-line format.
  • Recolor legacy yellow-only highlights by role during a format pass.
  • Make surgical Edits so the diff shows only markup.

Don’t

  • Add an H1, or wrap the tags line in YAML --- frontmatter.
  • Reword, translate, summarize, or “correct” content.
  • Highlight whole sentences or every term.
  • Edit data.json, .obsidian/, or plugin-generated notes (studying/vocabulary/).
  • Invent new callout types or a new highlight palette.

Graph View

Backlinks