This article offers a sample of basic Org Mode syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme. These are rendered slightly differently to those when creating content using Markdown, so this page acts as a comparison to the Markdown Syntax page.
This theme has some tweaks in the CSS to try and make the basic usage of Org Mode syntax produce results similar to that from the Markdown Renderer. See notes at Differences Between Org Mode and Markdown
In this theme there's a Org Mode pageBundle archetype you can use, simply:
$ hugo new --kind org-post /posts/my-new-post-name
and you're ready to go.
Headings
The following HTML <h1> - h6 elements represents six levels of section headings. <h1> is the highest section level while <h6> is the lowest.
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Images
Paragraph
Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.
Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.
Blockquotes
The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a proceeding #+CAPTION: element. You can insert a quote block with the usual template shortcut C-c C-, q.
Blockquote without attribution
Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use org-mode syntax within a blockquote.
Blockquote with attribution
A witty saying proves nothing.
Tables
Tables are a part of the org-mode spec, and awesome. Hugo supports them out-of-the-box.
| Name | Age |
|---|---|
| Bob | 27 |
| Alice | 23 |
Inline Org Mode within Tables
| Org Mode Syntax | Rendered |
|---|---|
/Italic/ | Italic |
*Bold* | Bold |
_Underline_ | Underline |
~Code~ | Code |
=Verbatum= | Verbatum |
+Strikethrough+ |
Code Blocks
Code block within a source code block
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>Code block with Hugo's internal highlight shortcodes
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Example HTML5 Document</title>
</head>
<body>
<p>Test</p>
</body>
</html>
Code that is wider that the column width
echo "What do you mean this line of code is excessivly long and doesn't wrap well?"List Types
Ordered List
- First item
- Second item
- Third item
Unordered List
- List item
- Another item
- And another item
Nested List
Fruit
- Apple
- Orange
- Banana
Dairy
- Milk
- Cheese
Summary with Details
Using the shortcode details gives you the following, but you have to wrap it in a begin_export html block and then write HTML for it to work.
A short summary
And then a longer explanation of how to use it in the HugoMods Docs...but there is another way, which seems a little sneaky
Another summary
Where you can write org-mode syntax as you want! without having to write everything in HTML.
That's by having two #+begin_export html sections, the first containing the opening <detail> tag with the summary, and then a later section with the closing tag, and in between just write org-mode, as below:
#+begin_export html
<details>
<summary>This is another summary</summary>
#+end_export
Where you can write ~org-mode~ syntax /as you want!/ without having to write everything in HTML.
#+begin_export html
</details>
#+end_exportOther Elements
If you want to use other features from HTML for which there isn't an org-mode equivalent, you can just write the HTML in a #+begin_export html block, which acts as a work-around. For example the abbreviation expansion as a hover over below:
Equations can be done directly from org-mode:
H2O
Xn + Yn = Zn
(Acts as if #+OPTIONS: ^:{} is set in the file parameters)
Press CTRL+ALT+Delete to end the session.
But again the <mark> tag requires the HTML export hack, otherwise it just looks like this:
Most <mark>salamanders</mark> are nocturnal, and hunt for insects, worms, and other small creatures.
and not like:
Most salamanders are nocturnal, and hunt for insects, worsma dn other small creatures.Differences Between Org Mode and Markdown
Org Mode has different goals to Markdown, Org Mode is more of an interactive document format, than a syntax for marking up text, but it can be used for that as well.
For the fine details on how org-mode files are rendered, see the Go-Org page for the details. They will be rendered slightly differently to those written in Markdown. If you want more precision then you're probably best using something like Ox-Hugo in your workflow, or even Org Mode's own HTML exporter.
Below are a few pointers for using this theme with Org Mode.
Images
Images without captions should be treated the same, but if you add a caption it's rendered as a <figure>, and so rendered slightly smaller, as below.
Lists
Lists of all types seem to be rendered with a bonus <p> in them, as shown below, this is negated by setting display: inline; in the style sheet.
<ol>
<li><p>First item</p></li>
<li><p>Second item</p></li>
<li><p>Third item</p></li>
</ol>Footnotes
From Markdown footnotes are rendered as an ordered2 list. For Org Mode input it's a series of <div>. Like with the lists we just inline the display to compact it a bit, and increase the size of the reference number, as otherwise it's tiny and hard to click. The little 'back' arrow does not appear automatically in org-mode footnotes, but they can be added by adding a link with a relref shortcode and the arrow character as follows (but without the space between the first two curly brackets.
[[#footnote-reference-NUMBER][↩]]
Link To Headings and other articles
To link to another page, use the Hugo short code for Links and Cross References within the usual double square bracket Org Mode syntax.
This is a bit of a pain. The usual Org Mode syntax of something like [[*Headings]] to jump back up to the Images heading doesn't work. All the headings are given ids in the format "headline-xx", which you can then use in the usual link with as [[#headline-XX] [text]], but that requires rendering the page at least once and then not adding headlines in between, not great.
Instead add a CUSTOM_ID property to the headline:
* My Headline
:PROPERTIES:
:CUSTOM_ID: my-headline
:END:and then link with [[#my-headline][My Headline]]. This will then work for the rendered webpage, but sadly not within Org Mode itself.