mel.rocks

Getting Started with Org-Mode Blogging

December 10, 2025
emacs org-mode workflow tutorial

Introduction

This post documents various org-mode snippets and processes for producing the html you see on this screen.

Why Org-Mode?

Org-mode offers several advantages for blogging:

Plain Text Forever

Everything is stored as plain text files. No database, no proprietary formats, just .org files that are readable on almost anything.

Powerful Features Built-In
  • Easy linking between posts
  • Code syntax highlighting
  • Tables and lists
  • Export to multiple formats (HTML, PDF, LaTeX)
  • TODO items and timestamps
Emacs Integration

Emacs is lisp machine that's good at editing text. Wiring in code is ok.

The Setup

The basic structure is simple: 

mel.rocks/
├── org/          # Source files
│   ├── posts/    # Blog posts
│   └── pages/    # Static pages
├── public/       # Generated HTML
└── publish.el    # Configuration

Writing Posts

Creating a new post is as simple as: 

#<buffer 2025-12-10-my-new-post.org>

Then add the metadata: 

#+TITLE: My New Post
#+AUTHOR: Your Name
#+DATE: <2025-12-10 Tue>
#+DESCRIPTION: A brief description

Your content goes here...

Publishing Workflow

The entire publishing process is handled by a single command: 

make build  # Generate HTML
make serve  # Preview locally
make deploy # Push to Cloudflare

Code Examples

Org-mode handles code blocks beautifully. Here's a Python example: 

def hello_world():
    """A simple greeting function."""
    return "Hello from org-mode!"

print(hello_world())

And some JavaScript: 

const greet = (name) => {
    return `Hello, ${name}!`;
};

console.log(greet("World"));

Tables

org-mode tables are cool. you define them as plain text like so 

| Feature     | Markdown | Org-Mode  |
|-------------+----------+-----------|
| Tables      | Limited  | Excellent |
| Code Blocks | Good     | Excellent |
| Linking     | Basic    | Advanced  |
| Export      | HTML     | Multiple  |

Seems simple enough but when you interact with them in emacs it balances everything for you and allows for excel like functionality.

When you input the same table as part of the doc the publishing tool renders it like so as html:

Feature Markdown Org-Mode
Tables Limited Excellent
Code Blocks Good Excellent
Linking Basic Advanced
Export HTML Multiple

Images and Media

Adding images is straightforward: 

[[file:../img/screenshot.png]]

You can also add captions and attributes: 

#+CAPTION: My awesome screenshot
#+ATTR_HTML: :width 600px :alt Screenshot description
[[file:../img/screenshot.png]]

Deployment to Cloudflare Pages

Cloudflare Pages makes hosting simple and free:

  1. Push your code to GitHub
  2. Connect Cloudflare Pages to your repository
  3. Set build command: emacs --batch -q --load publish.el
  4. Set output directory: public

Every push to main triggers a new deployment automatically.

Tips and Tricks

Use Snippets

Create yasnippet templates for common post formats: 

# -*- mode: snippet -*-
# name: blogpost
# key: blog
# --
#+TITLE: ${1:Title}
#+AUTHOR: Mel Gray
#+DATE: `(format-time-string "<%Y-%m-%d %a>")`
#+DESCRIPTION: ${2:Description}
#+KEYWORDS: ${3:keywords}

$0

Preview While Writing

Use org-preview-html-mode or run a local server: 

make serve &  # Run in background
make watch    # Auto-rebuild on changes

Organize with Tags

Use tags for categorization: 

**My Post Title :emacs:programming:tutorial:

Conclusion

This setup gives me everything I need:

  • Simple writing experience in Emacs
  • Version control with Git
  • Complete control over the output