Theme Documentation - Built-in Shortcodes

Sunt Programator! included in Documentation

2020-03-04 2225 words 11 minutes views

/en/theme-documentation-built-in-shortcodes/featured-image.png

Contents

Hugo provides multiple built-in shortcodes for author convenience and to keep your markdown content clean.

Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesn’t support well. You could use pure HTML to expand possibilities.

But this happens to be a bad idea. Everyone uses Markdown because it’s pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.

To avoid this limitations, Hugo created shortcodes. A shortcode is a simple snippet that can generate reasonable HTML code and conforms to Markdown’s design philosophy.

Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.

1 figure

Documentation of figure

Example figure input:

1

{{< figure src="/images/lighthouse.jpg" title="Lighthouse (figure)" >}}

The rendered output looks like this:

The HTML looks like this:

1
2
3
4
5
6


<figure>
  <img src="/images/lighthouse.jpg"/>
  <figcaption>
    <h4>Lighthouse (figure)</h4>
  </figcaption>
</figure>

2 gist

Documentation of gist

Example gist input:

1

{{< gist spf13 7896402 >}}

The rendered output looks like this:

The HTML looks like this:

1
2
3
4


<script
  type="application/javascript"
  src="https://gist.github.com/spf13/7896402.js"
></script>

3 highlight

Documentation of highlight

Example highlight input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{{< highlight html >}}

<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>
{{< /highlight >}}

The rendered output looks like this:

1
2
3
4
5
6
7
8


<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>

4.1 instagram(old)

Documentation of instagram

Example instagram input:

1

{{< instagram BWNjjyYFxVx hidecaption >}}

The rendered output looks like this:

The instagram-shortcode refers an endpoint of Instagram’s API, that’s deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the instagram-shortcode is used. For more information please have a look at GitHub issue #7879.

4.2 instagram(The way of mine by search and offical documents)

Official documents ofinstagram(Official documents of Hugo have not been updated yet)

Official documents ofinstagram(Facebook)

1
2
3
4
5
6
7
8
9


#1.Officially register with developers
#Create a task in the developer tool, get the app-id and app-secret, and fill in the request address below
curl -X GET "https://graph.facebook.com/oauth/access_token ?client_id={your-app-id} &client_secret={your-app-secret} &grant_type=client_credentials"
# Examples
curl -X GET "https://graph.facebook.com/oauth/access_token ?client_id=123&client_secret={456} &grant_type=client_credentials"
#After obtaining the token, fill in the following address to get the returned HTML code
curl -X GET \ 'https://graph.facebook.com/v10.0/instagram_oembed?url={url}&access_token={access-token}"
# Examples
curl -X GET \ 'https://graph.facebook.com/v10.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

The summary is as follows: the new version cannot be embedded directly, so the following steps need to be completed (both methods can be used) refer to the method of front-end boss JS

Instagram oEmbed Embedded IG post

Facebook:Application,ID,Key,URL

4.2.1Open the application directly with the mobile phone client, find the corresponding article, click three points, and then click embedded to generate the corresponding access address

4.2.2Steps of how to use code

Set up an application on Facebook for Developers and get the number and key

To enable the Facebook login function in Firebase, you need to have a set of ID and key of the Facebook application.

The application created in this article is for demonstration use. It will be deleted when this article goes online, so the application number and key will not exist.

Go to the page of FACEBOOK for Developers and log in to FB account, then click「create application」:

Select「more options」for the work part:

The next step is to fill in the display name of the application. Fill in a name that we can understand what we are doing:

After filling in, press 「create application」, to complete the creation.

Application number, key, OAuth URL

After the application is created, go to the application, click「Settings > basic data」,in the left menu, and you will see「application number」,「application key」, and some fields to be filled in:
Add a new product on the application: oembed, and adjust the application to「go online」

New products,oEmbed

After the application is created, click 「+」 next to 「products」 in the left menu

Then find 「oEmbed」and click「Settings」:

A confirmation box will pop up, check it and press「confirm」,Oembed will be added to the product list on the left, which means the addition is successful.

At the end, there is a Toggle button at the top, which is displayed as 「adjusting」:

Let’s click the button and confirm that we want to switch the mode and make it 「online」. Then the application can be used externally:

Add a Google Apps Script file to your Google Cloud Drive, and write the code to get the Access Token

When you add a GAS file to the backend, you get the FB Access Token

To be able to use the FB application, an Access Token is required to be cleared by FB, because the key is used in the process of retrieving the Token, so it has to be written on the back end and polished on the front end.

The quickest way to write a backend is to use the Google Apps Script file on Google’s cloud drive, or GAS.

Go to the Google cloud drive and click「Add > more > Google Apps Script」in the top left corner:

Enter the file, we first change the file name for the file, slide to the upper left-hand corner of the file name, click once can start to change the file name

The default is to have a myFunction on the right side, and after you delete the whole thing, paste the following code to get an Access Token:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


var  appId  =  '「Application number」 obtained by FB background';
var  secret  =  '「Application key」 obtained by FB background';


var  uri  =  'https://graph.facebook.com/oauth/access_token?client_id='  +  appId  +  '&client_secret='  +  secret  +  '&grant_type=client_credentials' ;


function  doGet ( e )  {
  var  response  =  UrlFetchApp . fetch ( uri ) ;
  return  ContentService . createTextOutput ( response ) . setMimeType ( ContentService . MimeType . JSON ) ;
}

Remember to modify the appId and secret variables.

doGet is what the GAS does when it anticipates GET, and in function it says GET an Access Token from FB.

After the code has been pasted and updated, click「Deployment > New deployment」in the upper right corner:

Click the gear icon on the right side of the 「Select type」icon and select 「Web application」:

Then on the right-hand side, the 「Who has access」area becomes everyone:

After you click 「Deploy」, the first deployment will require access:

Click 「Grant Access」in the image above and a warning window will appear:

Because we wrote the app ourselves, we can trust it. Click on 「Advanced」in the upper left-hand corner of the image above to open up a small line:

Click on 「Go to XXX」in the bottom left corner of the image above, because our application has not requested validation from Google, and the word (Unsafe)will keep appearing here.

When clicked, access will be granted:

Press 「Allow」and the GAS file is successfully deployed, giving a URL:

This URL is important, and just like the API, the GET URL returns a set of Access tokens.

Using JavaScript, Postman, browser and so on Access Token, and Access Token to get Instagram posts embedded code

Take Token, take IG post

At the end of the previous step we GET the deployed URL, first we GET the Access Token back using GET:

1
2
3
4
5
6


const  getToken  =  'Web address obtained after deployment' ;
fetch ( getToken )
  . then ( response  =>  response . json ( ) )
  . then ( response  =>  {
    console . log ( response ) ;
  } )

The response data from the Console looks like this:

1
2
3
4


{
  access_token: "405342487221016|50nqwaePxasUkpNVyIwrJpoA2H0",
  token_type: "bearer"
}

So we can know, response.access_token is our Access Token.

The next step is to use the Access Token to get the content of the IG post.

First we need to have the URL of the IG post, click the dot in the top right corner of the post, and click the 「Copy link」to get the URL OF THE POST:

With a post URL and a Token, we can use a GET to GET information about the post:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


const  getToken  =  'Web address obtained after deployment' ;
const  igUri  =  'Website of IG post' ;
const  hideCaption  =  true ;  //Wheather to hide the description,true to hide,false to not hide

fetch ( getToken )
  . then ( response  =>  response . json ( ) )
  . then ( response  =>  response . access_token )
  . then ( token  =>  {
    fetch ( `https://graph.facebook.com/v9.0/instagram_oembed?url= ${ igUri } &access_token= ${ token } &hidecaption= ${ hideCaption } ` )
      . then ( response  =>  response . json ( ) )
      . then ( response  =>  {
        console . log ( response ) ;
      } )
    } ) ;

As you can see from the API URL, the required parameters are: Ig post address, Access Token, and hidecaption to hide the description.

hidecaption isn’t in the new file, but magically it is in the old one, which Augustus tried out after reading the previous article, so it’s no surprise that FB will take it out one day.

In addition, the copied IG post URL itself takes a parameter like this:

1

https://www.instagram.com/p/CK6wSwfpuVi/?igshid=1wy9n8xgtbe89

After the actual test, there is no writing igshid this parameter does not matter, have captured the post information back.

In addition to the above three parameters, there are two other parameters are provided in the official file: maxwidth, omitscript.

maxwidth is the maximum width you can specify when embedding a post.

omitscriptis a Boolean value, and the default value is false. Generally speaking, when we embed IG posts, IG will automatically load the post data. If we want to have the need to load additional posts, we can write true here, and then execute instgrm.Embeds.process() to load the posts into the page.

But! During the implementation, it is not sure whether Augustus is wrongly written. No matter whether omitscript is trueor false, if instgrm. Embeds. Process() ‘is not executed, the post will appear white, like this:

And the old methods spit out html, which itself refers to IG’s embedd.html. Js, the new one seems to be merged with FB so it doesn’t exist:

1

<script src="https://www.instagram.com/embed.js"></script>

The response from console looks like this:

The values you can see are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


author_name
html
provider_name
provider_url
thumbnail_height
thumbnail_url
thumbnail_width
type
version
width

Where html is the code that we want to embed the IG post in, just put the whole section where we want it to go, and this Demo is in <div id="ig-iframe"></div>

The complete code embedded in IG post is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


< div  id =" ig-iframe " > </ div >

< script  src =" https://www.instagram.com/embed.js " > </ script >
< script >
  const  getToken  =  'Web address obtained after deployment' ;
  const  igUri  =  'IG posted website' ;
  const  hideCaption  =  true ;  //Optional,Weather to hide the description or not True to hide, false not to hide. The default is false
  const  maxWidth  =  400 ;  //Optional,What is the maximum width of the post


  fetch ( getToken )
    . then ( res  =>  res . json ( ) )
    . then ( res  =>  {
      const  token  =  res . access_token ;
      fetch ( `https://graph.facebook.com/v9.0/instagram_oembed?url= ${ igUri } &access_token= ${ token } &hidecaption= ${ hideCaption } &maxwidth= ${ maxWidth } ` )
        . then ( res  =>  res . json ( ) )
        . then ( res  =>  {
          const  wrap  =  document . getElementById ( 'ig-iframe' ) ;
          wrap . insertAdjacentHTML ( 'afterbegin' ,  res . html ) ;
          instgrm . Embeds . process ( ) ;
        } ) . catch ( err  =>  {
          throw  Error ( e )
        } )
      } ) . catch ( err  =>  {
        throw  Error ( e )
      } ) ;
</ script >

The completed Ig post embedding is completed~

Such two methods can’t embed instagram succinctly and quickly. They need to be embedded just like general resources. Hugo official said that they can’t continue to use and haven’t made any modification and adaptation for the time being. If they have been adapted, please contact me

5 param

Documentation of param

Example param input:

1

{{< param description >}}

The rendered output looks like this:

Hugo provides multiple built-in shortcodes for author convenience and to keep your markdown content clean.

6 ref and relref

Documentation of ref and relref

7 tweet

Documentation of tweet

Example tweet input:

1

{{< tweet 877500564405444608 >}}

The rendered output looks like this:

Hugo 0.24 Released: Big archetype update + @Netlify _redirects etc. file supporthttps://t.co/X94FmYDEZJ #gohugo #golang @spf13 @bepsays
— GoHugo.io (@GoHugoIO) June 21, 2017

8 vimeo

Documentation of vimeo

Example vimeo input:

1

{{< vimeo 146022717 >}}

The rendered output looks like this:

9 youtube

Documentation of youtube

Example youtube input:

1

{{< youtube w7Ft2ymGmfc >}}

The rendered output looks like this:

Contents

Theme Documentation - Built-in Shortcodes

1 figure

Lighthouse (figure)

2 gist

3 highlight

4.1 instagram(old)

4.2 instagram(The way of mine by search and offical documents)

Application number, key, OAuth URL

New products,oEmbed

When you add a GAS file to the backend, you get the FB Access Token

Take Token, take IG post

5 param

6 ref and relref

7 tweet

8 vimeo

9 youtube