Org Special Blocks

Special #+begin_.. .. #+end_.. constructs recognized by Ox-hugo.

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

You may choose to have a CSS snippet like above either inline in the exported Markdown, or in your website’s CSS file.

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:

Content inside something.

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:

This text will be in red.

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 &sum;, foo_{bar} will be replaced with foo<sub>bar</sub>, and so on.

But many times, the user might want to keep the contents of the special block as-as, in its raw form. 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" to the customization variable org-hugo-special-block-raw-content-types.

By default , "katex" 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.


If the "FOO" block type is one of types in org-blackfriday-html5-inline-elements (see HTML5 inline elements) or org-html-html5-elements (see HTML5 block elements) and you need to export the raw contents for that, it needs to be added to org-blackfriday-special-block-raw-content-types.

By default, "video" and "audio" are added to org-blackfriday-special-block-raw-content-types.

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>
Code Snippet 1: Sourcing TikZJax scripts in HTML head

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

#+begin_tikzjax
\draw (0,0) circle (1in);
#+end_tikzjax
Code Snippet 2: Example use of tikzjax special block

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

10 Whitespace Trimming #

Whitespace trimming around exported Org Special Blocks is supported.

Whether the whitespace before the exported block, after the block, or at both spaces is trimmed is decided by using some special markers after the special block name.

< suffix
Trim whitespace only before the block.
> suffix
Trim whitespace only after the block.
<> suffix
Trim whitespace both before and after the block.

By default if a special block tag is not recognized as an HTML block or inline element, or as a Hugo shortcode, it defaults to exporting with <div> tags. But if any of the whitespace trimming markers is used in a special block, it will export with <span> tags.

10.1 No trimming #

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 before and after the mark special block using <> suffix #

Below Org block:

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

exports and renders as:

line 1 abc def line 2

10.3 Whitespace trimmed only before the mark special block using < suffix #

Below Org block:

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

exports and renders as:

line 1 abc def

line 2

10.4 Whitespace trimmed only after the mark special block using > suffix #

Below Org block:

line 1
#+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_sidenote
abc def
#+end_sidenote
line 2

export with <div> tags by default:

1
2
3
4
5
6
7
8
9
line 1

<div class="sidenote">

abc def

</div>

line 2

and render as:

line 1

abc def

line 2

But if a trimming marker (any of them) is detected, it switches to using the <span> tag. So the below Org block:

line 1
#+begin_sidenote<>
abc def
#+end_sidenote<>
line 2

will export to:

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

and render as:

line 1 abc def line 2

Fork me on GitHub