The Tukuk-OS Blogging System: How Content Is Written, Stored and Served

From Tukuk-OS Wiki, the free knowledge base.

Not just an article list — the story behind Tukuk-OS’s simple blog system: JSON storage, a Markdown parser, a dynamic sitemap, and steady content standards.

The blog you are reading is not WordPress or an off-the-shelf platform — it was written specifically for Tukuk-OS. That choice saved cost, reduced the attack surface, and let me define exactly the content shape I wanted. Here is how the system works from editing to publishing.

Storage: Honest JSON

Articles live in one JSON file (data/tukuk-os.json) as an array of objects, each with title, slug, author, tags, excerpt, content, createdAt, and updatedAt.

At first I worried about single-file performance, but the number of blog articles (dozens, not hundreds of thousands) is far below the point where it becomes a problem. The server keeps data in memory and writes back on a delay, so reads never wait on disk.

The unexpected advantage: a JSON file can be eyeballed, hand-edited in an emergency, and fed into an existing backup pipeline with no extra database tooling. When my server crashed one night I fixed one record with a text editor in three minutes.

Editing: A Script, Not a Panel

I write articles in special JavaScript files containing arrays of article objects, then run a seed script to insert them into storage. The script adds new articles and updates fields that change — for example, standardising the author name across the archive.

This approach suits me because it works anywhere (including over SSH from a phone), can be reviewed in version control, and requires no admin web panel to secure.

A Small Markdown Parser

When an article page opens, the content passes through renderMarkdown — a function that turns ## into headings, lists into <ul>, bold text into <strong>, plus links, code spans, and paragraphs.

This parser is not full CommonMark, and that is deliberate. It supports the subset I use in writing, produces clean HTML with no stray styles, and is impossible to exploit because it takes content I wrote myself. That one decision removes an entire class of complexity (and risk) that third-party content editors bring.

Publishing and Distribution

Every time the article list grows it appears automatically:

• On the /blog list, newest first.

• In the dynamic XML sitemap (/sitemap.xml) with correct <lastmod>.

• In feeds and other internal links with no extra work.

The sitemap is built dynamically from stored data — not a static file that needs regeneration — so a new article appears in the sitemap within seconds of being saved.

Quality: The 650–850 Word Standard

Every article targets between 650 and 850 words: deep enough to be useful, short enough to finish reading. The seed script counts words and warns if an article falls outside the range.

I also have personal writing rules: one main idea per article, at least three headings, real examples from real projects, and no filler. If I cannot explain something without jargon, it means I have not understood it well enough.

What Makes an Article Ready to Publish

Before saving, every article passes a short checklist. First, does it answer a question real people actually ask? Second, does it contain concrete examples from projects I actually worked on? Third, can a newcomer follow it without prior knowledge? Fourth, is the title honest — does it promise exactly what the piece delivers? Fifth, does it link to at least one other page on this site?

A sixth check happens after the draft is "finished": I read it aloud. Any sentence that makes me stumble while reading is rewritten, because a sentence that is hard to say aloud is usually hard to follow on a screen. This single habit catches more awkward phrasing than any automated tool I have tried.

That checklist takes about ten minutes per article and is why this archive stays consistent even as my writing style evolves. The rules are deliberately small — the moment a quality process becomes bureaucratic, people (including me) start skipping it.

What Comes Next

The roadmap includes an official RSS feed, smarter ranking for the blog list, and possibly layered categories. But the core principles will stay: content is data, storage must be easy to recover, and the system must stay small until it genuinely needs to grow.

See also

• Tukuk-OS Is Alive: Reflections From Broken Laptop to Working Search Engine
• What Is Tukuk-OS? What This Search Engine Actually Does
• Tukuk-OS Complete Feature Tour: From Web Search to Space Data
• Image and Video Search in Tukuk-OS: How It Actually Works
• Tukuk-OS Automation: Backups, Watchdogs and Self-Monitoring
• The Tukuk-OS Contact Form: From Click to Your Inbox