The rest of this site is three files: index.html, styles.css, script.js. No build\nstep, no framework, no node_modules in sight. I liked it that way, and I did not want\na blog to be the thing that dragged in a bundler.
So the constraint I set myself was: adding a post must not make the site heavier for\nthe reader, and must not make the repository harder to understand.
\nEvery post is a Markdown file in content/blog/. A Node script reads them at build\ntime and writes plain HTML into blog/. The browser receives no Markdown, no parser,\nand no JavaScript that is not already on the homepage.
content/blog/my-post.md → blog/my-post/index.html\n → blog/index.html\n → blog/tags/<tag>/index.html\n → blog/rss.xml, blog/feed.json\n → sitemap.xml, robots.txtThe generated directory is gitignored. It is rebuilt in CI on every push, immediately\nbefore the GitHub Pages artifact is uploaded — which is exactly how the résumé PDF on\nthe homepage already worked. I did not invent a pipeline; I added a step to one that\nexisted.
\nEach file opens with a small metadata block:
\n---\ntitle: Ordering is a local property\ndescription: Message ordering is not something a broker hands you globally.\ndate: 2026-08-05\nupdated: 2026-08-09\ntype: article\ntags: [Kafka, distributed-systems]\nfeatured: true\ndraft: false\n---type is the interesting field. I write four different kinds of thing — long articles,\nshort notes, reactions to something I read, and build logs like this one — and my first\ninstinct was four separate systems. That was wrong. They differ in presentation, not\nin structure: same title, same date, same body. One content model with a type field\ndoes the whole job, and the templates decide that a note does not need a reading-time\nbadge.
One dependency. marked, for Markdown. It has no transitive dependencies and it\nruns only at build time. I parse the frontmatter myself — it is eight known keys, and\npulling a full YAML engine in to read eight known keys is not a trade I wanted.
Headings become anchors. Every ## gets a stable, Unicode-safe id and a permalink,\nso you can link someone to the paragraph that matters instead of to the top of a\ntwo-thousand-word page.
Direction is per block, not per page. I write in English and in Persian, sometimes\nin the same paragraph. The build tags each block with the direction that most of its\ncharacters actually want, rather than trusting the first-strong-character rule that\ndir="auto" uses — which gets a Persian sentence wrong the moment it opens with an\nEnglish technical term.
Drafts are not built. A post with draft: true produces no file at all. There is no\npage to leak, no URL to guess, and nothing in the sitemap or feeds. Locally I run:
BLOG_DRAFTS=1 node tools/blog/build.mjswhich is the only way a draft ever becomes HTML.
\nSyntax highlighting, for now. Every option costs either a large build-time grammar\nbundle or client-side JavaScript, and monospaced code with real contrast and generous\nline height reads fine. If I start posting more code than prose I will revisit it — the\nhook is a single function in tools/blog/markdown.mjs.
Comments, analytics, a newsletter, and search. There are a handful of posts here. A\nsearch box would be decoration.
\nPagination. At some point a chronological index gets silly, but "some point" is a long\nway from here, and building for it now would mean guessing at a problem I do not have.
\n# 1. write\n$EDITOR content/blog/something-i-learned.md\n\n# 2. preview\nnode tools/blog/build.mjs && python -m http.server 8123\n\n# 3. publish\ngit add content/blog/something-i-learned.md && git commit && git pushStep three triggers CI, which rebuilds the site and the PDF and deploys. There is no\nstep four, and there is no admin panel to log into — which was the entire objective.
\n", "date_published": "2026-08-05T00:00:00.000Z", "tags": [ "meta", "static-sites", "tooling" ], "language": "en", "_blog": { "type": "build", "type_label": "Build log", "path": "/blog/how-this-blog-is-built/", "reading_minutes": 3 } }, { "id": "https://mojtaba.tech/blog/fa-idempotency/", "url": "https://mojtaba.tech/blog/fa-idempotency/", "title": "یادداشتی دربارهٔ idempotency", "summary": "چرا در سیستمهای پیاممحور، «دوباره اجرا شدن» یک استثنا نیست و باید از ابتدا برایش طراحی کنیم.", "content_html": "هر سیستم پیاممحوری که با تضمین at-least-once کار میکند، دیر یا زود یک پیام را دوبار\nتحویل میدهد. این باگ نیست؛ بخشی از قرارداد است. اگر broker مطمئن نباشد که پیام را\nپردازش کردهاید، دوباره میفرستد — و این دقیقاً همان رفتاری است که از او خواستهایم.
\nمشکل وقتی جدی میشود که handler ما فرض کرده باشد هر پیام دقیقاً یک بار میآید. آن وقت\nیک retry ساده میتواند موجودی انبار را دوبار کم کند یا برای یک سفارش دو بار فاکتور\nبزند.
راهحل معمولاً پیچیده نیست. کافی است هر پیام شناسهٔ یکتا داشته باشد و پیش از اعمال،\nبررسی کنیم که قبلاً آن را دیدهایم یا نه:
\nif (await _processed.ExistsAsync(message.Id))\n{\n return HandlerResult.Skip;\n}\n\nawait using var tx = await _db.BeginTransactionAsync();\nawait _inventory.DecreaseAsync(message.Sku, message.Quantity);\nawait _processed.AddAsync(message.Id);\nawait tx.CommitAsync();نکتهٔ ظریف این است که ثبت شناسه و خودِ تغییر وضعیت باید در یک تراکنش انجام شوند. اگر\nآنها را جدا کنیم، باز هم به همان مشکل برمیگردیم — فقط با پنجرهٔ زمانی کوچکتری که\nپیدا کردنش سختتر است.
\nThe short version in English: at-least-once delivery makes idempotency a requirement,\nnot an optimisation. Design for the duplicate on day one and you never have to hunt it\ndown at two in the morning.
\n", "date_published": "2026-07-25T00:00:00.000Z", "tags": [ "Kafka", "event-driven", "Persian" ], "language": "fa", "_blog": { "type": "note", "type_label": "Note", "path": "/blog/fa-idempotency/", "reading_minutes": 1 } } ] }