Org Special Blocks

1 HTML5 inline elements #

Org special blocks created using the HTML tags defined in org-blackfriday-html5-inline-elements will export as inline HTML.

#+begin_INLINETAG
something
#+end_INLINETAG

will export as:

<INLINETAG>something</INLINETAG>

For example, mark is one of those inline elements. So,

#+begin_mark
This sentence is marked.
#+end_mark

will export as:

<mark>This sentence is marked.</mark>

and render as:

This sentence is marked.

2 HTML5 block elements #

Org special blocks created using the HTML tags defined in org-html-html5-elements will export as HTML blocks wrapped by those tags.

#+begin_BLOCKTAG
something
#+end_BLOCKTAG

will export as:

<BLOCKTAG>

  something

</BLOCKTAG>

For example, aside is one of those HTML5 block elements. So,

#+begin_aside
Some content for the ~aside~ block.
#+end_aside
We can even make the ~aside~ block /aside-like/ with
[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside][this little CSS]].

will export as:

<aside>

Some content for the `aside` block.

</aside>
We can even make the `aside` block _aside-like_ with
[this little CSS](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside).

and render as:

We can even make the aside block aside-like with this little CSS.

3 Details and Summary #

details is one of the HTML5 block elements, but it is treated as a separate case because we also need to support the nested inline summary tag in there.

#+begin_details
#+begin_summary
This is summary.
#+end_summary
Here are the details.
#+end_details

See Details and Summary .

4 HTML Attributes #

HTML attributes can be added to the first tag of any of the above Special Blocks using the #+attr_html syntax. The class attribute, for instance, is very handy.

For example, if we want the marked text to have red foreground color, we can do:

#+begin_export html
<style>
  .red {
    color: red;
  }
</style>
#+end_export
#+attr_html: :class red
#+begin_mark
This marked text's foreground is red.
#+end_mark

and that will render as:

This marked text’s foreground is red.

5 Description #

The #+begin_description .. #+end_description special block can be used to set the description front-matter variable.

This allows the description to be written in a well-formatted fashion with Org markup and it can be multi-line too.

As an example:

#+begin_description
Here is my *post summary*.

And this can be over /multiple lines/ too!
#+end_description

Above will export as this in the TOML front matter:

description = """
  Here is my **post summary**.

  And this can be over _multiple lines_ too!
  """

6 Hugo Paired Shortcodes #

See HUGO_PAIRED_SHORTCODES .

7 Other Special Blocks (div tags) #

If the Special Block tag used isn’t found in org-blackfriday-html5-inline-elements or org-html-html5-elements, that block exports just as an HTML div block.

#+begin_SOMETHING
Content inside something.
#+end_SOMETHING

exports as:

<div class="SOMETHING">

Content inside something.

</div>

and renders as:

If we want to reuse the .red CSS rule defined above, we can type:

#+begin_red
This text will be in red.
#+end_red

which will render as:

See the Whitespace Trimming section if you need to export with <span> tags instead of <div> tags.

8 Raw Org contents #

By default, the content inside the Org special blocks will have some default processing done by the exporter – Org entities like \sum will be replaced by its HTML entity ∑, foo_{bar} will be replaced with foo<sub>bar</sub>, and so on.

But the user might want to keep the contents of the special block as-as, in its raw form, for some special block types. If the user wants to do this for a special block of the type FOO:

#+begin_FOO
Some content
#+end_FOO

, they need to add ("FOO" . (:raw t)) to the customization variable org-hugo-special-block-type-properties.

By default , ("katex" . (:raw t)) is added to this list. So when using a special block like,

#+begin_katex
E = -J \sum\_{i=1}^N s\_i s\_{i+1}
#+end_katex

, the equation in the content of that special block: E = -J \sum\_{i=1}^N s\_i s\_{i+1} will be exported to Markdown as-is.

As an another example, if you have a special block for the Mermaid diagramming markup, and you need to write special blocks like below which has one of the HTML reserved characters (>),

#+begin_mermaid
flowchart TD
    Start --> Stop
#+end_mermaid

you will need to export the content of that shortcode in raw Org. To do so, you can add something like this to your config:

(with-eval-after-load 'ox-hugo
  (add-to-list 'org-hugo-special-block-type-properties '("mermaid" . (:raw t))))

9 TikZJax #

ox-hugo supports exporting raw tikz snippet to Markdown which can be rendered to images using the TikZJax project.

To use this feature, ensure that the TikZJax scripts are loaded in the HTML <head> (you will need to tweak your site’s Hugo template for that):

<link rel="stylesheet" type="text/css" href="https://tikzjax.com/v1/fonts.css">
<script src="https://tikzjax.com/v1/tikzjax.js"></script>

Then simply put tikz snippets in the Org source like so:

#+begin_tikzjax
\draw (0,0) circle (1in);
#+end_tikzjax

Search the ox-hugo test site for “tikzjax” examples.

10 Whitespace Trimming #

The default whitespace trimming around exported Org Special Blocks can be configured by setting the :trim-pre and :trim-post properties for specific special block types in the org-hugo-special-block-type-properties customization variable.

• If :trim-pre is set to t, whitespace before the block is removed.
• If :trim-post is set to t, whitespace after the block is removed.

Here’s an example of specifying trimming options for a new special block type “sidenote”:

(with-eval-after-load 'ox-hugo
  (add-to-list 'org-hugo-special-block-type-properties '("sidenote" . (:trim-pre t :trim-post t))))

Here’s an example of overriding properties for one of the types, say “mark”:

(with-eval-after-load 'ox-hugo
  (setcdr (assoc "mark" org-hugo-special-block-type-properties) '(:trim-pre t :trim-post nil)))

Or, you can M-x customize-group, select org-select-hugo and tweak this variable in that UI.

The default values set this way can be overridden in the Org file by using the #+header: keyword above the special blocks. Below examples demonstrate the usage of this #+header keyword.

By default (in org-hugo-special-block-type-properties), the “mark” special block type has :trim-pre and :trim-post both set to t, because typically the <mark> is used to highlight words and phrases mid-sentence and we wouldn’t want to introduce a paragraph break before or after a <mark> element.

10.1 Whitespace trimmed before and after the mark special block (default) #

Below Org block:

line 1
#+begin_mark
abc def
#+end_mark
line 2

exports and renders as:

line 1 abc def line 2

10.2 Whitespace trimmed only before the mark special block #

Below Org block:

line 1
#+header: :trim-post nil
#+begin_mark
abc def
#+end_mark
line 2

exports and renders as:

line 1 abc def

line 2

10.3 Whitespace trimmed only after the mark special block #

Below Org block:

line 1
#+header: :trim-pre nil
#+begin_mark
abc def
#+end_mark
line 2

exports and renders as:

line 1

abc def line 2

10.4 No trimming #

Below Org block:

line 1
#+header: :trim-pre nil :trim-post nil
#+begin_mark
abc def
#+end_mark
line 2

exports and renders as:

line 1

abc def

line 2

10.5 Use <span> tag if trimming detected #

Below Org block:

line 1
#+begin_foo
abc def
#+end_foo
line 2

exports with <div> tags by default:

1
2
3
4
5
6
7
8
9

line 1

<div class="foo">

abc def

</div>

line 2

and renders as:

line 1

line 2

But if any of the trimming options are set in the header, it switches to using the <span> tag. So the below Org block:

line 1
#+header: :trim-pre t :trim-post t
#+begin_foo
abc def
#+end_foo
line 2

will export to:

1

line 1 <span class="foo">abc def</span> line 2

and render as:

line 1 abc def line 2