<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-us"><generator uri="https://gohugo.io/" version="0.101.0">Hugo</generator><title type="html">special-block on A Scripter's Notes</title><subtitle type="html">Emacs, scripting and anything text oriented.</subtitle><link href="https://scripter.co/tags/special-block/" rel="alternate" type="text/html" title="HTML"/><link href="https://scripter.co/tags/special-block/index.xml" rel="alternate" type="application/rss+xml" title="RSS"/><link href="https://scripter.co/tags/special-block/atom.xml" rel="self" type="application/atom+xml" title="Atom"/><link href="https://scripter.co/tags/special-block/jf2feed.json" rel="alternate" type="application/jf2feed+json" title="jf2feed"/><updated>2026-04-22T08:24:58-04:00</updated><author><name>Kaushal Modi</name><email>kaushal.modi@gmail.com</email></author><id>https://scripter.co/tags/special-block/</id><entry><title type="html">Sidenotes using ox-hugo</title><link href="https://scripter.co/sidenotes-using-ox-hugo/?utm_source=atom_feed" rel="alternate" type="text/html"/><link href="https://scripter.co/sidenotes-using-only-css/?utm_source=atom_feed" rel="related" type="text/html" title="Sidenotes using only CSS"/><id>https://scripter.co/sidenotes-using-ox-hugo/</id><author><name>Kaushal Modi</name></author><published>2022-02-05T18:14:00-05:00</published><updated>2022-02-05T18:14:00-05:00</updated><content type="html"><![CDATA[<blockquote>Adding sidenotes using a Hugo shortcode and ox-hugo.</blockquote><div class="ox-hugo-toc toc">
<div class="heading">Table of Contents</div>
<ul>
<li><a href="#hugo-shortcode">Hugo shortcode</a></li>
<li><a href="#org-mode-special-block">Org mode special block</a></li>
<li><a href="#summary">Summary</a>
<ul>
<li><a href="#one-time-configuration">One-time configuration</a></li>
<li><a href="#org-special-block-sidenote">Org special block: <code>sidenote</code></a></li>
</ul>
</li>
</ul>
</div>
<!--endtoc-->
<p>The main focus of my <a href="/sidenotes-using-only-css/"> previous post </a> was the CSS for sidenotes. I also
showed the companion HTML wrapper needed for that CSS to work. Here it
is again for convenience:</p>
<p><a id="code-snippet--sidenote-html-example"></a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">&#34;sidenote-number&#34;</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">&lt;</span><span class="nt">small</span> <span class="na">class</span><span class="o">=</span><span class="s">&#34;sidenote&#34;</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    sidenote content
</span></span><span class="line"><span class="cl">  <span class="p">&lt;/</span><span class="nt">small</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
</span></span></code></pre></div><div class="src-block-caption">
  <span class="src-block-number"><a href="#code-snippet--sidenote-html-example">Code Snippet 1</a>:</span>
  Sidenote HTML example
</div>

<h2 id="hugo-shortcode">Hugo shortcode&nbsp;<a class="headline-hash no-text-decoration" href="#hugo-shortcode">#</a></h2>


<p>Now .. You might be thinking that it&rsquo;s not too practical to type that
thing for each new sidenote. And you are right! That&rsquo;s where we use
the <a href="https://gohugo.io/content-management/shortcodes/">Hugo Shortcode</a> feature.
<span class="sidenote-number"><small class="sidenote">
<em>Hugo Shortcodes</em> are like Org Macros that are typically used to
insert some HTML template around the user entered content.
</small></span>
If you look at the <a href="#code-snippet--sidenote-html-example">above snippet</a>, the outer <code>span</code> and <code>small</code> tags
are just HTML boilerplate that the user will need to type mechanically
around each sidenote. So the shortcodes are perfect for solving this
annoyance.</p>
<p>If we design a <em>paired</em> shortcode for this, the above HTML example
will change to below:</p>
<p><a id="code-snippet--sidenote-shortcode-use"></a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-md" data-lang="md"><span class="line"><span class="cl">{{% sidenote %}}
</span></span><span class="line"><span class="cl">sidenote content
</span></span><span class="line"><span class="cl">{{% /sidenote %}}
</span></span></code></pre></div><div class="src-block-caption">
  <span class="src-block-number"><a href="#code-snippet--sidenote-shortcode-use">Code Snippet 2</a>:</span>
  Example use of the <code>sidenote</code> shortcode
</div>
<p>As you can see, this shortcode
<span class="sidenote-number"><small class="sidenote">
This is a markdown-rendering shortcode i.e. a shortcode with <code>{{​% .. %}}</code> instead of <code>{{​&lt; .. &gt;}}</code>. So the insides of this shortcode
will passed on to the Hugo Markdown renderer.
</small></span>
<em>now</em> enables the user to
<mark>focus on content writing</mark> than on writing boilerplate HTML. And the definition of that shortcode
is pretty simple as well:</p>
<p><a id="code-snippet--sidenote-shortcode"></a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">&#34;sidenote-number&#34;</span><span class="p">&gt;&lt;</span><span class="nt">small</span> <span class="na">class</span><span class="o">=</span><span class="s">&#34;sidenote&#34;</span><span class="p">&gt;</span>{{ .Inner }}<span class="p">&lt;/</span><span class="nt">small</span><span class="p">&gt;&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
</span></span></code></pre></div><div class="src-block-caption">
  <span class="src-block-number"><a href="#code-snippet--sidenote-shortcode">Code Snippet 3</a>:</span>
  "sidenote.html" Hugo shortcode
</div>
<p>The only Hugo-templating syntax used here is <code>{{ .Inner }}</code>. You can
read more about it <a href="https://gohugo.io/templates/shortcode-templates/#inner">here</a>, but the <em>tl;dr</em> is that the <code>.Inner</code> holds
whatever content the user entered <em>inside</em> the <code>{{​% sidenote %}}</code> and
<code>{{​% /sidenote %}}</code> tags.</p>
<p>Once you save <a href="#code-snippet--sidenote-shortcode">that shortcode snippet</a> to a <code>layouts/sidenote.html</code> file
in your Hugo site&rsquo;s directory, you are ready to use it.</p>
<div class="verse">
<p>        🛑 But wait! 🛑<br /></p>
</div>

<h2 id="org-mode-special-block">Org mode special block&nbsp;<a class="headline-hash no-text-decoration" href="#org-mode-special-block">#</a></h2>


<p>It would be a shame to populate the Org source of this blog with
Hugo-specific shortcodes when I am using <a href="https://ox-hugo.scripter.co/">ox-hugo</a> 😄.</p>
<p>So instead, we just use the plain-old Org special blocks and tell
<em>ox-hugo</em> that this &ldquo;sidenote&rdquo; special block be exported as a
markdown-rendering Hugo shortcode. I do that by just placing this at
the top of my Org file
<span class="sidenote-number"><small class="sidenote">
See the <a href="https://ox-hugo.scripter.co/doc/shortcodes/#hugo-paired-shortcodes">Hugo Paired Shortcodes</a> section in the <em>ox-hugo</em> manual to learn
more about this.
</small></span>
:</p>
<p><a id="code-snippet--sidenote-hugo-paired-shortcode"></a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-org" data-lang="org"><span class="line"><span class="cl"><span class="cs">#+hugo_paired_shortcodes</span><span class="c">: %sidenote</span>
</span></span></code></pre></div><div class="src-block-caption">
  <span class="src-block-number"><a href="#code-snippet--sidenote-hugo-paired-shortcode">Code Snippet 4</a>:</span>
  <code>#+hugo_paired_shortcodes</code> keyword for specifying "shortcode" special blocks
</div>
<p>.. and then writing a &ldquo;sidenote&rdquo; type Org special block:</p>
<p><a id="code-snippet--sidenote-special-block-use"></a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-org" data-lang="org"><span class="line"><span class="cl">abc
</span></span><span class="line"><span class="cl"><span class="c">#+begin_sidenote</span>
</span></span><span class="line"><span class="cl">example sidenote content
</span></span><span class="line"><span class="cl"><span class="c">#+end_sidenote</span>
</span></span><span class="line"><span class="cl">def
</span></span></code></pre></div><div class="src-block-caption">
  <span class="src-block-number"><a href="#code-snippet--sidenote-special-block-use">Code Snippet 5</a>:</span>
  Example use of the <code>sidenote</code> special block
</div>
<p>Normally, Org mode would insert a paragraph break where any Org block
(like that <em>sidenote</em> special block) is used. So above would render
as:</p>
<div style="color:green;" class="green">
<p>abc</p>
<p><span class="sidenote-number"><small class="sidenote">
example sidenote content
</small></span></p>
<p>def</p>
</div>
<p>But I am pretty sure that nobody would render sidenote references in
their main text as above&mdash;instead, below is more <em>normal</em> 😄.</p>
<div style="color:green;" class="green">
<p>abc
<span class="sidenote-number"><small class="sidenote">
example sidenote content
</small></span>
def</p>
</div>
<p>In that <em>normal</em> example of the sidenote, <em>ox-hugo</em> trims the whitespace
around the <em>sidenote</em> block. That is configured by customizing the
<code>org-hugo-special-block-type-properties</code> variable:</p>
<p><a id="code-snippet--sidenote-whitespace-trimming"></a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-emacs-lisp" data-lang="emacs-lisp"><span class="line"><span class="cl"><span class="p">(</span><span class="nb">with-eval-after-load</span> <span class="ss">&#39;ox-hugo</span>
</span></span><span class="line"><span class="cl">  <span class="p">(</span><span class="nv">add-to-list</span> <span class="ss">&#39;org-hugo-special-block-type-properties</span> <span class="o">&#39;</span><span class="p">(</span><span class="s">&#34;sidenote&#34;</span> <span class="o">.</span> <span class="p">(</span><span class="nb">:trim-pre</span> <span class="no">t</span> <span class="nb">:trim-post</span> <span class="no">t</span><span class="p">))))</span>
</span></span></code></pre></div><div class="src-block-caption">
  <span class="src-block-number"><a href="#code-snippet--sidenote-whitespace-trimming">Code Snippet 6</a>:</span>
  Whitespace trimming enabled by default for <code>sidenote</code> special blocks
</div>
<p>You can read more about this <em>whitespace trimming</em> feature in the
<a href="https://ox-hugo.scripter.co/doc/org-special-blocks/#whitespace-trimming">ox-hugo manual</a>.</p>

<h2 id="summary">Summary&nbsp;<a class="headline-hash no-text-decoration" href="#summary">#</a></h2>



<h3 id="one-time-configuration">One-time configuration&nbsp;<a class="headline-hash no-text-decoration" href="#one-time-configuration">#</a></h3>


<ol>
<li>Create and save a &ldquo;sidenote&rdquo; Hugo shortcode as shown <a href="#code-snippet--sidenote-shortcode">here</a>.</li>
<li>Configure <em>ox-hugo</em> to export &ldquo;sidenote&rdquo; special block as a
markdown-rendering shortcode.</li>
<li>Configure whitespace to be trimmed around those blocks using
<code>org-hugo-special-block-type-properties</code> customization variable.</li>
</ol>

<h3 id="org-special-block-sidenote">Org special block: <code>sidenote</code>&nbsp;<a class="headline-hash no-text-decoration" href="#org-special-block-sidenote">#</a></h3>


<p>Now just use the <code>#+begin_sidenote</code> .. <code>#+end_sidenote</code> Org special
blocks wherever you need sidenotes.</p>
]]></content><category scheme="https://scripter.co/categories/emacs" term="emacs" label="emacs"/><category scheme="https://scripter.co/categories/org" term="org" label="org"/><category scheme="https://scripter.co/categories/hugo" term="hugo" label="hugo"/><category scheme="https://scripter.co/categories/web" term="web" label="web"/><category scheme="https://scripter.co/series/sidenotes" term="sidenotes" label="Sidenotes"/><category scheme="https://scripter.co/tags/sidenotes" term="sidenotes" label="sidenotes"/><category scheme="https://scripter.co/tags/100daystooffload" term="100daystooffload" label="100DaysToOffload"/><category scheme="https://scripter.co/tags/ox-hugo" term="ox-hugo" label="ox-hugo"/><category scheme="https://scripter.co/tags/shortcode" term="shortcode" label="shortcode"/><category scheme="https://scripter.co/tags/special-block" term="special-block" label="special-block"/></entry></feed>