Liaison

This example registers a new blob macro which will receive the URL to the blob page of the currently visited document.

(setq org-export-global-macros
      '(("blob" . "(eval (liaison-get-resource-url 'blob))")))

We can now call the blob macro in an Org document and it will expand to the string we assigned to it.

#+TITLE: Example

* Heading

To view this document in its raw format, follow this link: {{{blob}}}.

In your publishing script, you will want to redefine the org-html-format-spec function such as to extend it with your custom format strings.

If you intend to use any other format strings, such as the preset %a or %e, don't forget to add them, otherwise they won't be expanded.

(defun org-html-format-spec (info)
  "Return format specification for preamble and postamble."
  `((?b . ,(liaison-get-resource-url 'blob))
    (?m . ,(liaison-get-resource-url 'blame))
    (?t . ,(liaison-get-resource-url 'tree))
    (?l . ,(liaison-get-resource-url 'log))
    (?p . ,(liaison-get-resource-url 'plain))
    (?e . ,(liaison-get-resource-url 'edit))))

This next step involves preparing your project structure to support the use of HTML templates; snippets which will be added onto our Org documents. These templates can reference at any point any of the format strings defined in the org-html-format-spec function.

The following is an example of such a template:

<nav>
  <a href="%e"><button>Edit</button></a>
  <a href="%m"><button>Blame</button></a>
  <a href="%b"><button>Blob</button></a>
  <a href="%t"><button>Tree</button></a>
  <a href="%l"><button>Log</button></a>
  <a href="%p"><button>Plain</button></a>
</nav>

During the export phase, Org will locate the format strings, and interpolate them using the return value of their associated function.

We'll now need a way to access the contents of these HTML files from our publishing script - to achieve that, you could use something like this:

(defun read-template (filename)
  "Read contents of FILENAME from the templates directory."
    (with-temp-buffer
      (insert-file-contents
       (file-name-concat "templates" filename))
      (buffer-string)))

We will use read-template along with the :html-preamble property to inject a preamble into the files of a particular project component.

(setq org-publish-project-alist
      (let ((preamble (read-template "preamble.html")))
        (list
         (list "articles"
               :base-extension "org"
               :base-directory "articles"
               :publishing-directory "public/articles"
               :publishing-function 'org-html-publish-to-html
               :html-preamble preamble
               :html-postamble nil)
         (list "all"
               :components "articles"))))

Your website is now properly configured to use Liaison.

The publishing script should be loaded before the org-publish-project function is called, this translates to the following command:

emacs --quick --batch \
      --load publish.el \
      --funcall org-publish-all t t

In some cases, you may find yourself using Liaison's functions in a publishing project with the :auto-sitemap option set to t.

Provided you are relying upon a templating system like the one proposed in this document, you will notice that when you visit the sitemap (e.g. https://example.com/blog/sitemap.html) in a web browser, the document will contain the same preamble/postamble as the files which it is indexing.

To get around this, you should use set the :sitemap-function option. Here's an example in which we hide the postamble from appearing in the sitemap:

(defun my/blog-sitemap-function (title list)
  "Custom site map function for the blog project."
  (concat "#+OPTIONS: html-postamble:nil\n"
          (org-publish-sitemap-default title list)))

Here's another example which references a setupfile:

(defun my/blog-sitemap-function (title list)
  "Custom site map function for the blog project."
  (concat "#+SETUPFILE: setup.org\n"
          (org-publish-sitemap-default title list)))

By now you will have noticed that the strings we're concatenating to the default sitemap function, i.e. org-publish-sitemap-default, follow the same syntax as any Org document.

The result of this endeavor is a persistent configuration of the project's sitemap with our own custom options.