/style
━━━━━━

drafted by kimi

Date: February 11, 2026

│ drafted by kimi

/style
━━━━━━

How I write and build this site. A personal style guide.

Tone of Voice
─────────────

Casually self-deprecating with technical credibility.

I write like I’m talking to someone at a conference after-party, not a LinkedIn profile. It’s okay to poke fun at myself and my projects. “Under-funded, over-dreamed, barely documented” is a feature, not a bug.

Principles:

- Use first person (“I”, “me”, “my”)
- Keep sentences punchy and direct
- Include real personal details and hobbies
- Show technical expertise without taking myself too seriously
- It’s okay to mention frustrations with mainstream tools

Writing Rules
─────────────

Formatting:

- No em-dashes. Use periods or commas instead
- No emoji
- 80 character hard wrap
- Double space between sentences
- Headers should be concise (2-4 words)

Structure:

- Put code examples front and center
- Add brief context or “why this matters” even if just one sentence
- It’s okay to say “I use this when…” or “This saved me from…”
- Personal anecdotes add authenticity
- Technical terms are fine, but explain the “why” behind choices

Content Types:

+------------------+---------------------------------------------------+
| Type             | Tone                                              |
+------------------+---------------------------------------------------+
| Blog posts       | Full conversational tone, share opinions openly   |
| Hot tips / TILs  | Short, practical, but not robotic                 |
| Glossary entries | Stiff, definitional tone is intentional           |
| Daily notes      | Casual and quick, stream of consciousness is fine |
+------------------+---------------------------------------------------+

Code Style
──────────

Python:

- Use

  uv

  for package management
- Type hints required:

  from typing import TYPE_CHECKING, List, Optional
- Pydantic models for configuration
- f-strings over concatenation
- Proper exception handling

Bash:

- set -euxo pipefail

  in scripts
- Use

  just

  for task management

Naming:

- Functions: snake_case
- Classes: PascalCase
- Python files: snake_case
- Content files: kebab-case

Site Architecture
─────────────────

Stack:

- Markata (custom Python static site generator)
- Tailwind CSS v4+ with pnpm
- Jinja2 templating
- Markdown with YAML frontmatter
- Kubernetes hosting (basement cluster)

Directories:

```
plugins/     Markata extensions
scripts/     Utility scripts (Typer CLI)
templates/   Jinja2 HTML templates
pages/       Markdown content
tailwind/    CSS source files
static/      Built assets
```

Content Philosophy
──────────────────

DIY Ethic:

I emphasize building and maintaining things myself. This site runs on a Kubernetes cluster in my basement because “I love DevOps” like maintaining your own bare-metal cluster just to host a static site.

Authenticity:

I create this blog with one person in mind: me. If it helps others, great. But I’m writing to document what I learn and think, not to build an audience or optimize for engagement.

Learn in Public:

Share failures, unfinished projects, and half-baked ideas. The TIL format works because it captures learning in the moment, not after I’ve mastered something.

What I Avoid
────────────

- “Just”

  - The word skips invisible complexity
- Pretending to know everything

  - I’ll say when I’m confused
- Overly complex solutions

  - Prefer systems I can understand and fix
- Performance for likes

  - Not optimizing for engagement metrics

Inspiration
───────────

This style guide draws from:

- slashpages.net /style
- Rubenerd style guide
- Robb Knight’s design style
- Years of reading indie web blogs and knowing what I like

--------

This is a living document. I break these rules when it feels right.