A short introduction to Org-mode and Hugo

Basic understanding of GNU Emacs is necessary. If you are new to this, then get GNU Emacs and follow its marvelous built-in tutorial, which is accessed by typing C-h t, that is, Ctrl-h followed by t. Once you have finished this task, please create a file named example.org and populate it with the following code, select it, and execute the selected region using M-x eval-region.

(setq org-image-actual-width nil)

(setq org-format-latex-options (plist-put org-format-latex-options :scale 3.0))

(org-babel-do-load-languages
 'org-babel-load-languages
 '((python . t)))

(setq org-babel-python-command "python3")

A line starting with a # followed by a space is an Org comment. For example,

# I will not be exported since I am a comment.
# I am another comment.

More information: https://orgmode.org/manual/Comment-Lines.html

The above text "Headlines" is a web browser rendering of an HTML export of a top-level headline in Org-mode. Top-level headlines in Org-mode are created by putting a * symbol in front of the headline text.

* This is a top level headline

Lower level headlines are added by adding more * symbols

** Second level
*** Third level 1
    Some exciting content
*** Third level 2
    More interesting content

The following is an example rendering of the above

TODO items are just headlines that start with the word TODO. When the task is complete it can be marked as DONE by changing the state. Use C-c C-t to change the TODO state.

** TODO install FreeBSD on server2
** DONE install Debian on server1

More information: https://orgmode.org/manual/TODO-Basics.html

italic, underlined, bold, verbatim, code, strike-through

is an example rendering of

/italic/, _underlined_, *bold*, =verbatim=, ~code~, +strike-through+

More information: https://orgmode.org/manual/Emphasis-and-Monospace.html

• Unordered list items start with -, +, or * as bullets.

• Ordered list items start with a number followed by either a . or a ).

For example,

1. Editors
   - Emacs
   - Vim
2. Operating systems
   - Linux
   - Windows
3. Languages
   - C
   - Python

which renders here as

1. Editors

   • Emacs

   • Vim

2. Operating systems

   • Linux

   • Windows

3. Languages

   • C

   • Python

More information: https://orgmode.org/manual/Plain-Lists.html

type ----- (5 dashes) to create a horizontal rule, which renders here as

More information: https://orgmode.org/manual/Horizontal-Rules.html

Add [ ] to the start of a plain list item to add checkbox functionality. Note the space between the [, ].

** TODO Study progress [66%]
  - [X] Algebra
  - [ ] Combinatorics
  - [X] Geometry

** DONE Gotta Catch 'Em All! [3/3]
  - [X] Charmander
  - [X] Bulbasaur
  - [X] Squirtle

Use C-c C-c to toggle checkboxes. Insert [/] or [%] as above to indicate progress.

More information: https://orgmode.org/manual/Checkboxes.html

Superscripts and subscripts are denoted using ^ and _ respectively. Use C-c C-x \ to render the superscripts and subscripts in Emacs. The following are examples of web rendering of Org-mode superscripts and subscripts.

• e^{x} is rendered as e^x

• x_{n} is rendered as x_n

To create the following table

| Name    | Type      | Color  |
|---------+-----------+--------|
| Apple   | Fruit     | Red    |
| Cabbage | Vegetable | Green  |
| Banana  | Fruit     | Yellow |

type

|Name|Type|Color|
|-

followed by TAB, or type

|Name|Type|Color

followed by C-c RET; press RET again to add lines; use C-c C-c to re-align.

The following is a web rendering of the table after some application of CSS.

More information: https://orgmode.org/manual/Tables.html

Place your text in #+BEGIN_VERSE, #+END_VERSE, or #+BEGIN_QUOTE, #+END_QUOTE or #+BEGIN_CENTER, #+END_CENTER blocks. For example

#+BEGIN_QUOTE
I am the punishment of God. If you had not committed great sins, God would not have sent
a punishment like me upon you. ---Chinggis Khaan
#+END_QUOTE

Let's see how that renders here after some application of CSS!

I am the punishment of God. If you had not committed great sins, God would not have sent a punishment like me upon you. —Chinggis Khaan

For an example demonstrating the centering of an image using #+BEGIN_CENTER, #+END_CENTER, goto Images.

More information: https://orgmode.org/manual/Paragraphs.html

Images, tables, $\LaTeX$ equations, code blocks, etc. can be captioned by inserting a line that says #+CAPTION: your-caption-text immediately before them. After applying some CSS to the tables, the following code

#+BEGIN_CENTER
#+CAPTION: *2022 census data*
| Name          | Age |
|---------------+-----|
| Ash Ketchum   |  10 |
| Ash's Pikachu |  30 |
#+END_CENTER

gives us

Optionally, one can use #+CAPTION[Short caption]: Longer caption.

More information: https://orgmode.org/manual/Captions.html

Links in Org-mode are created using the syntax [[LINK][DESCRIPTION]] or just [[LINK]].

- [[https://www.lmfdb.org/]]
- [[https://pubs.opengroup.org/onlinepubs/9699919799/][POSIX]]

[[file:/home/soumendra/images/ramanujan.jpg]]
[[/home/soumendra/images/ramanujan.jpg]]

[[file:images/ramanujan.jpg]]
[[./images/ramanujan.jpg]]

* Images
  :PROPERTIES:
  :CUSTOM_ID: imgs
  :END:

[[#imgs][goto Images]]

Define a footnote by using [fn:your-footnote-name]; for example,

The internet archive[fn:1] contains a large database of old books.
[fn:1] https://archive.org/

renders as

The internet archive¹ contains a large database of old books.

C-c C-c jumps between footnote definition and reference in Org-mode.

More information: https://orgmode.org/manual/Creating-Footnotes.html

All the displayed Org code in this document is created by placing the Org code between #+BEGIN_SRC org, #+END_SRC. In general, #+BEGIN_SRC language-name, #+END_SRC is used. Use C-c C-c to evaluate the current code block. For example,

# Use return statement.
# Entire source block will get indented and used as the body of main().
#+BEGIN_SRC python
def factorial(n):
    if n == 0:
        return(1)
    else:
        return(n*factorial(n-1))

return(factorial(5))
#+END_SRC

#+RESULTS:
: 120

is rendered here as

def factorial(n):
    if n == 0:
        return(1)
    else:
        return(n*factorial(n-1))

return(factorial(5))

120

More information: https://orgmode.org/manual/Working-with-Source-Code.html

Also see https://orgmode.org/worg/org-contrib/babel/languages/index.html for language support.

Add a link to an image as follows.

#+ATTR_ORG: :width 500
[[file:fiber_product.svg]]

This renders in your web browser as

Type C-c C-x C-v in Org-mode to toggle inline display.

We can also customize HTML export options as follows.

#+BEGIN_CENTER
#+CAPTION: *Commutative diagram*
#+ATTR_HTML: :width 250px
[[file:fiber_product.svg]]
#+END_CENTER

This exports as

We can also have clickable HTML link images as follows.

#+BEGIN_CENTER
#+CAPTION: *Commutative diagram (clickable link image)*
[[https://en.wikipedia.org/wiki/Pullback_(category_theory)][file:fiber_product.svg]]
#+END_CENTER

This renders as

We can rotate an image by adding some CSS as follows.

#+BEGIN_CENTER
#+CAPTION: *Commutative diagram (rotated)*
#+ATTR_HTML: :style transform: rotate(180deg);
[[file:fiber_product.svg]]
#+END_CENTER

This renders as

More information: https://orgmode.org/manual/Images.html

The following is the Org code for a $\LaTeX$ code block; it starts with #+BEGIN_SRC latex and ends with #+END_SRC.

#+BEGIN_SRC latex
$e^{i\pi} + 1 = 0$
#+END_SRC

It web renders as

$e^{i\pi} + 1 = 0$

The following is the Org code for a $\LaTeX$ fragment; it does not contain the #+BEGIN_SRC latex, #+END_SRC.

$e^{i\pi} + 1 = 0$

If you have a working $\LaTeX$ installation and dvipng , dvisvgm , or ImageMagick installed, $\LaTeX$ fragments can be processed to produce images of the typeset expressions to be used for inclusion while exporting to HTML or for inline previewing within Org-mode; toggle inline preview of $\LaTeX$ fragments in Org-mode using C-c C-x C-l.

$\LaTeX$ fragments can alternatively be web rendered using MathJax or KaTeX . For example, the above $\LaTeX$ fragment is rendered by MathJax as follows.

$e^{i\pi} + 1 = 0$

More information: https://orgmode.org/manual/Embedded-LaTeX.html and https://orgmode.org/manual/LaTeX-Export.html

In Emacs, you can use C-c C-e h h to export your Org file to an HTML file or C-c C-e h o to export to an HTML file and open in a web browser. Alternatively, you can follow this short article by Peter Prevos on how to generate a static website using Org-mode and Hugo. Note that alongside Org, Hugo also supports generating HTML from Markdown .

To embed raw HTML in Org-mode, type your HTML between #+BEGIN_EXPORT html and #+END_EXPORT. For example,

#+BEGIN_EXPORT html
<svg height="100" width="100">
  <circle cx="50" cy="50" r="40" fill="#2b4e77" />
  <circle cx="50" cy="50" r="30" fill="white" />
  <circle cx="50" cy="50" r="20" fill="#2b4e77" />
  <circle cx="50" cy="50" r="10" fill="white" />
</svg>
#+END_EXPORT

renders as

More information: https://orgmode.org/manual/HTML-Export.html

We will visit some specific examples of Hugo shortcodes in this note. To embed a YouTube video having ID fZYWwSIvYL0, type

{{< youtube id="fZYWwSIvYL0" >}}

which will render as

A similar approach works for other video sharing sites such as Vimeo. Try

{{< vimeo 146022717 >}}

Hugo also makes it easy to embed GitHub gists, Instagram photos, and tweets using shortcodes! For example,

{{< gist spf13 7896402 "img.html" >}}

renders here as

Instead of inserting images using Org-mode, we can also use Hugo shortcodes; for instance,

#+BEGIN_CENTER
{{< figure src="/images/fiber_product.svg" title="Fiber product" >}}
#+END_CENTER

produces the following output

To make links open in a new browser tab, one needs to add target="_blank" to their <a> HTML element; this can be done in Org-mode by adding #+ATTR_HTML: :target _blank before a link, but the Hugo exporter seems to have a bug that adds the target="_blank" to a <p> element containing the <a> HTML element. One can however create shortcodes to add this functionality. For example, creating the file /themes/your-theme-name/layouts/shortcodes/ant.html with the following content

<a href="{{ index .Params 0 | safeURL }}" target="_blank" >{{ index .Params 1 | safeHTML }}</a>

allows one to write

{{< ant "https://www.wikipedia.org/" "WIKIPEDIA" >}}

to get

WIKIPEDIA

More information: https://gohugo.io/content-management/shortcodes/ and https://gohugo.io/templates/shortcode-templates/

After setting enableEmoji to true in your Hugo site's configuration file, you can type heart in between two : symbols (no spaces) to render a ❤️ emoji. This contains many more such examples.

To add Font Awesome functionality to your Hugo website, add the following to the <head> block.

<link rel="preload" href="https://use.fontawesome.com/releases/v6.2.1/css/all.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="https://use.fontawesome.com/releases/v6.2.1/css/all.css"></noscript>

Next, create the file /themes/your-theme-name/layouts/shortcodes/awe.html with the following content.

<i class="{{ range .Params }}{{ . }} {{ end }}"></i>

Now, type the following in your Org file.

*I love to play the* {{< awe fa fa-guitar >}}

This is rendered here as

I love to play the

I hope you have a wonderful experience with GNU Emacs, Org-mode, and Hugo! 👍

More information: https://gohugo.io/functions/emojify/