Skip to content

Embeds and shortcodes

Jump to bottom
Ram Iyer edited this page Nov 1, 2021 · 5 revisions

Adding embeds and using other shortcodes

This theme supports the following embeds and partials:

  1. YouTube
  2. Spotify
  3. Table of contents
  4. Raw HTML
  5. Small-caps

These are apart from what Hugo already supports, including Instagram and Twitter.

YouTube embed

The YouTube embed supported here is the privacy-friendly one. It does not track user behaviour until the user plays the video. To use it in the default Hugo way, use the embed like you would use the default one:

{{< youtube myYouTubeVidID >}}

To start the video at a specific time point, add the time point (in seconds) as the first argument to the shortcode:

{{< youtube myYouTubeVidID 128 >}}

To start the video at a specific time point and end it at another, add the two time points (in seconds) as the two arguments:

{{< youtube myYouTubeVidID 128 142 >}}

If you would like to start the video at the beginning and end it at a specific time point, use 0 as the first argument:

{{< youtube myYouTubeVidID 0 42 >}}

Instagram embed

On October 24, Facebook pulled the plug on what it calls the "legacy" API, which meant that you can no more embed Instagram posts using the built-in short code. You would need to create a Facebook app and use the oEmbed capability to embed Instagram posts.

Spotify embed

The Spotify embed is simple. This is designed to use with podcast episodes, if you are into podcasting and your podcast is available on Spotify. Use the episode ID as the argument to the shortcode:

{{< spotify 1aIKOuo9dleSDqR4mnf4uJ >}}

Another way to use the Spotify shortcode is specify the episode ID in the frontmatter (YAML follows):

title: My new blog post
episode:
  spotify: 1aIKOuo9dleSDqR4mnf4uJ

Apple Podcasts embed

If you would like to give your readers to listen to a podcast episode on Apple instead, use the apple embed, same as how you would use Spotify:

{{< apple 10039018387488729 >}}
title: My new blog post
episode:
  apple: 10039018387488729

The series of numbers is the episode ID, which you can get from the browser address bar---this is the string that follows ?i= in the URL.

You will also need to set up your country (by default, the podcast embed will use us) and your ApplePodcastsId in your site config. This is the string after /podcast/,and before ?i= in the episode URL.

[params]
  applePodcastsId = "010938017739013093"
  countryCode = "in"

Podcast buttons

If you have your podcast on Google, Apple and Spotify, and would like to give the readers a button instead of the embed, this theme has you covered. Configure your Apple Podcasts parameters as above to be able to use the Apple Podcasts button, and Google Podcasts parameters as below to use the Google Podcasts button:

googlePodcastsId = aijdp0183ap68x9874abcblabla

Next, add the episode IDs to your post frontmatter:

title: My new blog post
episode:
  apple: 10039018387488729
  spotify: 1aIKOuo9dleSDqR4mnf4uJ
  google: 1aIKOuo9dleabiidhc2793cls7SDqR4mnf4uJ

Add add the buttons using a shortcode wherever you like within the post:

{{< podcast >}}

Table of contents

When you use subheadings in the posts, the subheadings get sluggified anchors associated with them. The TOC contains these subheadings with the anchors. You can choose to show the table of contents anywhere in the post (or choose not to show it at all, by omitting the shortcode).

To include the table of contents, use the following:

{{< toc >}}

Raw HTML

The Markdown parser that Hugo uses, removes HTML tags from the content. If you would like to use raw HTML (say, for a specific embed like Imgur), or if you would like to include some plain HTML formatting, use the raw shortcode.

{{< raw >}}
  <div class="my-awesome-div">My awesome div.</div>
{{< /raw >}}

Small-caps

The general convention in typography is to use small-caps for all-caps words longer than three characters. Like UNICEF. When reading, using small-caps for such words makes the reading experience smoother.

Typographical uses real small-caps included in the beautiful Alegreya font.

The theme automatically selects all occurrences of three or more consecutive uppercase letters and shows them in small-caps. But in some cases, you might want to explicitly set this up. For single-word small-caps, use:

{{< smallcaps UNICEF >}}

If you would like to use small-caps on a phrase, specify the phrase in quotes:

{{< smallcaps "ABC DEF" >}}

You may even choose to use small letters like unicef, and that will still appear in small-caps in the post:

{{< smallcaps unicef >}}

Caveat: To make it simpler to use, CSS forcefully makes these letters lowercase. Therefore, if you would like the first letter of a certain small-cap word to appear as actual capitals, leave the first letter out of the shortcode. (Use this sparingly.)

U{{< smallcaps NICEF >}}

A use case for this is when a sentence begins with an acronym.

Sidenotes

The theme supports showing side notes. These notes appear in the margin on large screens and as folded blocks on small screens. The side notes are numbered.

Here is the syntax for side notes:

{{< sidenote "abcdef" >}}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Aenean dignissim, mi vitae cursus condimentum, enim tellus
    congue lacus, vitae malesuada elit velit in mauris.
{{< /sidenote >}}

The name (in quotes) can be anything; each side note should have a unique name within the document. This mainly helps the folding and unfolding CSS on small screens.

EthicalAds

EthicalAds is a privacy-friendly, non-tracking advertising platform by ReadTheDocs. This theme supports adding EthicalAds advertisements.

To enable it, you would need to create an item under params in your site config. The first argument needed is the PublisherId. You would need to get your Publisher ID from EthicalAds.

The next parameter is the class. This site uses flat horizontal by default. If you would like to change this site-wide, use one of the classes from the official documentation.

The theme does not automatically add ads in posts, but implements it using a shortcode.

To add a theme, call it using:

{{< ethicalAds >}}

By default, this will show a text ad. You can add the type as a parameter if you would like. For example, to show an ad of type image, use:

{{< ethicalAds image >}}

You can also optionally add an ad ID. This would be the second parameter (which means that the first parameter is mandatory, if you would like to change the ID) when calling the shortcode. It defaults to post-ad.

The tags you use for the post would be the keywords used to pass context to the ad. Ensure you add the right keywords.

Mastodon

You can verify your site with Mastodon by passing in the Mastodon parameters in your site config:

[params.mastodon]
  server: mastodon.online
  username: myprecious79876
Clone this wiki locally