Software

Markdown as a Technical Notebook

Using Markdown as a simple format for documenting technical work.

September 26, 2026

One of the reasons I like Markdown is that it stays out of the way.

A technical note can contain normal prose, code, diagrams, tables, links, and images without requiring a complicated editor.

Code

For example, a small Python function:

def calculate_area(width: float, height: float) -> float:
    return width * height


area = calculate_area(10, 5)
print(area)

Or a SQL query:

SELECT
    project,
    status,
    updated_at
FROM projects
WHERE status = 'active'
ORDER BY updated_at DESC;

Or a shell command:

find src/content/notes -name "*.md" -type f

Architecture diagrams

Diagrams are particularly useful when documenting systems.

flowchart TD
    User[User] --> Browser
    Browser --> Astro[Astro Static Site]
    Astro --> Firebase[Firebase Hosting]
    Firebase --> Internet