Insights

Personal knowledge vault — notes, tips, tricks, and short investigations across programming, databases, machine learning, infrastructure, and tools.

Maintained as an Obsidian vault and published as an mdBook site.

For the canonical, fully-linked landing page see doc/README.md. This top-level README covers repo-level concerns: how the vault is built, what tooling lives alongside it, and how to publish.

What's in here

Path	Purpose
doc/	The vault. ~620 articles in 132 directories. Structured per plan.md §3.
doc/SUMMARY.md	mdBook table of contents (auto-generated by inventory/build_summary.py).
published/	Cleaned-up articles published externally (yarenty.blogspot.com).
book/	mdBook output (gitignored).
inventory/	All re-runnable maintenance scripts + audit reports (see below).
plan.md	Master reorganization plan and live progress tracker.
book.toml	mdBook configuration.
mdbook-admonish.css, mermaid.min.js, mermaid-init.js	mdBook preprocessor assets.
Apple Notes/, resources/	Auxiliary collections (not part of the published book).

Investigation procedure

When I add a new tool or technology to this vault I follow a fixed loop:

1. Investigate — 5 minutes copying source material into a new file.
2. Summarise — 5 minutes writing summary + insight + keywords following the article template.
3. Cross-link — add Obsidian wikilinks to related articles already in the vault.
4. Close the tab — the whole point of the vault is to empty the browser.

For tools specifically: install instructions, plugin/extension setup, and a tip section live alongside.

Article template

Every non-landing article has YAML frontmatter and the same section layout:

---
title: <Human-readable title>main_link: <canonical URL — official site / repo / paper>keywords: [kw1, kw2, kw3] # 3-10 short tagsstatus: draft | reviewed
---

# <Title>**Main link:** <main_link>
## Summary — 2-5 sentences. What is it, who made it, what it does.## Insight — Why care, when/where to reach for it, gotchas.## Similar / related topics## Internal links — [[wikilinks]] to related vault articles.## Keywords — `#tag` cloud## TODO — Per-file outstanding work## References / raw notes — Original verbatim content.

The full template plus the per-article rewrite checklist lives in plan.md §2 + §8.

Featured published articles

• 2024-02-04 — Datafusion Comet → https://yarenty.blogspot.com/2024/02/datafusion-comet.html

Building the mdBook site

mdbook serve --open # live preview
mdbook build # produce static site under book/

The build pipeline uses two preprocessors: mdbook-mermaid (for ```mermaid diagrams) and mdbook-admonish (for callout boxes). If you ever see "Incompatible assets installed" re-run:

mdbook-admonish install

PDF rendering is commented out in book.toml; uncomment to enable.

Conventions

• Every directory has exactly one README.md as its landing page.
• File names: lower_snake_case.md, no spaces, no mixed case (except literal README.md and SUMMARY.md).
• Internal cross-links use Obsidian wikilinks [[…]]; SUMMARY.md keeps standard [text](path) for mdBook compatibility.
• Asset folders (img/, res/, res_pptx/, papers/) hold non-.md files and are excluded from README generation and SUMMARY.

Status

All eight phases of the reorganization are complete (P1–P7); see plan.md for the detailed log. Per-article quality polish is ongoing — articles still tagged status: draft carry per-file TODO lists describing what's left to write.