← Pablo Murad

Build a website with Org mode and Emacs

A complete, step-by-step guide to building a static website with Org mode and Emacs alone: writing pages in Org, a build script with ox-publish, a blog index that updates itself, styles, code highlighting, previewing, deploying and fixing the usual errors.

A code window titled hello-world.org on a lilac background, showing an Org file with a title, a date and a description, a heading "Why this site exists" with bold, italic and verbatim text, and a heading "A bit of code" with a Python source block
Contents

Most website tools ask you to learn a framework, a template language and a build system before you write your first sentence. Org mode asks for much less. You write plain text files in Emacs, and Emacs turns them into HTML. No Node, no Ruby, no Go, no database. The tool that does the work, ox-publish, has shipped with Org for years, and Org ships with Emacs.

This guide builds a small but complete site from scratch: a home page, an about page, a blog with an index that updates itself, a stylesheet, images, highlighted code, a one-command build, a local preview and a deploy. Every step explains what it does and why, so you can bend it to your own taste afterwards.

What Org mode is #

Org mode is a major mode for Emacs, created by Carsten Dominik in 2003 and part of Emacs itself since version 22. People use it for notes, to-do lists, agendas, spreadsheets, literate programming and writing. Underneath all of that, an Org file is just text with a light markup, a bit like Markdown, but with a lot more built in.

The Org mode logo: a teal unicorn head with a red and brown mane and a golden horn, drawn in a simple cartoon style

The part that matters here is the exporter. Org can turn the same file into HTML, LaTeX, PDF, ODT, Markdown and plain text. On top of the exporter sits the publishing system, ox-publish, which exports a whole folder of files at once, copies images and stylesheets along, and keeps track of what changed. That's a static site generator, already installed.

Real sites run on it. Worg, the community wiki of the Org project, is written in Org files and published with this same machinery.

The Worg home page, titled Hello Worg, the Org-Mode Community, with an introduction explaining that Worg is written by volunteers, that its source files are written in Org, and the Org unicorn in the bottom corner

What you need #

  • Emacs, any recent version. Org comes with it.
  • A terminal, to run the build.
  • Python 3 or any small web server, only to preview the site locally.
  • Somewhere to host the result later: your own server, or a static host like GitHub Pages, Codeberg Pages or SourceHut pages.

You don't need to be an Emacs expert. You'll edit a few text files and run one command.

A crash course in Org markup #

If you've never written Org, this is enough to build a site. Headings start with stars, and more stars mean a deeper level:

* A top heading
** A sub-heading
*** And another level

Inline formatting:

  • *bold*, /italic/, _underlined_ and +struck through+
  • =verbatim= and ~code~ for monospace text

Links and images use double brackets. A link to a file that is an image becomes an image on the page:

[[https://orgmode.org][The Org website]]
[[file:about.org][About me]]
[[file:img/photo.jpg]]

Lists, tables, quotes and code blocks:

- an item
- another item
1. a numbered item

| Name | Language |
|------+----------|
| Org  | Elisp    |

#+BEGIN_QUOTE
Plain text lasts.
#+END_QUOTE

#+BEGIN_SRC python
print("Hello")
#+END_SRC

And the lines starting with #+ at the top of a file are settings. #+TITLE becomes the page title, #+DATE the date and #+DESCRIPTION the meta description.

One handy detail: a link to another .org file, like [[file:about.org]], becomes a link to about.html when the site is published. You link between your source files, and Org fixes the extensions for you.

Step 1: the folder structure #

Create this layout. Your writing lives in content/, and the finished site appears in public/.

A dark code window titled my-site showing the project tree: build.sh and build-site.el at the top, a content folder with index.org, about.org, css/style.css, img and a posts folder holding 2026-11-18-hello-world.org, and a public folder marked as generated, never edit by hand
mkdir -p my-site/content/posts my-site/content/css my-site/content/img
cd my-site

Keeping sources and output apart is the most important habit here. public/ is disposable: you can delete it at any time and the build recreates it. Anything you edit by hand in there is lost on the next build.

Step 2: write the content #

content/index.org, the home page:

#+TITLE: My little corner of the web
#+DESCRIPTION: Notes, essays and experiments.

Hello! This site is written in plain text with Org mode and built by Emacs.

* Start here
- [[file:about.org][About me]]
- [[file:posts/index.org][Every post, newest first]]

content/about.org:

#+TITLE: About

I write about the things I build and the things I learn.
You can reach me by email at [[mailto:you@example.org][you@example.org]].

And the first post, content/posts/2026-11-18-hello-world.org:

#+TITLE: Hello, world
#+DATE: <2026-11-18 Wed>
#+DESCRIPTION: The first post on a site built with Org mode.

* Why this site exists
This page was written in *plain text*, with /no/ HTML at all.
Emacs and =org-publish= turned it into a web page.

* A bit of code
#+BEGIN_SRC python
print("Hello from Org!")
#+END_SRC

The #+DATE line matters for posts: the blog index uses it to sort them. Inside Emacs you don't have to type the date by hand. C-c . opens a calendar and inserts it in the right format.

Notice that index.org links to posts/index.org, a file you never wrote. The build creates it, as you'll see in step 4.

Step 3: a stylesheet #

Org's default HTML is clean but plain. A few lines of CSS go a long way. Save this as content/css/style.css:

body { max-width: 42rem; margin: 2rem auto; padding: 0 1rem; font: 18px/1.6 Georgia, serif; color: #222; background: #fdfcf8; }
nav { margin-bottom: 2rem; }
nav a { margin-right: 1rem; }
h1, h2, h3 { line-height: 1.25; }
a { color: #8a3b12; }
pre { background: #f3f1ea; padding: 1rem; overflow-x: auto; }
img { max-width: 100%; height: auto; }
footer { margin-top: 3rem; font-size: 0.9rem; color: #666; }

If you'd rather not write CSS at all, a classless stylesheet like Simple.css or Water.css works well with Org's output, since Org produces plain, semantic HTML.

Step 4: the build script #

This is the heart of the site. Create build-site.el at the root of the project:

;; build-site.el: turns content/ into a website in public/

;; 1. Keep the packages this build needs inside the project
(require 'package)
(setq package-user-dir (expand-file-name "./.packages"))
(setq package-archives '(("melpa" . "https://melpa.org/packages/")
("elpa" . "https://elpa.gnu.org/packages/")))
(package-initialize)
(unless package-archive-contents
(package-refresh-contents))
(package-install 'htmlize)

;; 2. Load the publishing system
(require 'ox-publish)

;; 3. Keep publishing timestamps inside the project too
(setq org-publish-timestamp-directory (expand-file-name "./.timestamps/"))

;; 4. HTML settings shared by every page
(setq org-html-validation-link nil
org-html-head-include-scripts nil
org-html-head-include-default-style nil
org-html-doctype "html5"
org-html-html5-fancy t
org-html-head "<link rel=\"stylesheet\" href=\"/css/style.css\">"
org-html-preamble "<nav><a href=\"/\">Home</a> <a href=\"/posts/\">Posts</a> <a href=\"/about.html\">About</a></nav>"
org-html-postamble "<footer>Written in Org mode, built with Emacs.</footer>")

;; 5. How each post shows up in the posts index
(defun my/sitemap-entry (entry style project)
(if (directory-name-p entry)
entry
(format "%s: [[file:%s][%s]]"
(format-time-string "%Y-%m-%d" (org-publish-find-date entry project))
entry
(org-publish-find-title entry project))))

;; 6. The projects: posts, pages and static files
(setq org-publish-project-alist
(list
(list "posts"
:base-directory "./content/posts"
:base-extension "org"
:publishing-directory "./public/posts"
:publishing-function 'org-html-publish-to-html
:section-numbers nil
:with-toc nil
:with-author nil
:time-stamp-file nil
:auto-sitemap t
:sitemap-filename "index.org"
:sitemap-title "Posts"
:sitemap-style 'list
:sitemap-sort-files 'anti-chronologically
:sitemap-format-entry 'my/sitemap-entry)
(list "pages"
:base-directory "./content"
:base-extension "org"
:publishing-directory "./public"
:publishing-function 'org-html-publish-to-html
:section-numbers nil
:with-toc nil
:with-author nil
:time-stamp-file nil)
(list "static"
:base-directory "./content"
:base-extension "css\\|js\\|png\\|jpg\\|jpeg\\|gif\\|svg\\|webp\\|ico"
:publishing-directory "./public"
:recursive t
:publishing-function 'org-publish-attachment)
(list "site" :components '("posts" "pages" "static"))))

;; 7. Build everything, ignoring what was built before
(org-publish-all t)
(message "Build complete!")

That's a lot at once, so here's what each part does.

Part 1 sets up Emacs' package manager inside the project folder, in .packages, so the build never touches your personal Emacs configuration. It installs one package, htmlize, which Org needs to color the code in your source blocks. Without it, the build stops with "Cannot fontify source block (htmlize.el >= 1.34 required)".

Part 2 loads ox-publish, the publishing system.

Part 3 moves Org's record of what it already published from your home folder into the project. It's a small thing that keeps every project self-contained.

Part 4 shapes every page:

  • org-html-validation-link nil removes the old "Validate" link Org adds at the bottom.
  • The two include settings switch off Org's built-in CSS and JavaScript, since you have your own stylesheet.
  • doctype "html5" and html5-fancy make Org use modern tags like <nav>, <section> and <figure>.
  • org-html-head adds your stylesheet to every page.
  • The preamble goes at the top of each page, so it's a good place for the navigation. The postamble goes at the bottom, which suits a footer.

Part 5 is a small function that decides how each post appears in the posts index: the date from #+DATE, followed by the title as a link. org-publish-find-date and org-publish-find-title read those values from each file.

Part 6 defines the projects. A project is a folder Org knows how to publish:

  • posts exports every .org file in content/posts to HTML. :auto-sitemap t makes Org write a list of all posts into posts/index.org before publishing, newest first because of anti-chronologically. That generated file becomes your blog index, at /posts/.
  • pages exports the .org files at the top of content: the home page and the about page. It isn't recursive, so it leaves the posts alone.
  • static copies everything that isn't Org, like CSS, scripts and images, exactly as it is. org-publish-attachment means "copy, don't convert".
  • site groups the three, so a single name builds everything. The order matters: posts come first, because the home page links to posts/index.org, which only exists after the posts project has generated it.

The :section-numbers, :with-toc, :with-author and :time-stamp-file lines turn off things that feel bookish on a website: numbered headings, a table of contents at the top, the author line and a "created" timestamp. Turn any of them back on for a page that needs it.

Part 7 runs the whole thing. The t forces a full rebuild every time, which avoids confusing moments where a change doesn't show up because Org thinks the file is already up to date.

Step 5: build with one command #

Create build.sh next to it:

#!/bin/sh
emacs -Q --script build-site.el

Make it executable and run it:

chmod +x build.sh
./build.sh

-Q starts Emacs without your personal configuration, so the build behaves the same on any machine, including a server or a CI job. --script runs the file and exits, without opening a window. The first run takes a little longer while it downloads htmlize. After that, public/ holds your site:

public/
index.html
about.html
css/style.css
posts/index.html
posts/2026-11-18-hello-world.html

Step 6: preview it #

The navigation uses links that start with /, so open the site through a small web server rather than double-clicking the files. Python has one built in:

cd public
python3 -m http.server 8000

Then visit http://localhost:8000. Change a file, run ./build.sh again and reload the page.

If you prefer to stay inside Emacs, the simple-httpd package does the same job: install it from MELPA, run M-x httpd-serve-directory and point it at public/. It serves on port 8080 by default.

Working from inside Emacs #

The build script is the reliable way to publish, but Org's export menu is handy while you write. Inside any Org file:

  • C-c C-e: open the export menu
  • C-c C-e h h: export the current file to HTML
  • C-c C-e h o: export it and open the result in your browser
  • C-c C-e P f: publish the current file with its project settings
  • C-c C-e P p: publish the current project
  • C-c C-e P a: publish every project
  • C-c C-l: insert a link, with completion for file paths
  • C-c .: insert a date from a calendar

The P commands need org-publish-project-alist loaded in your running Emacs. One way is to keep the project definitions in a separate file and load it from your configuration.

Images #

Put images in content/img/ and link to them with a path relative to the Org file:

[[file:img/sunset.jpg]]

From a post inside posts/, go one level up:

[[file:../img/sunset.jpg]]

To add a caption, alt text or a size, put these lines right above the link:

#+CAPTION: The view from the window, at the end of the day
#+ATTR_HTML: :alt A sunset over the hills :width 600
[[file:../img/sunset.jpg]]

The static project copies the image to public/img/, so the same relative path works on the published site. If an image is missing from the output, check that its extension is in the :base-extension list of the static project.

Better code highlighting #

By default, htmlize writes the colors straight into each code block, using whatever theme the build happens to have. With emacs -Q, that's the default light theme. To control the colors with CSS instead, add this to part 4 of build-site.el:

(setq org-html-htmlize-output-type 'css)

Now the code blocks carry CSS classes instead of colors. To get a stylesheet for them, open your normal Emacs with the theme you like, run M-x org-html-htmlize-generate-css, and save the buffer it produces as content/css/code.css. Then load it next to your stylesheet:

org-html-head "<link rel=\"stylesheet\" href=\"/css/style.css\"><link rel=\"stylesheet\" href=\"/css/code.css\">"

Per-page settings #

Everything set in the build script can be changed for a single page with #+ lines at the top of the file. For example, a long guide that deserves a table of contents and numbered sections:

#+TITLE: A long guide
#+OPTIONS: toc:t num:t

And to add something only to the <head> of one page:

#+HTML_HEAD_EXTRA: <meta name="robots" content="noindex">

The order of priority is simple: settings inside a file win over the project settings, which win over the global variables.

Publishing it #

The finished site is just files in public/, so anything that serves files can host it.

To your own server, with rsync:

./build.sh
rsync -avz --delete public/ you@your-server:/var/www/my-site/

The --delete flag removes files from the server that no longer exist locally, so deleted pages disappear online too. On the server, any web server pointing at that folder will do.

For GitHub Pages, Codeberg Pages or SourceHut pages, the idea is to run build.sh and upload the contents of public/, by hand or from a CI job that installs Emacs and runs the same script. That's the payoff of emacs -Q --script: the build doesn't depend on anyone's personal setup.

If you keep the site in git, commit the sources and the build files, and leave the generated and downloaded folders out with a .gitignore:

public/
.packages/
.timestamps/

Common errors and what they mean #

  • "Unable to resolve link": a [[file:...]] link points to an Org file that doesn't exist. Usually a typo, or a page that hasn't been written yet. Org stops the build on purpose, so you never publish broken internal links.
  • "Cannot fontify source block (htmlize.el >= 1.34 required)": htmlize isn't installed. Part 1 of the build script takes care of it, so check that it ran, and that the machine could reach MELPA.
  • The navigation works online but not when you open the files directly: links starting with / point to the root of a web server. Use the preview server from step 6.
  • A change doesn't show up: make sure you ran the build again, and that you're looking at public/, not content/. The t in org-publish-all t already rules out stale caches.
  • An image or CSS file is missing: its extension isn't in the static project's :base-extension.

Going further #

What you built here covers a personal site and a simple blog. When you want more, there's a whole ecosystem around Org publishing:

  • RSS: the ox-rss package, on MELPA, exports Org files to an RSS feed that can sit next to your posts.
  • ox-hugo: write in Org, and let Hugo build the site. Useful if you want Hugo's themes and features but prefer Org for writing.
  • org-static-blog: a small package focused on blogs, with an archive, tags and an RSS feed out of the box.
  • weblorg: a static site generator for Emacs with templates, for sites that outgrow a plain ox-publish setup.

Worg keeps a page that compares many of these tools, listed below.

A good path is to start with plain ox-publish, as in this guide. It's built in, it will keep working as long as Emacs does, and every piece of it is a few lines of Emacs Lisp you can read and change. Reach for the bigger tools once you know exactly what you're missing.

Study sources #