All posts

Markdown for Blogging: The Standard Format for Static Site Generators

Markdown is the de facto standard for blogging platforms and static site generators. Learn how Jekyll, Hugo, Next.js, Astro, and Ghost use markdown, the role of frontmatter, and how to structure blog posts for maximum portability.

Markdown for Blogging: The Standard Format for Static Site Generators

If you blog, you're using markdown—or you should be.

Every major blogging platform and static site generator (SSG) has standardized on markdown:

  • Jekyll — GitHub Pages' engine. All posts are .md files.
  • Hugo — Fast SSG written in Go. Markdown native.
  • Next.js — React framework with MDX (markdown + JSX components).
  • Astro — Modern SSG with built-in markdown support.
  • Ghost — Blogging platform. Uses markdown for post creation.
  • 11ty — Lightweight SSG. First-class markdown support.
  • Gatsby — React-based static site generator. Markdown via plugins.

Why? Because markdown is:

  • Version control friendly — Plain text, diffs show exactly what changed.
  • Platform agnostic — Switch between Jekyll and Hugo without re-formatting.
  • Human readable — Even the raw .md file is readable without rendering.
  • Lightweight — No dependencies, no database, just text files.

If you're building a blog in 2026, markdown is the default choice.

How Blogging Platforms Use Markdown

Let's walk through how a typical blogging setup works.

The File Structure

content/
├── blog/
│   ├── how-to-organize-markdown-files-mac.md
│   ├── plain-text-movement.md
│   ├── markdown-for-github.md
│   └── one-time-purchase-apps.md
├── pages/
│   ├── about.md
│   └── contact.md
└── projects/
    ├── project-a.md
    └── project-b.md

Each .md file is a post or page. The SSG processes these files and generates HTML.

Build Process

The SSG reads:

  1. Frontmatter — Metadata at the top of the file (title, date, author)
  2. Content — The actual markdown below the frontmatter
  3. File path — Determines the URL slug

It then:

  1. Renders markdown to HTML
  2. Applies a template (layout, styling, navigation)
  3. Generates static HTML files
  4. Deploys to a web server

No database. No dynamic requests. Just HTML files. This is why SSGs are fast, secure, and easy to host.

Frontmatter: The Metadata Layer

Frontmatter is metadata written at the top of a markdown file, delimited by ---.

---
title: 'How to Organize Markdown Files on macOS'
date: '2026-02-22'
author: Ryan McDonald
tags: [markdown, macos, organization]
description: >
  Master macOS organization for markdown files. Learn folder structures, naming conventions, and Finder tags.
---

# How to Organize Markdown Files on macOS

Content starts here...

The frontmatter is YAML (or sometimes TOML or JSON, depending on the SSG). It's structured, parseable, and human-readable.

Standard Frontmatter Fields

Title: The post title (appears in page title, RSS feeds, search results).

Date: Publication date, usually in ISO format (YYYY-MM-DD). SSGs use this to sort posts, create archives, and manage scheduling.

Author: Who wrote the post. Useful for multi-author blogs.

Tags or Categories: Content classification. Used to generate tag pages and group related posts.

Description: A short summary (SEO description, RSS feed, social media preview).

Slug: The URL path. If omitted, the SSG generates it from the filename.

Draft or Published: Whether to include the post in the live site. Draft posts are generated for preview but excluded from the final build.

Image: Featured image URL. Used in social media previews, RSS feeds, and as a post thumbnail.

Some SSGs support custom fields. You might add:

---
title: 'Post Title'
date: '2026-02-21'
canonicalUrl: 'https://example.com/post'
redirectUrl: '/old-slug'
---

This lets you:

  • Set canonical URLs for republished content
  • Handle redirects from old URLs
  • Add custom metadata your template uses

Structure for Maximum Portability

Write your markdown with portability in mind. You might switch from Jekyll to Hugo, or from Ghost to Next.js. If your markdown is well-structured, the transition is painless.

Use Semantic Headings

# Main Title (H1)

This is the post introduction.

## Section 1

Content for section 1.

### Subsection 1.1

More details.

## Section 2

More content.

Use H1 only once, at the top. Headings should reflect document structure, not styling. This:

  • Improves accessibility (screen readers navigate via headings)
  • Makes your markdown more readable
  • Lets SSGs auto-generate table of contents

Use Markdown Lists

Key points:

- Markdown is portable
- Plain text lasts forever
- Works with every SSG

Numbered list:

1. Create the file
2. Write the post
3. Commit and deploy

Don't use raw HTML (except when markdown can't express it). Stick to markdown syntax. It's more readable and more portable.

Links and Images

Use relative paths when possible:

Read more: [Our markdown guide](/blog/plain-text-movement)

![Screenshot](/images/openmark-screenshot.png)

Absolute URLs work too, but relative links make it easier to move your site or test locally.

Code Blocks

Specify language for syntax highlighting:

function greet(name) {
  return `Hello, ${name}!`;
}

def greet(name):
    return f"Hello, {name}!"

MDX: Markdown + Components

Modern SSGs like Next.js and Astro support MDX—markdown files that can include React components.

---
title: 'Building with React'
---

# Building with React

Here's a markdown paragraph.

<Alert type="warning">
  This is a React component inside markdown.
</Alert>

More markdown after the component.

<CodeExample language="jsx">
  export default function App() {
    return <h1>Hello</h1>
  }
</CodeExample>

This gives you the best of both worlds:

  • Write in markdown (fast, readable, portable)
  • Use components when you need interactivity (buttons, forms, embeds)

Most MDX content remains portable. If you move from Next.js to Astro, the markdown parts are fine; you might need to adapt custom components, but the content itself is safe.

How to Structure a Blog Post in Markdown

Here's a template for a well-structured blog post:

---
title: 'Your Post Title'
date: '2026-02-25'
description: >
  A compelling one-line description for SEO and social sharing.
author: Your Name
tags: [tag1, tag2, tag3]
---

# Your Post Title

A 2-3 sentence introduction that hooks the reader. What problem does this post solve? Why should they read it?

---

## First Major Section

Content here. Use markdown for emphasis, links, and lists.

### Subsection

More detailed content.

---

## Second Major Section

Use `---` section dividers to break up the post visually. Helps with readability.

### Another Subsection

Details and examples.

---

## Conclusion

Summarize your main points. Suggest next steps or related reading.

---

[Link to related resource](https://example.com)

This structure:

  • Clear metadata (frontmatter)
  • Compelling intro
  • Logical sections with headings
  • Section dividers for visual breaks
  • Conclusion and calls-to-action

Tips for Blogging in Markdown

Write in a markdown editor first. GitHub's web interface or a text editor is fine, but a proper markdown editor like OpenMark gives you live preview, better editing experience, and fewer typos.

Use consistent frontmatter. Decide on your required fields, optional fields, and field naming. Make a template. Every post should follow the same structure.

Commit to version control. Git + GitHub makes it easy to track post history, collaborate, and manage drafts.

Use draft mode. Set published: false or draft: true in frontmatter for posts you're working on. The SSG won't include them in the live site.

Test locally. Run your SSG locally (npm run dev for Next.js, hugo server for Hugo) to preview the post before publishing.

Avoid platform-specific markup. Don't use Notion-style tags or Ghost-specific syntax. Stick to standard markdown. You want portability.

Switching SSGs

If you decide to switch from Jekyll to Hugo, or from Ghost to Next.js, your markdown files migrate cleanly:

  1. Export all posts as .md files (every SSG can do this)
  2. Update frontmatter fields if the new SSG uses different names
  3. Regenerate the site with the new SSG
  4. Upload to the new host

Your content is never trapped. This is the power of markdown.

The Future of Blogging

Blogging with markdown and SSGs is the most future-proof approach. Your posts are version-controlled, portable, and readable 50 years from now. They're not locked into a proprietary platform or database.

This is why it's the de facto standard.

Ready to blog with markdown? Write your posts in OpenMark—a native macOS markdown editor with live preview, perfect for crafting blog content locally before committing to your SSG.

Download OpenMark for $9.99 on the Mac App Store.