The minimum upgrade path from blog to technology platform (1): from 'file pile' to 'thematic'

Writing Statement This article is based on the author’s practical experience in upgrading his personal blog from a simple time stream to a complete home page with topics, tags and a platform. It does not involve the interpretation of external technical articles. All opinions come from the process of pitfalls, trial and error, and reconstruction.

---

Beginning: When your readers say “You have a lot of articles, but I can’t find what I want to read.”

Three months ago, my blog had over 30 posts.

Technically it works well - Astro builds are fast, GitHub Pages hosting is stable, RSS feeds work fine. But a reader said something in a private message that made me stop my update plan:

“You have written a lot of articles, but I can only read them in chronological order. It is difficult to quickly find the topics I care about.”

This sentence points out a fact that I deliberately avoid: **My blog is essentially a “pile of files”, with Markdown files laid out on the homepage in reverse chronological order. **

What readers want are “articles about RAG”, “deployment-related practices”, and “content suitable for introductory AI engineering”. But all I gave them were “articles from December 2025” and “articles from January 2026”.

This is not a technical issue, but a backwards approach to content organization.

---

First Principles: The Essential Difference Between Blogs vs. Technology Platforms

To understand the direction of upgrading, first look at the current situation.

The default structure of a traditional blog

Most blogging tools (WordPress, Hexo, Hugo default themes) instill in authors an implicit assumption that time is the most important organizational dimension.

• Home page = list of articles in reverse chronological order
• Classification = simple tag cloud
• Navigation = About page + Friendly links

This structure is perfectly fine when there are less than 20 articles, a single topic, and low update frequency. Readers can finish it by turning a few pages, and the author himself can remember what he wrote in each article.

Core Features of Technology Platforms

But when you start to cover multiple technical fields (such as AI engineering, back-end architecture, data processing), the number of articles exceeds 50, and the readership changes from “getting to know you as a person” to “looking for specific technical content”, the time dimension is no longer the best entry point.

The core feature of the technology platform is to regard Topic as the first organizational dimension:

Dimensions	traditional blog	Technology platform
primary entrance	Latest articles	Topic list
Discovery method	time browsing	Topic exploration
content relationship	Linear (sequentially)	mesh (associative)
reader path	”Just take a look"	"Come with questions”

Key Insight: Upgrading your blog is not about changing to a beautiful theme, but about redesigning the way content is related.

---

Practical judgment: Do you really need to upgrade?

Not everyone needs thematization. Before taking action, ask yourself three questions:

Question 1: Does your article have “inter-period correlation”?

Open your list of articles and see if you can find a pattern like this:

• The 5th article introduces a certain concept, the 23rd article goes into the implementation details, and the 41st article shares the production pitfalls.
• If these three articles are scattered on different pages according to time, it will be difficult for readers to find that they are continuations of the same theme.

**If the answer is “yes”, you need to thematize. **

Question 2: Do readers repeatedly ask “Are there any articles about XXX”?

This is the most direct signal. When your reply changes from “Yes, I’ll send you the link” to “I’ll look for it… there seem to be several articles, but scattered at different times”, it means that your content organization can no longer keep up with the search needs of readers.

Question 3: Do you yourself often forget what you have written?

The author himself cannot remember the structure of the content library, and the reader’s experience will only be worse. This is a clear sign that content debt has accumulated to a breaking point.

My judgment criteria: When the answer to any two questions above is “yes”, it is the time to start the upgrade.

---

Minimum viable solution: three-tier architecture for thematic upgrades

No need to rewrite the entire site. My practical path can be summarized as “three-level progression”:

The first level: define the topic (Topic)

Topics are aggregation dimensions higher than tags, and usually correspond to the technical field that you continue to focus on and write about.

On my blog, topics include:

• AI engineering practice
• backend engineering
• Agent system construction
• SFT data engineering

Key Design Principles:

1. The number of topics should be limited to 5-10 - too few and there will be no distinction, too many and the navigation value will be lost.
2. Each topic should have a clear boundary description - allowing readers to determine at a glance whether it is what they are looking for.
3. The topic is the author’s content commitment - “I will continue to produce in this field”

Second level: establishing content attribution

Each article must belong to a topic. This is not a taxonomy show-off, but a definite “entry” for readers.

In Astro’s Content Collections, I use the topic field to implement:

---
title: "RAG system"
topic: ai-engineering-delivery  # "AI Engineering Practice"Topic
tags:
  - rag
  - hallucination
  - production
---

The third level: design thematic entry page

Each topic requires an independent landing page, including:

• Introduction to the topic (what is this field and why is it important)
• List of articles under this topic (sorted by time or series)
• Related guides/recommended reading (if any)
• Subtopic navigation (if the topic is large, it can be subdivided)

This is a key transition from “time flow” to “topic space” - readers no longer turn pages, but explore within the topic.

---

Technical Implementation: Minimal Configuration of Astro Content Collections

If you’re also using Astro, here’s the minimal code structure to implement theming:

1. Define content collections

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    topic: z.string(),  // field
    tags: z.array(z.string()).default([]),
    description: z.string(),
  }),
});

const topics = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    order: z.number().optional(),
    featured: z.boolean().default(false),
  }),
});

2. Create thematic data files

# src/content/topics/ai-engineering-delivery.md
---
title: AI Engineering Practice
description: LLMfrom prototype to productionengineeringpath
order: 1
featured: true
---

AI engineering practice focuses on systematically integrating LLM capabilities into software engineering...

3. Build a topic index page

---
// src/pages/topics/[slug].astro
import { getCollection } from 'astro:content';

const topic = Astro.props.topic;
const posts = await getCollection('blog',
  post => post.data.topic === topic.id
);
---

<h1>{topic.data.title}</h1>
<p>{topic.data.description}</p>

{posts.map(post => (
  <article>
    <a href={`/blog/${post.slug}`}>{post.data.title}</a>
    <p>{post.data.description}</p>
  </article>
))}

This is all core technology. There is no need for a complex database or CMS, just changing the organization of Markdown from “a bunch of files” to “thematically attributed content”.

---

Common resistance and responses

”My content is too complex and difficult to classify”

This is a matter of classification granularity, not a matter of whether to classify. Try this decision tree:

• First, divide it by “technical field” (front-end/back-end/AI/operation and maintenance)
• If there are more than 15 articles in a certain field, subdivide it (for example, AI is divided into “RAG/Agent/Fine-tuning”)
• If an article really spans multiple fields, choose the most relevant attribution and don’t get hung up.

”Once the topic is decided, it is difficult to change it.”

Topics are alive. What I do is:

1. Start with broad topics (such as “Backend Engineering”)
2. When a topic exceeds 20 articles, consider splitting it
3. Use redirects to handle URL changes without readers being aware of them

”It’s too much work to migrate old articles”

Don’t migrate all at once. My path:

1. Add topic field to new article
2. Take time to add attribution to 5 old articles every week
3. Articles without topic are still displayed in the “All articles” list

---

Conclusion: Thematicization is the “foundation” of the content platform

After completing the thematic upgrade, my blog homepage became like this:

• Special Entrance (8 core technology areas)
• Latest Article (Keep time stream, but only one of the entrances)
• Recommended Reading (a curated mix across topics)

The changes in reader feedback are substantial:

• “I want to learn RAG” → Go directly to the AI ​​engineering topic
• “Your deployment articles” → There are 6 related articles in the back-end engineering topic
• “Suitable for beginners” → The guide series in the topic are sorted by difficulty

This upgrade made me understand a truth: The value of blog content lies not only in the quality of a single article, but also in whether the relationship between the content can be discovered and utilized by readers.

Thematization is not the end point, but the infrastructure for all subsequent upgrades (tag system, search, recommended reading).

In the next article, I will share how to design a tag system to avoid the two most common pitfalls of “tag flooding” and “categorization confusion.”

---

Series of articles

1. From “file pile” to “thematic” ← This article
2. The Art of Designing Tags and Topics—How to Build a Content Taxonomy Without Confusion (To be Released)
3. Build a platform-based homepage - allowing readers to go from “seeing” to “discovering” (to be released)
4. Astro + Content Collections Practical Guide (to be released)

---

Reference resources

• Source code of this blog: GitHub repository
• Astro Content Collections documentation: https://docs.astro.build/en/guides/content-collections/