Sample Org-Mode File for Hugo

L. Larrabee Strow

1 Introduction

This is a sample org file for producing a hugo web page. What you should look at carefully is how you can easily get a latex pdf output from this file by some very small and easy changes to the code generating figures. This is partially required since you cannot show .pdf files in-line with html, and figures using .pdf files look better in LaTeX output pdfs.

2 Figures (NEW WAY)

Org-mod does not know about Hugo, and that is reflected in how org-mode handles links.

The Hugo website view of both the "content" and "static" directories are at the Hugo top-level (they are combined). You can put limited figures in the static directory, but I don't want to fill-up the aslhugo git repo with figures (maybe this will change). For example, if you want a photo in your home page, put it in /static/hepplewhite/hepplewhite.jpg as an example. Then refer to it as [[/hepplewhite/hepplewhite.jpg]].

However, if we want to move to putting figures into the repo, we can do it as follows:

  • Make a directory with the same name as the org file, without the .org
  • Put your figures there, here called test.png
  • Refer to them with the relative path [[./test.png]]

Below I have now inserted the figure into the web page with a caption. I've included in the .org file syntax to control the figure width in the latex output as well.


Figure 1: A test figure.

3 Figures (OLD WAY)

Absolute URLs for figures can also be used.


Figure 2: Another caption for a figure on the ASL web site.

4 Orgmode Syntax

Code blocks, examples, prose, etc can be done a number of ways, two ways are shown below, see the source code of this document to see how these are done. Here is the rendering of an in-line code block. Is was done by enclosing the code block in =, as shown below where we repeat these last two sentences. #+END_SRC Note that the code block rendering will render carriage return, line feeds if they exist.

To render a matlab file (or latex, or html, etc) just use the backticks, and put the language right after the first set of three backticks. I would generally put language of "text" for notes, or if you do not want automatic colorization, etc. I can't figure out how to render a code block inside a code block, so look at the source of this file (/strow/ to see how this works.

% A matlab code snippet
for i=1:n
   a(i) = fact(i);

5 Math

To include a mathematical formula in-line using org-mode, just use normal latex syntax. Here is some in-line math a = α × β. For latex equations or displaymath just type them in the file as usual:

\begin{equation} \frac{n!}{k!(n-k)!} = \binom{n}{k}. \end{equation}

6 Lists

Lists work out of the box (enumerated or itemize)

  1. Just write a Markdown document, and sprinkle your LaTeX code snippets in between.
  2. Save the document with an .md suffix.
  3. Run the Pandoc conversion:
  4. Just write a Markdown document, and sprinkle your LaTeX code snippets in between.
  5. Save the document with an .md suffix.
    • nested list
  6. Run the Pandoc conversion:

There is a css formating bug somewhere that puts in the extra space after a nested list.

7 Tables

Hugo is limited to simple tables, org-mode provides much more flexibility. Here is the Hugo (default markdown) table syntax, followed by it's html rendering. The code block is fancier than it's rendering…

Here is a table using org-mode, followed by the code. Unfortunately, there is a bug in org-mode that doesn't put a carriage-return, line-feed after a left-justified table, so avoid those for now.

Table 1: The table caption
Name Age
Bob 27
Alice 23

The code. If you don't center the table, the rendering goes bad.

8 Table of Contents

It is not possible to automatically produce a table of contents with org-mode that can be passed to Hugo. For some reason, when you set body-only to true (C-e C-b) org-mode will not output the table of contents, even if you request it. Although tedious, you can just out put the full (body-only false) html, grab the table of content html code, and then insert that into your org file right before the #END_EXPORT. Just wait until you are done, or have your sections done, and this will work.

9 Fenced Matlab Code Block

Here is an example of a Matlab fenced code block. Note, you can do ascii tables inside code block if you like. Looks at the source for this file to see how to do this.

% A matlab code snippet
%   rad2bt - translate radiance to brightness temperature
%   bt = rad2bt(fr, rad);
%   fr  - n-vector of wavenumbers, cm-1
%   rad - n x k array of radiances, mW/m2 per strad
%   bt  - n x k array of brightness temps, K
%   H. Motteler

function bt = rad2bt(fr, rad);

% Constants; values from NIST (CODATA98)
c = 2.99792458e+08;  % speed of light      299 792 458 m s-1
h = 6.62606876e-34;  % Planck constant     6.626 068 76 x 10-34 J s
k = 1.3806503e-23;   % Boltzmann constant  1.380 6503 x 10-23 J K-1

% Compute radiation constants c1 and c2
c1 = 2*h*c*c * 1e+11;
c2 = (h*c/k) * 100;

% the scalar calculation, for reference
% bt = c2 * fr / log(1 + c1 * fr^3 / rad)

% LLS cut a bunch out here!

% do the vectorized calculation
bt = c2 * (fr * ones(1,j)) ./ log(1 + c1 * (fr.^3 * ones(1,j)) ./ rad);

% restore rad original shape
bt = reshape(bt, d2);

comments powered by Disqus