parsiya / hugo-shortcodes

Parsia's Hugo Shortcodes

My Hugo Shortcodes

These are shortcodes that I have created for the Hugo static blogging engine.

To use them, copy the HTML files into your-hugo-blog/layouts/shortcodes/ or your-hugo-blog/themes/current-theme/layouts/shortcodes/. I do not suggest the second approach. Create the shortcodes directory if it does not exist. You can learn more about shortcodes from Hugo documentation.

• My Hugo Shortcodes
  • Codecaption (codecaption.html)
  • Image Caption (imgcap.html)
  • Wikipedia Link Generator (wp.html)
  • Octopress blockquote (blockquote.html)
  • Year (year.html)
  • abbr HTML Tag (abbr.html)
  • mark HTML Tag (mark.html)
  • Table of Contents (toc.html)
  • xref (xref.html)
    • Path
    • Anchor
    • Text
    • Title
• Editor Snippets
  • Sublime Text Completions
  • VS Code Snippets
  • Atom Snippets - Archived
• License

Codecaption (codecaption.html)

Adds title to code blocks.

Usage:

{{< codecaption lang="html" title="Code caption shortcode" >}}
<figure class="code">
  <figcaption>
    <span>{{ .Get "title" }}</span>
  </figcaption>
  <div class="codewrapper">
    {{ highlight .Inner (.Get "lang") "linenos=true" }}
  </div>
</figure>
{{< /codecaption >}}

Results in:

Image Caption (imgcap.html)

This shortcode adds captions to pictures. Due to the way the original css file was organized, this shortcode does not use <figure> and <figcaption>. Alt will also be set to title.

Usage:

{{< imgcap title="Sample caption" src="/images/2016/thetheme/1.png" >}}

Results in HTML:

<span class="caption-wrapper">
  <img class="caption" src="/images/2016/thetheme/1.png" title="Sample caption" alt="Sample caption">
  <span class="caption-text">Sample caption</span>
</span>

Wikipedia Link Generator (wp.html)

I attempted to the re-create the Jekyll Wikipedia link generator by Keltia. You can see the source here.

You can see the discussion on Hugo forums here with my original gist.

It has some shortcomings. There are definitely better ways to do this. Personally I prefer the named parameter version because the shortcode is easier to write but this should work for both.

Usage:

You can either use named parameters:

• {{< wp tag="VIC_cipher" >}}
• {{< wp tag="VIC_cipher" lang="fr" >}}
• {{< wp tag="VIC_cipher" lang="fr" title="" >}}
• {{< wp tag="VIC_cipher" title="VIC Cipher" >}}
• {{< wp tag="VIC_cipher" lang="en" title="VIC Cipher" >}}

Rendered to:

<a href="https://en.wikipedia.org/wiki/VIC_cipher">VIC_cipher</a>
<a href="https://fr.wikipedia.org/wiki/VIC_cipher">VIC_cipher</a>
<a href="https://fr.wikipedia.org/wiki/VIC_cipher">VIC_cipher</a>
<a href="https://en.wikipedia.org/wiki/VIC_cipher">VIC Cipher</a>
<a href="https://en.wikipedia.org/wiki/VIC_cipher">VIC Cipher</a>

Or positional:

• {{< wp VIC_cipher >}}
• {{< wp VIC_cipher fr >}}
• {{< wp VIC_cipher "" fr >}}
• {{< wp VIC_cipher "VIC Cipher" >}}
• {{< wp VIC_cipher "VIC Cipher" fr >}}

<a href="https://en.wikipedia.org/wiki/VIC_cipher">VIC_cipher</a>
<a href="https://fr.wikipedia.org/wiki/VIC_cipher">VIC_cipher</a>
<a href="https://fr.wikipedia.org/wiki/VIC_cipher">VIC_cipher</a>
<a href="https://en.wikipedia.org/wiki/VIC_cipher">VIC Cipher</a>
<a href="https://fr.wikipedia.org/wiki/VIC_cipher">VIC Cipher</a>

It does not remove the underlines from tag to use in title. I have not found a Hugo template function for that yet (perhaps there is one).

Octopress blockquote (blockquote.html)

Port of the Octopress blockquote plugin at http://octopress.org/docs/plugins/blockquote/.

It supports author, link, source and title. If title is not provided and link is longer than 32 characters, it is cut at the last forward slash similar to the original plugin.

It can be used as follows (also in tests/wp-test.markdown):

Normal quote:
{{< blockquote >}}
  This is a simple quote.
{{< /blockquote >}}

Quote with author
{{< blockquote author="Author2" >}}
  This is a quote with only an Author named Author2.
{{< /blockquote >}}

Quote with author and source
{{< blockquote author="Author3" source="Source" >}}
  This is a quote from Author3 and source "source."
{{< /blockquote >}}

Quote with author and link
{{< blockquote author="Author4" link="https://www.google.com" >}}
  This is a quote from Author4 and links to https://www.google.com.
{{< /blockquote >}}

Quote with author, link and title
{{< blockquote author="Author5" link="https://www.google.com" title="Google" >}}
  This is a quote from Author5 and links to https://www.google.com with title "Google."
{{< /blockquote >}}

Quote with author and a link longer than 32 characters, string is first cut at 32 characters then everything after the last forward slash is removed
{{< blockquote author="Author6" link="https://twitter.com/CryptoGangsta/status/716427930126196737" >}}
  This is a quote from Author5 and links to https://twitter.com/CryptoGangsta/status/716427930126196737 which is longer than 32 characters.
  <br>And this is a new line in the quote with the HTML br tag.
{{< /blockquote >}}

Test from the Octopress blockquote page at: http://octopress.org/docs/plugins/blockquote/
{{< blockquote author="@allanbranch" link="https://twitter.com/allanbranch/status/90766146063712256" >}}
  Over the past 24 hours I've been reflecting on my life & I've realized only one thing. I need a medieval battle axe.
{{< /blockquote >}}

Results in:

Year (year.html)

Displays the current year - based on the shortcode tutorial at https://gohugo.io/templates/shortcode-templates/#single-word-example-year.

Usage: {{< year >}}.

abbr HTML Tag (abbr.html)

Creates an abbr HTML tag. The structure for this tag looks like:

<abbr title="World Health Organization">WHO</abbr>

Which is created by the following shortcode:

{{< abbr title="World Health Organization" text="WHO" >}}

mark HTML Tag (mark.html)

Creates a mark HTML tag to highlight text.

Usage: {{< mark text="highlighted text" >}} results in the following HTML:

<mark>highlighted text</mark>

Table of Contents (toc.html)

Use it to insert a table of contents anywhere in your page. For more information about Hugo's table of contents please see https://gohugo.io/content-management/toc/.

Usage: {{< toc >}}.

Note for Goldmark users:

Starting with Hugo 0.60 (I think?), the configuration file has a new section named markup. We can specify the minimum and maximum heading levels in the table of contents. The defaults are as follows which are not that useful. Be sure to override them in your site's config file:

markup:
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2

For more information please see https://gohugo.io/getting-started/configuration-markup/#table-of-contents.

xref (xref.html)

Adds text to the input params to create a relref link for my blog. It adds hardcoded strings to the path to work with the way I organize my paths. It might not be useful for you.

These two are identical

{{< xref text="Brief Recon of the Nordpass Password Manager"
  path="/post/2021/2021-04-30-testing-extensions-edge/" anchor="brief-recon"
  title="Brief Recon" >}}

instead of

[Brief Recon of the Nordpass Password Manager]
  ({{< relref "/post/2021/2021-04-30-testing-extensions-edge/index.markdown#brief-recon" >}}
  "Brief Recon)

We can also use positional arguments.

{{< xref "path" "text" "title" "anchor" >}}

{{< xref "/post/2021/2021-04-30-testing-extensions-edge/" "brief-recon"
  "Brief Recon of the Nordpass Password Manager" "Brief Recon" >}}

With positional arguments, we cannot skip arguments. E.g., we can have path and anchor but not

{{< xref "/post/2021/2021-04-30-testing-extensions-edge/" >}}

{{< xref "/post/2021/2021-04-30-testing-extensions-edge/" "brief-recon" >}}

Path

• Path is passed to the relref link so it will panic if the path does not exist.
• If the path does not end in .md or .markdown it adds /index.markdown to the end of it to support page bundles.
• Don't worry about including / at the beginning or in the end, the shortcode removes them and adds its own.

Anchor

• Link's anchor.
• Optional.
• No need to include # but if included it will not introduce a bug. The shortcode trims it and adds its own.

Text

• The link's text.
• Optional.
• If not provided, the text will be the same as the link. I.e., .Site.BaseURL/$relreflink.

Title

• The text that appears on the mouse tooltip when it's over the link. The title HTML attribute for the a tag.
• Optional.
• If not provided, it will be the same as text.

---

Editor Snippets

I have created snippets for Atom, Sublime and VS Code.

Sublime Text Completions

Sublime text completions are stored in a .sublime-completion file in the User directory.

VS Code Snippets

VS Code snippets can be added to File > Preferences > User Snippets > markdown.json. For more information please see:

• https://code.visualstudio.com/docs/editor/userdefinedsnippets

Atom Snippets - Archived

I use Atom editor these days so I created a couple of snippets to insert these shortcodes while editing Markdown files. In order to read on how to create snippets please refer to Atom's Snippets package.

Open your snippets file (on Windows it's File > Open Your Snippets) and paste the editor-snippets\atom-snippets.cson into it.

My original mistake was to repeat '.source.gfm' before the imgcap snippet, seems like cson keys should not be repeated.

For more information please see:

• https://flight-manual.atom.io/using-atom/sections/snippets/

License

I don't know, MIT I guess.

hugo-shortcodes's Issues

replacing underscore with space

I don't do a pull request for that, but you can use (with your Scratch use, that is no more necessary)

 {{ $.Scratch.Set "wp_title" (replace (.Get 0) "_" " ")  }}

Of course it is untested, but I have similar code in my shortcodes.

Convert to a theme component

See here https://github.com/davidsneighbour/dnb-hugo-shortcodes

blockquote scrambles output

Hello!

Thank you very much for your blockquote plugin, it's amazing!
However, I found a little difference with original one which I think might be considered a problem:

Here is the source code of fragment:

{{< blockquote author="Paul Graham" title="Write Like You Talk" link="http://www.paulgraham.com/talk.html" >}}
Here's a simple trick for getting more people to read what you write: write in spoken language.

Something comes over most people when they start writing. They write in a different language than they'd use if they were talking to a friend. The sentence structure and even the words are different. No one uses "pen" as a verb in spoken English. You'd feel like an idiot using "pen" instead of "write" in a conversation with a friend.

<...>

You don't need complex sentences to express complex ideas. When specialists in some abstruse topic talk to one another about ideas in their field, they don't use sentences any more complex than they do when talking about what to have for lunch. They use different words, certainly. But even those they use no more than necessary. And in my experience, the harder the subject, the more informally experts speak. Partly, I think, because they have less to prove, and partly because the harder the ideas you're talking about, the less you can afford to let language get in the way.

<...>

People often tell me how much my essays sound like me talking. The fact that this seems worthy of comment shows how rarely people manage to write in spoken language. Otherwise everyone's writing would sound like them talking.

If you simply manage to write in spoken language, you'll be ahead of 95% of writers. And it's so easy to do: just don't let a sentence through unless it's the way you'd say it to a friend.
{{< /blockquote >}}

Conditions of the MIT license

MIT license comes with conditions of use stating use of any of your snippets (of which people are likely going to copy some not all) must include the license and copyright notice:

As such, it would be a good idea for you to:

• Drop the copyright notice and license into each of the files, or;
• Provide clear usage instructions in the README.

Of course you don't have to do any of this. But it would be nice to prevent others from potentially copying this work without the attribution required by your license.

I see a lot of people—even those with years of experience—get this wrong so no worries. Should you decide to do nothing that's fine too just don't expect to see attributions based on your license when the shortcodes included here are ultimately copied by others without meeting the conditions.

There are, of course, other licenses which do not come with the conditions of the MIT license. Ultimately BlackDuck will know so you don't have to. ;)

Also remove the www at the start of URLs for blockquote shortcode

The blockquote shortcode removes the protocol:// from the start of the link when displaying it in absence of a title. It should also remove the www. for better visibility.

Be sure to update the screenshot.

Blockquote won't show title if there is no link

Hello, friend!
$subj. Example:

{{< blockquote author="Марк Аврелий" title="Наедине с собой" link="http://www.opentextnn.ru/man/?id=518" >}}
Да живи ты хоть три тысячи лет, хоть тридцать тысяч, только помни, что человек никакой другой жизни не теряет, кроме той, которой жив
{{< /blockquote >}}

If I remove link, title will go away, which is not good in my opinion - one should be able to quote the book without linking.
By the way, thanks for the plugin again, it's amazing.

Reset scratch variables at the start of shortcode

If scratch variables are not reset, they will keep their value between different shortcodes. If uninitialized that will mess things up.

Codeblock shortcode that reads from a file in the data directory

Create a version of the codecaption shortcode that reads the source code from a file in the data directory.

Create a shortcode for relref

This is how my relref snippet does:

[link text]({{< relref "/post/2020/2020-01-01-blog/index.markdown#anchor" >}} "link text")

However, this is bulky and make blog posts unreadable.

Make a shortcode that does it a bit better. I have not decided on the parameters yet but here's an example:

{{< myref title="link text" post="/2020/2020-01-01-blog" anchor="anchor" >}} should generate the above.

Or I can do positional parameters {{< myref "link text" "/2020/2020-01-01-blog" "anchor" >}}

Shortcodes support tablecaption

Now Shortcodes support codecaption and imagecaption, how about tablecaption?

Typo in the blockquote example in readme

The last blockquote is missing a forward slash

  Over the past 24 hours I've been reflecting on my life & I've realized only one thing. I need a medieval battle axe.
{{< blockquote >}}  <--- here

Create a test page to showcase uses and output

Add rel="noopener noreferrer" to shortcodes that create links

wp.html and blockquote.html create links. Possibly, others.