Home > Usage > Org Mode

Org Mode

This section describes how to use Org mode to write your web pages using mark-up rather than writing HTML. Org mode is provided by the GNU Emacs editor.

I write all body content using Emacs' Org mode. That is, I create and edit a file body.org in each site directory. The files body.htm are generated by using Org mode's HTML export functionality. The body.org files also contain the necessary meta data, via lines like

#+HTML_HEAD: <meta name="htTab" content="Usage"/> <meta name="htOrder" content="10"/>

Alternatively, you could also write

#+HTML_HEAD: <meta name="htTab" content="Usage"/>
#+HTML_HEAD: <meta name="htOrder" content="10"/>

with the same effect. The Org mode exporter converts such lines to proper <meta> HTML elements in the <head> section of the target HTML file, as required by trgensit.

Configuring the Org Mode Exporter Functionality

Emacs Org mode comes with an export module that can export to various output formats. For the purpose of trgensit, we need the Org mode exporter to export to minimal, "plain vanilla" HTML. I have documented how to achieve this under https://web222.webclient5.de/doc/swdev/emacs/orgmode/html.

In summary, to configure the Org mode exporter accordingly, you might want to add a statement like

#+SETUPFILE: path/mysetup.org

to the top of each body.org file. An example mysetup.org file is included in the trgensit-org.zip file in directory trgensit/doc/. All body.org files of the trgensit manual contain a relative path to this central file.

Using Make

The files trgensit.zip and trgensit-org.zip contain a Makefile in directory trgensit/doc/site. This eases the maintenance of a web site. There are two specificities:

1) Using One Makefile For a Tree

If you are working on a body.org or body.htm file, and invoke make, it will look for Makefile or makefile in the same directory. Rather than copying a Makefile to each directory, or providing a path to a central Makefile every time, I added functionality to Emacs to be able to use just one Makefile at the top of the web-site tree. I added to my Emacs init.el file the following lines:

;;; Use make file in current dir /or further up/. Can amend when prefixed with C-u
(defun my-compile-project ()
  (interactive)
  (let* ((mk-dir (locate-dominating-file (buffer-file-name) "Makefile"))
         (compile-command (concat "make -k -f " (shell-quote-argument (concat mk-dir "Makefile"))))
         (compilation-read-command nil))
    (call-interactively 'compile)))

(global-set-key [f5] 'my-compile-project)

This allows me to update a changed page by hitting the F5 key in Emacs. With prefix, i.e. C-u F5, I can change the make command line, for example to select a different make target, e.g. updateall to process a whole sub-tree.

2) Using Thomas' Org Mode Exporter Post Processing

The provided Makefile calls my Emacs function tr-org-html-export-to-html rather than the built-in org-html-export-to-html. The purpose is to post-process the HTML generated by Emacs Org mode. The rationale is given in https://web222.webclient5.de/doc/swdev/emacs/orgmode/html and the code is published under https://web222.webclient5.de/doc/swdev/emacs/orgmode/html/trorghtml.zip

Other Option - Markdown

Of course Markdown could also be used to write the web pages. A tool like pandoc could be used to go from a body.md file to the body.htm file.

Alternative to trgensit - Org Publishing

Org mode also contains publishing functionality to generate, upload and maintain a web-site. This is a complete Emacs based solution for maintaining web-sites different from trgensit. I had developed trgensit in year 2003 (then implemented in VBScript), well before Org publishing was created.


Last change: 2024-09-27
© 2002-2024 Dr. Thomas Redelberger redetho(at)gmx.de