Markdown Blog Workflow: From Frontmatter to GitHub Actions Deployment

The most important part of a blog is not the editor. It is the workflow. If writing, reviewing, publishing, and revising a post feels heavy, the habit disappears. Markdown files and Git history keep the workflow small enough to repeat.

The goal is simple: adding one post should create a page, missing metadata should fail before deployment, and the published HTML should be easy for search engines and people to read.

Why Markdown

Markdown is useful less for its power and more for its constraints. A technical note usually needs headings, paragraphs, lists, code blocks, and links. That is enough for the first version of a small technical blog.

The second advantage is history. In a CMS, it is easy to see the final article and lose the reasoning behind edits. In a repository, posts can be reviewed like code. A changed title, a refined description, or a cleaned-up tag list leaves a trace.

Each post carries frontmatter that turns the article into structured content:

title: used in browser titles and search snippets
description: used in meta descriptions and listing cards
lang: used for localized routes and language alternates
translationKey: used to connect translations
tags: used for list filters, RSS categories, and structured data
publishedAt, updatedAt: used for publishing and modification dates

People write the article, but the build system turns this metadata into site structure.

Validate before publishing

The weakness of Markdown is that it is permissive. A file can look like a post while missing information the site needs. That is why the workflow needs validation.

Astro Content Collections can define a schema for posts. Title, description, language, publication date, and tags are checked during the build. It is cheaper to catch a bad language code before deployment than to let a search engine index the wrong canonical or alternate URL.

Internationalization follows the same rule. Posts with the same translationKey can point to each other through alternate links. A crawler or reader on the Korean page can discover the English version, and the reverse works the same way.

Publishing flow

The current flow is intentionally plain:

Add a Markdown file under src/content/posts/{ko,en}.
Validate frontmatter against the content schema.
Let Astro generate article pages, listings, sitemap, and RSS.
Let GitHub Actions publish the static output to GitHub Pages.

No running server is needed to publish a new post. When the repository changes, static HTML is regenerated. That keeps the cost model simple even if traffic grows.

What can change later

Using Markdown does not mean the site is locked into a tiny blog forever. Static search can be added later. A headless CMS can be introduced if editing inside Git becomes too slow. The important part is to avoid paying for those capabilities before the need is real.

So the decision is not “Markdown is always enough.” The decision is: for the current problem, Markdown plus static generation gives the best balance of clarity, cost, and future flexibility.

A Markdown workflow for publishing static blog posts