Building a Emacs Org-Mode Blog

Evaluating above code is enough to enable publishing. Open an org file within your project and type C-c C-e to bring up the "Org Export Dispatcher", type P for Publishing, and a to publish all. The site will be generated and placed in the html/ directory.

You can also publish the site from elisp with:

(org-publish "taingram.org" t)

The t argument is optional and will force every file to be re-export, even if that file has not changed. Useful if you are experimenting with project settings without changing org files.

We can tweak the way HTML is exported with a number of :html-* options. I prefer to use HTML5 and disable Org's default style sheet and scripts:

; HTML5
:html-doctype "html5"
:html-html5-fancy t

; Disable some Org's HTML defaults
:html-head-include-scripts nil
:html-head-include-default-style nil

Like :html-head Org Publish options for inserting extra HTML before and after your post content using :html-preamble and :html-postamble.

You can add as much (or little) additional HTML as you would like. I used the preamble to insert some navigation and when the page was updated. The postamble has a footer with copyright information and site creation info.

:html-preamble "<nav>
  <a href=\"/\">&lt; Home</a>
</nav>
<div id=\"updated\">Updated: %C</div>"

:html-postamble "<hr/>
<footer>
  <div class=\"copyright-container\">
    <div class=\"copyright\">
      Copyright &copy; 2017-2020 Thomas Ingram some rights reserved<br/>
      Content is available under
      <a rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\">
        CC-BY-SA 4.0
      </a> unless otherwise noted
    </div>
    <div class=\"cc-badge\">
      <a rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\">
        <img alt=\"Creative Commons License\"
             src=\"https://i.creativecommons.org/l/by-sa/4.0/88x31.png\" />
      </a>
    </div>
  </div>

  <div class=\"generated\">
    Created with %c on <a href=\"https://www.gnu.org\">GNU</a>/<a href=\"https://www.kernel.org/\">Linux</a>
  </div>
</footer>"

Note the use of '%c' and '%C', these symbols will be expanded by Org's html exporter. Their meaning is documented in the org-html-preamble-format variable. Here is the complete list:

Org publish can generate a sitemap for projects, essentially a site wide table of contents with links and directory structure. For a global sitemap in your website add the following to the "pages" project component:

:auto-sitemap t
:sitemap-filename "sitemap.org"

For example, a global sitemap for taingram.org would appear as follows:

• Interesting Links From Around the Web
• Résumé
• Useful Tips and Tricks
• blog
  • Building a Blog with Emacs Org-Mode
  • Emacsclient Setup with Desktop Integration
  • Fixing Dell XPS 13 Audio

Once the sitemap.org is generated you can include it from any other page with

#+INCLUDE: sitemap.org :lines "3-"

The :lines 3- will only include the 3rd line on, skipping the #+TITLE tag set in sitemap.org and grabbing the list of pages as shown above.

Another option is to publish directly to your web server using TRAMP. TRAMP (Transparent Remote (file) Access, Multiple Protocol) is a tool built into Emacs for accessing files on remote servers. The format for accessing a file over TRAMP is /method:user@host:/path/to/file and can be used directly in Emacs find file dialog.

We can simply replace our :publishing-directory with the tramp format:

:publishing-directory "/ssh:thomas@taingram.org:/var/www/taingram.org/html/"

Just like that when we publish our file they will be sent directly to our server. Convenient for publishing individual files, but will be much slower than the rsync solution.

If you do not intent to distribute the source code of your website or move the directory around frequently. The simplest way to configure Org publish is to place settings directly in your Emacs init with hard coded directory paths.

However, I've released the source of my website and therefore hard coded paths will break when project folder moves around. For that reason I keep all of my Org publish configuration in publish.el. From publish.el we can get the complete project path:

(defun my/relative-path-expand (path)
  "Expand relative PATH from current buffer or file to a full path."
  (concat
   (if load-file-name
       (file-name-directory load-file-name)
     default-directory)
   path))

Now we can dynamically set our base directory to the full path:

:base-directory  ,(my/relative-path-expand "org/")

Note for this to work your org-publish-project-alist should be started with a ` (backquote) which enables code after a comma to be evaluated. See backquote in the Emacs Lisp Manual.

$ go get github.com/golang/example/hello

$ go get github.com/golang/example/hello

$ go get github.com/golang/example/hello

• https://nicolas.petton.fr/
• https://ogbe.net/
• https://bastibe.de/