Seam

Seam is a personal wiki system based on Org mode.

The target audience is people who wish to keep a large collection of notes — some publicly shared and others private — and to export a subset of them to HTML in a no-nonsense way.

Read on for a brief overview, or follow the tutorial.

Notes

A Seam note is an Org file with a level 1 headline for its title. Metadata is explicitly avoided. Note files are automatically renamed according to their title.

All notes are kept in a single directory: seam-note-directory. They are filed into subdirectories according to their type. (Deeper nesting is not supported.)

One key use of types is to exclude certain notes from export.

In the default setup, all notes are created private, and can be made public with seam-set-note-type. This can be customized via seam-note-types and seam-default-note-type.

Exporting

Nothing is exported by default. Use seam-export-alist to set up exports.

Here is an example with two different export setups (using a custom draft note type): 

(setq seam-export-alist
      '(("~/seam/html/preview"
         :types ("public" "draft")
         :root-path "/preview/")
        ("~/seam/html/live"
         :types ("public")
         :root-path "/")))

All relevant notes are exported automatically when saving. You can run seam-export-all-notes if you ever need to manually re-export existing notes.

Linking

Notes are linked together by name, using the seam: link scheme. Whenever a note is renamed, links are fixed up automatically. Links to unexported notes are not rendered as links — only the description will be visible.

If you wish to have a backlinks (or “incoming links”) section on your page, it’s easy to do so with templating.

Templating

Currently Seam uses a very basic HTML templating system. It specifies a handful of variables that you can reference like {{this}} within your templates.

See seam-export-alist for the various ways of specifying a template, and seam-export-default-template-string for the variables that are available.

Title formatting

By default, Seam formats titles for completion and buffer names using seam-format-title-default. However, you can set seam-format-title to a custom function. Here is an example of a formatter using icons: 

(defun my-seam-title-formatter (title type)
  (format "%s %s"
          (cdr (assoc type '(("private" . "🔒")
                             ("public" . "🌐"))))
          title))

Other options

All options are documented under M-x customize-group seam.

Caveats

Seam is a new project, in active development. I cannot promise there will be no sharp edges or breakage. However, I will do my best to document and fix all issues as they arise.

Some features are still notably missing, such as the ability to copy linked files into an export.

Check it out

Latest release: v0.1.0 (2025-03-15) 

git clone https://git.plexwave.org/seam

There is a GitHub mirror if you prefer.

Seam has no dependencies besides Emacs itself and POSIX-compatible find and grep. Emacs versions prior to 30.1 have not been tested.

Pencil icon Edited