Skip to content

Latest commit

 

History

History
342 lines (250 loc) · 9.57 KB

README.md

File metadata and controls

342 lines (250 loc) · 9.57 KB
Raw

Hugo Shortcodes

Some shortcodes for Hugo, which you can add to your website as a Hugo Module ✨

Install

  1. Enable modules in your repository (skip this step if you already have a go.mod file in your repo):

    hugo mod init github.com/$username/$reponame

  2. Add this module to your website by adding it to your config.toml:

    [module]
  [[module.imports]]
    path = "github.com/tohn/hugo-shortcodes"

  3. Run Hugo. This will download the latest version of the module.

    hugo server -v -D

Update

You can update this module with:

hugo mod get -u github.com/tohn/hugo-shortcodes

Or you can update all modules defined in your config.toml with:

hugo mod get -u

Styling

I decided to not include the (S)CSS directly in the shortcode so you have to include it yourself. This is due to minification and bundling reasons.

Include it like this in your <head> in layouts/_default/baseof.html:

<head>
  <!-- CSS -->
  {{ $tohn_hugo_shortcodes := resources.Get "css/tohn_hugo_shortcodes.scss" | toCSS }}
  {{ $css := slice $tohn_hugo_shortcodes | resources.Concat "css/bundle.css" | minify }}
  {{ if ne hugo.Environment "development" -}}
    {{ $css = $css | fingerprint -}}
  {{ end -}}
  <link rel="stylesheet" href="{{ $css.Permalink }}">

Adjust the styles you need/want by copying assets/css/tohn_hugo_shortcodes.scss to your assets/css folder and deleting the lines you don't need/want.

i18n

To also support websites with more than one language (or a different one than german or english), we use the i18n function of Hugo. Read more about the Multilingual Mode in the docs.

If you want to contribute some translations, feel free to do so 😊
Have a look in the i18n folder and use the file en.yaml as a starting point.

Override

You can override a shortcode by adding a file with the same name as the one you want to replace in your own shortcode directory (layouts/shortcodes for example). The same works for SCSS or i18n files.

Modules

abbr.html

abbr.html is copied from sametbh.

It can be used to insert an abbr HTML tag into your page.

Example:

{{< abbr title="What The Fuck" text="WTF" >}}

audio.html

audio.html can be used for inserting audio files with the audio HTML tag into your page.

This shortcode makes use of i18n.

Example:

{{< audio src="example.ogg" src2="example.mp3" >}}

color.html

color.html can be used to display the color representation of a hex value in your text.

This is one of the (hopefully!) few shortcodes with CSS declarations in it (since it would be very impractical to define every hex value beforehand).

Example:

{{< color "#1db954" >}}

contrastchecker.html

contrastchecker.html uses the Contrast Checker by WebAIM to display the Contrast Ratio and Passings/Failings of WCAG AA(A) of given Foreground and Background Colors in a table.

Of course you can use CSS to style the table.

Example:

{{< contrastchecker fcolor="242424" bcolor="FCFCFC" >}}

linkcontrastchecker.html

linkcontrastchecker.html is similar to contrastchecker.html and uses the Link Contrast Checker by WebAIM to display some ratios of given Link, Body Text and Background Color in a table.

I used a tables generator to help me create the table.

Example:

{{< linkcontrastchecker fcolor="242424" bcolor="FCFCFC" lcolor="0A802D" >}}

icon.html

icon.html can be used to include a fontawesome icon to your website.

To use it, we first have to add the Hugo Module for fontawesome. Normally we can just declare the module in config.toml. But since this would add an outdated release (4.x instead of 6.x), we have to add this via this command (notice the @6.x at the end):

hugo mod get github.com/FortAwesome/[email protected]

Afterwards we have to add the module in our config.toml:

[module]
  [[module.imports]]
    path = "github.com/FortAwesome/Font-Awesome"
    [[module.imports.mounts]]
      source = "scss"
      target = "assets/css/fontawesome"
    [[module.imports.mounts]]
      source = "webfonts"
      target = "static/fonts/fontawesome"

We also have to add the SCSS in assets/css/fontawesome.scss. See Styling how to do this.

Example:

{{< icon size="fa-lg" anim="fa-spin" col="#abcdef" >}}
{{< icon set="fa-brands" icon="fa-github" rot="flip-both" anim="fa-fade" >}}

progress.html

progress.html can be used to display a progress bar on your page. It is inspired by W3.CSS Progress Bars and Bootstrap.

Example:

{{< progress cur=3 max=42 color="#bee" mode="percent" >}}

spoiler.html

spoiler.html is essentially copied from Nelis Oostens (thanks for this!).

It can be used to hide some text (inline or multiline) and reveal it by hovering over it.

Example:

CN Spoiler {{< spoiler >}}Secret!!1!{{< /spoiler >}}

{{< spoiler >}}
Fictum, deserunt mollit anim laborum astutumque! Quisque placerat
facilisis egestas cillum dolore. Nec dubitamus multa iter quae et nos
invenerat. Contra legem facit qui id facit quod lex prohibet. Quam diu
etiam furor iste tuus nos eludet?
{{< /spoiler >}}

You can find the SCSS in assets/css/spoiler.scss. See the instructions in Styling how to add this to your website.

sub.html

Since we can't have HTML code in markdown, sub.html can be used to use the sub HTML tag.

Example:

CO{{< sub "2" >}}

sup.html

Similar to sub.html, sup.html can be used to use the sup HTML tag.

Example:

2{{< sup "10" >}}

video.html

video.html can be used for inserting video files with the video HTML tag into your page.

An alternative for this shortcode could be hugo-video.

This shortcode makes use of i18n.

Example:

{{< video src="example.webm" >}}

wayback.html

wayback.html uses the Wayback Machine to simplify the process of reviving links to deleted/moved or otherwise now inaccessible sources. Thanks Fryboyter for the inspiration!

I'm using this shortcode with reference style links in markdown. It's also important to notice that we have to use a different shortcode notation (with % instead of < and >).

Example:

This is [a link][1].

[1]: {{% wayback "https://example.org" %}}

Inspirations