Garnett: A Simple Emacs-based Static Site Generator

Synopsis

This is (yet another) wrapper around org-mode’s powerful publishing engine. The name garnett is meant as a tribute to Constance Garnett, a famous translator of Russian literature.

Mostly org-mode based

Uses parts of org-mode’s extensive publishing engine.

Image Management

Handles image resizing and organization. Supports metadata stored in separate org-mode files for image details such as titles, captions, and tags.

Customizable Layouts

Allows you to define custom HTML preambles and postambles to control the overall site structure.

Extensible

Uses a modular design, making it relatively easy to add new features and customize existing ones.

Minimal HTML

Aggressively prefers dom.el representations over “manual” html.

Getting Started

1. Install Garnett: Place garnett.el file in your Emacs load-path (dom.el and org-mode is required).
2. Create Project: Create a directory for your website. Within that directory, create the following:

   content

   Directory for your org-mode content files (e.g., blog.org, pages/about.org).

   static/

   Directory for static assets like CSS, JavaScript, and images (to be copied, not processed).

   images/

   (Optional) Directory for images that will be processed and resized. You can point Garnett to any accessible path where your images reside using garnett-image-source-dir .

   example-project-publish-configuration.el

   (Example provided below) Your Garnett configuration file.

3. Configure Garnett :: Create an example-project-publish-configuration.el file with your project settings.
4. Create Content :: Create your website content using org-mode files in the content/ directory. Image galleries, must be put into elisp source blocks that export your images. E.g.,

#+begin_src elisp :exports results :results html
  (garnett-dom-to-html
   (garnett-image-generate-image-list-dom
    (directory-files garnett-image-source-dir t directory-files-no-dot-files-regexp)
    garnett-image-db
    (list
     (garnett-get-path-relative-file garnett-static-dir "js/lightbox.js")
     (garnett-get-path-relative-file garnett-static-dir "js/tagfilter.js"))))
#+end_src

1. Publish :: Use M-x org-publish to generate your website. The org-publish-project-alist in your configuration file defines what to publish and how. Select the project name (e.g., "example-project") from the list.

Configuration (Example: example-project-publish-configuration.el)

(require 'garnett)

(setq garnett-project-root-directory    (file-truename ".")
      garnett-project-publish-directory (file-name-concat (file-truename ".") "public")
      garnett-image-source-dir          (file-truename "./images") ; Path to your image directory
      garnett-image-publish-dir         "images" ; this is within `garnett-project-publish-directory'
      garnett-static-dir                "static" ; this is within `garnett-project-publish-directory'
      garnett-image-db-name             "image-metadata.org"  ; Metadata for images
      garnett-image-db (garnett-parse-metadata-org-buffer garnett-image-db-name)
      ; ... other garnet settings (see garnett.el for options) ...
      )

(setq org-publish-project-alist
      `((("example-project"
         :base-directory "./content"
         :publishing-function org-html-publish-to-html
         :publishing-directory ,garnett-project-publish-directory
         ; ... other org-publish settings ...
         )
        ("images"
         :base-directory ,garnett-image-source-dir
         :base-extension "jpg\\|gif\\|png"
         :exclude "\\.DS_Store"
         :publishing-directory "./public/images"
         :publishing-function garnett-image-image-export-resize)
        ("static"
         :base-directory ,garnett-static-dir
         :base-extension "css\\|js\\|svg\\|png\\|jpg\\|ico"
         :exclude "\\DS_Store"
         :recursive t
         :publishing-directory "./public/static"
         :publishing-function org-publish-attachment))))

Example org-mode Content

#+title: Blog
#+name: utility-functions
#+begin_src elisp :results none :exports none
(require 'garnett)
#+end_src


* Make available                                                   :noexport:

This is needed in case you need some of the configuration variables here.

#+CALL: utility-functions()

* Post 1
This is the content of my first blog post.

* Post 2
This is the content of my second blog post.

Example org-mode Content

#+title: Photography

#+name: utility-functions
#+begin_src elisp :results none :exports none
(require 'garnett)
#+end_src


* Make available                                                   :noexport:

This is needed in case you need some of the configuration variables here.

#+CALL: utility-functions()

* Gallery

#+begin_src elisp :exports results :results html
  (garnett-dom-to-html
   (garnett-image-generate-image-list-dom
    (directory-files garnett-image-source-dir t directory-files-no-dot-files-regexp)
    garnett-image-db
    (list
     (garnett-get-path-relative-file garnett-static-dir "js/lightbox.js")
     (garnett-get-path-relative-file garnett-static-dir "js/tagfilter.js"))))
#+end_src

Remember to replace placeholders like image paths and file names with your actual content.

Advanced Usage

Consult the garnett.el file for a complete list of customizable variables to fine-tune Garnett to your needs. You can adjust HTML templates, add custom functions, and extend Garnett’s capabilities.

Contributing

Contributions are welcome!