# 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


## 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!
"""


## 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 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

An example special block of type 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

An example special block of type 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

An example special block of type 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))))

An example of updating a special block type's :raw property to 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>

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

Example use of tikzjax special block

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.

For the types not specified in org-hugo-special-block-type-properties, the default behavior is like that of '(:trim-pre nil :trim-post nil).

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.

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 either pre or post trimming options are detected for a special block, it will export with <span> tags.

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

and renders as:

line 1

abc def

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

 1  line 1 abc def line 2