The Elpher Client is an Emacs plugin to view Gopher holes and Gemini capsules. Some configuration are available to change the way Elpher presents information, such as:

 ( use-package elpher
   :custom
  (elpher-gemini-link-string  "🔗 ")
  (elpher-gemini-bullet-string  "- "))

Start browsing with M-x elpher-go and enter a Gemini or Gopher address. Some useful keybindings are (press ? for more):

• O: Back to capsule root page
• R: Reload the current page
• ^: Back to previous page
• TAB and S-TAB: Next and previous link

If you want to become an active participant in the world of Gemlogs, then Emacs also has you covered. Two methods are available to create a Gemini Capsule with Emacs:

1. Write directly in Gemtext
2. Write in Org mode and publish to Gemtext

While writing Gemtext in Emacs is easy, using Org mode adds more flexibility because you can export the same files as a website, ebook, or even a print-ready PDF for a book. The Org publishing functionality also provides some powerful abilities to add dynamic content and automatically generate sitemaps and other embellishments.

The ox-gemini package by Justin Abrams provides an Org mode export backend to either convert individual Org files, or publish a complete capsule. Most Org mode functionality doesn't translate to Gemtext, such as front matter keywords, and image captions, and the export module as such ignores them.

You can add sections that are only included when exporting to Gemtext by wrapping them in a source code structure template, which appears with C-c C-, E gemini. Any text written inside the export block only appears in Gemini exports. Alternatively, you can also add text in an exort_html block so that it only appears in all the web version of your page, and so on.

 #+begin_export gemini
```
⠀⠀⠀⠀⡄⠀⢻⡄⢠⡛⠀⢠⠀⠀⠀⠀
⠀⠀⠀⠀⠘⣧⠸⠇⠸⠇⣼⠃⠀⠀⠀⠀
⠀⠘⠶⠶⡄⣠⣶⣿⣿⣶⣄⢠⠶⠶⠃⠀
⠰⠶⣤⡄⣼⣿⣿⣿⣿⣿⣿⣧⢠⣤⠶⠆
```
#+end_export

Exporting individual pages works through the usual org-export-dispatch menu ( C-c C-e) and selecting the appropriate menu options.

Exporting each page individually can be tedious, so Org mode's publishing function has you covered. With this functionality you point Org mode to your source files and provide it with a destination, indicate the export format, and Emacs does the rest.

To publish a complete Gemini capsule written in Org, create a project directory to start writing content, for example ~/projects/gemini/content/. This directory will contain your capsule in Org mode, including any images or other attachments. For each project component, the following minimal options are available:

• :base-directory: Location of the source files
• :publishing-directory: destination of the exported files
• :publishing-function: how the files are exported. Some options are:
  • org-html-publish-to-gemini: converts org files to Gentext
  • org-publish-attachment: copies files verbatim
• :recursive: Set to non-nil when you have files in subdirectories

The example configuration below has two components: the Gemini pages and any related images, each using different source and target directories and publishing functions. For the static files, the targeted files a regular expression indicates the relevant file extensions without the dot. The two components combine to create the "gemini" project. This project will be available for publishing with (org-publish "gemini"), or the dispatch menu with C-c C-e P x.

 ( require ' ox-publish)

( setq org-publish-project-alist
      (list '( "gemini-pages"
               :base-directory  "~/projects/gemini/content/"
               :publishing-directory  "~/projects/gemini/gemini/"
               :recursive t
               :publishing-function org-gemini-publish-to-gemini)
            '( "gemini-images"
               :base-directory  "~/projects/gemini/org/images"
               :base-extension  "png \\ | jpg \\ | webp"
               :publishing-directory  "~/projects/gemini/gemini/images"
               :recursive t
               :publishing-function org-publish-attachment)
            '( "gemini"
               :components ( "gemini-pages"  "gemini-images"))))

The first five steps prepare the source files before the actual export loop starts:

1. Evaluate the project
2. Run the preparation functions
3. Initialise the timestamp cache
4. Generate sitemaps
5. Collect files

Now the actual publication starts. For every file in the project, Org takes these five steps:

1. Compute the destination directories, preserving relative directory hierarchies in the publishing-directory.
2. Check if the source file or any of its dependencies have changed since the last build using the timestamp cache, or whether the user asks to ignore the cache.
3. When the file has changed, or the user forces publishing all files, call the publishing function and the export engine to process the file.
   • Parsed into an Abstract Syntax Tree (AST)
   • Extract project properties, buffer keywords ( #+TITLE:, #+DATE:, etc.), and export options and merge into a unified property list.
   • Evaluate dynamic functions assigned to :html-head, :html-head-extra, :html-preamble, and :html-postamble using the property list.
   • Write the transcoded output string to the destination file.
4. Cache the output path returned by the publishing function.
5. Trigger the org-publish-after-publishing-hook.

The actual transformation occurs in the third step with several opportunities for deep configuration by using filters on the source text.

1. Generate the index
2. Evaluate the completion functions
3. Commit timestamp cache to disk

This detailed description of the publishing process should give you everything you need to create the website you deserve. However, the capabilities are not as advanced as major publishing systems such as Hugo or Jekyll, without advanced Elisp hacking. Org mode is as such ideal for websites that focus on sharing text, but perhaps not so much a fancy graphical landing page.

For me, it is satisfying to do everything inside Emacs so I choose to move from Hugo to using Org mode. You can peruse the source code on the GitHub repository.

You can control the export process at three levels: keywords for individual files, project parameters, or global variables. The examples below show how to exclude the author name from a web page from an individual page, set it for a project, or configure it for all future exports. Note that the file keyword overrides the export parameter, which in turn overrides global settings, so in order of priority:

1. Add a keyword for a specific file ( #+OPTIONS: :author:nil)
2. Use an export parameter for the project ( :with-author nil)
3. Set a global variable for all future exports (setq org-export-with-author nil)

The help file for each variable describes the syntax to use in a project, or in an individual file. The examples in this article describe the export parameters for projects.

The help file for org-publish-project-alist lists generic properties to finetune the output. These variables mainly determine whether to include or exclude certain Org mode syntax elements, such as drawers, tags or TODO keywords. The help file for each of these variables explains their effect on the result and how to define it as a file keyword or project parameter. For example, to remove the table of contents and standard footer, use this in your project:

  :with-toc nil
 :with-author nil
 :with-date nil
 :time-stamp-file nil

You can also override these for individual files. For example, if you want to include a table of contents for a long article, then override this project setting by adding #+OPTIONS: toc:1, which in this case would result in a table of contents with only level 1 headings.

These options apply to any export type, either HTML, ASCII, or whatever your publishing project entails. The next sections discuss how to use website-specific variables to optimise your website's design.

The head element of a web page contains metadata for browsers, search engines, and web services. The head is essential for a responsive, well-designed website that search engines and social media recognise.

Org assembles the head tag sequentially in three parts:

1. org-html--build-meta-info: Character set encoding, viewport, document title, generator and available file keywords (author, description, and keywords).
2. org-html--build-head: Default CSS and Javascript, and/or user-generated content.
3. org-html--build-mathjax-config: MathJax scripts when LaTeX fragments are part of the content.

The viewport and character set in the first part are configurable, but for most websites the defaults are just fine. The second part of the head tag is fully configurable. Org export adds a default style sheet and JavaScript to each exported file. You can replace these defaults with your personal preference. The :html-head can be a string to define your preferences, as shown below.

  :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-head  "<link rel=\"stylesheet\" href=\"https://cdn.simplecss.org/simple.min.css\" />"

Alternatively, you can save the head content in a template file and include CSS, a favicon and other static parts of the head and read it into a string.

 ( setq my-html-head
      ( with-temp-buffer
        (insert-file-contents
         (expand-file-name  "templates/head.html"))
        (buffer-string)))

Add this variable to your project component with :html-head ,my-html-head. The comma before the variable name inserts the value into the list instead of the literal string.

You can also override or append the HTML head settings for individual files with the #+HTML_HEAD: keyword to replace the template, and #+HTML_HEAD_EXTRA: to append the template.

The next article in this series explains how to create dynamic content, such as Open Graph and Structured Data, using a function instead of a static variable.

The third part of the HTML head is an optional part to load MathJax for rendering mathematical formulas, which is further described below.

Org mode uses an old HTML standard for generating pages. However, modern websites use HTML5 for improved accessibility, SEO, cleaner code, and easier styling.

The diagram below illustrates a typical semantic HTML5 page layout. It frames the central main area between a header and footer, dividing the main body into an aside for supplementary content and one or more sections, each containing one or more articles for the core message.

┌─ header ──────────────────────────────────────┐
│                                               │
└───────────────────────────────────────────────┘
┌─ main ────────────────────────────────────────┐
│ ┌─aside─┐ ┌─ section ───────────────────────┐ │
│ │       │ │ ┌─article─────────────────────┐ │ │
│ │       │ │ │                             │ │ │
│ │       │ │ │                             │ │ │
│ │       │ │ └─────────────────────────────┘ │ │
│ └───────┘ └─────────────────────────────────┘ │
└───────────────────────────────────────────────┘
┌─ footer ──────────────────────────────────────┐
│                                               │
└───────────────────────────────────────────────┘

You can configure Org mode to use HTML5 in the export process. These HTML export options in Org mode control the Document Object Model for your website:

• org-html-doctype: Document type definition
• org-html-html5-fancy: Use new HTML5 elements
• org-html-divs: Defines the elements for HTML export
• org-html-container-element: Top level sections

The example below configures Org mode to use semantic elements instead of generic <div> tags. In html-divs, the first string is the HTML tag and the second one is the id, e.g. <main id="content">.

  :html-doctype  "html5"
 :html-html5-fancy t
 :html-divs ((preamble   "header"  "preamble")
            (content    "main"    "content")
            (postamble  "footer"  "postamble"))
 :html-container  "section"

The header of a HTML page (or preamble) usually holds content such as navigation, a logo, title, author name and so on. We can define a header of our site using :html-preamble.

When this variable is set to t, the content of org-html-preamble-format defines the header, which is empty by default. You can also configure the preamble as a string. This string can contain the following format markers to include page variables:

• %t: Title of the source file ( #+title:)
• %s: Subtitle of the source file ( #+subtitle:)
• %a: Content of the #+author: keyword or user-full-name.
• %e: Content of the #+email: keyword or user-mail-addres wrapped in a mailto link.
• %d: Content of the #+date: keyword.
• %C: Last modification time of the source file
• %T: The export time of the source file
• %c: Content of org-html-creator-string (links to Emacs and Org mode websites).
• %v: Content of org-html-validation-link

The three timestamp format markers produce a date in accordance with org-html-metadata-timestamp-format, which you can configure to your regional preferences.

A simple example of a header string could be:

  :html-preamble  "<h1>%t</h1>\n<h2>%a</h2>"

When including the title in the header, you might want to exclude the title from the main content to avoid duplication by setting :with-title to nil.

Just like the head element, you can read a static template file with a function, including format markers, and use that as a preamble, as explained above.

Org mode can also evaluate a function to define a header dynamically based on the page's metadata, which is discussed in the next article in this series.

Org export also provides a range of variables to finetune how the content converts to HTML. The next sections describe some specialised options to configure the main content of your pages.

A footer typically contains authorship, copyright and contact information and perhaps links to other pages.

By default, Org mode uses the author, email, creator, date and a validation link to construct a footer. You can and define a bespoke footer and override these settings by configuring :html-postamble. The method is the same as with the header.

When this variable is t, the content of org-html-postamble-format becomes the footer. You can also use a bespoke string using the same format markers with the header and read the contents from a template, in the same ways as the head and preamble of the page.

The export module in Org version 9.8 defines over 130 variables plus 77 variables specific to HTML exports. This article only discussed salient variables.

The Emacs help system is your friend if you like to explore deeper. The help file for org-publish-project-alist contains an extensive list of configuration options. You can also explore the variables starting with org-html to deeper explore the available options to configure the output.

The next article in this series discusses how to create dynamic content such as the HTML head, preable, postamble, sitemaps and RSS feeds using bespoke publishing Elisp functions.

Let's assume our mini website looks something like this:

content
  ├── index.org
  ├── about.org
  ├── blog/
  │    ├── index.org
  │    ├── 2026-09-12-post-01.org
  │    └── ...
  └── images/
       ├── image01.png
       └── ...

The standard export process through the dispatch menu ( org-export-dispatch) converts one file at a time, which is a tedious process when publishing a website. You can concatenate Org files with the #+INCLUDE: keyword, but that will result in a single export file unsuitable for a website. The Org mode publishing functionality lets you export a collection of files and associated static files as a project. The configuration below defines a minimum working example:

 ( setq org-publish-project-alist
      `(( "html"
          :base-directory  "~/content"
          :publishing-directory  "~/public"
          :recursive t)
        '( "images"
           :base-directory  "~/content/images"
           :base-extension  "png \\ | jpg \\ | webp"
           :publishing-directory  "~/public/images"
           :recursive t
           :publishing-function org-publish-attachment)
        '( "website"
           :components ( "html"  "images"))))

The org-publish-project-alist variable can contain one or more publishing projects (websites, Gemini capsule, collections of PDF files and so on). Each project consists of one or more components, in this example the website project contains HTML files and associated images. The backquote at the start of the list allows you to selectively evaluate elements in the list, which will be useful later on.

Each list begins with the name of the component, followed by an list of named properties. The minimum requirement is to define the base and publishing directories. This minimal setup exports all Org mode files in the base directory and saves the HTML versions in the publishing directory:

• :base-directory: Directory containing the source files, in our case ~/content. Defaults to all files with the .org extension.
• :publishing-directory: The directory for exported files.

The example above also sets :recursive t for both components. When this option is non-nil, the export includes all subdirectories of :base-directory.

The second component defines the location of images, which are copied without any transformation. We do this by specifying a publishing function. The org-publish-attachment function copies files from the base to the publishing directory, which is ideal for images, CSS, robots.txt and other static files. This config uses a regular expression to define the extensions of the included files. We don't need a publishing function for converting Org mode to HTML as this is the default.

The third component combines the first two for convenience, so we don't have to export components individually to build the website.

You might not want to publish every Org mode file in your base directory, so Org mode provides tools to include and exclude specific files. For example, you might want to exclude all files with "draft" in their filename.

• :base-extension - Define the included extension(s) without the dot for source files. The default is "org". When set to "any", then Org converts all files to HTML as if they were Org mode files.
• :exclude - Exclude files from publishing using a regular expression to match file names.
• :include - Include extra files with a list of filenames relative to the base directory. Note that the exclusion step evaluates first.

These configurations require a regular expression as input. In this website I use a function to generate this regex to exclude any articles with a future data or with #+draft: t as a keyword.

To publish the project, use C-c C-e P x ( org-publish) and select the relevant component or meta-project (i.e. "website"). Alternatively, use M-x org-publish-all to publish all components or org-publish-project to select a component or project.

Org mode creates the publishing directory if it doesn't exist yet. Note that org-publish doesn't delete existing files in the output directory. As a result, removed pages will remain on the server unless you explicitly remove them.

You don't have to republish every file each time you generate the website. Org mode maintains a list of timestamps that record when a file was last published. This cache is stored in the location defined by org-publish-timestamp-directory. This functionality allows us to skip unmodified files to reduce processing time. To force publishing all files in the project, use the universal argument ( C-u M-x org-publish-all).

Emacs has a web server package to test the freshly published website that can serve the content of a publishing directory at http://localhost:8080.

 ( use-package simple-httpd
   :init
  (httpd-serve-directory  "~/public"))

These are the basic principles of publishing a website with Org mode. However, the result is not up to scratch with the expectations for modern web standards. Org mode inserts its own CSS, and the pages are not SEO optimised, so there is still a lot to do.

The next article discusses how to expand on the basic functionality to create a simple website that meets modern needs.