Markdown Elements for Hugo/Wowchemy

Update to keep the very latest developments:

Sources:

• Markdown Cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code
• Front Matter Variables: https://gohugo.io/content-management/front-matter/#predefined
• Hugo Emojify Cheat Sheet: https://ckli.xyz/post/emoji-lut/
• Wawchemy Page Elements: https://wowchemy.com/docs/content/writing-markdown-latex/
• Hugo Content Management: https://gohugo.io/categories/content-management
• 10 Ways to improve your (Hugo) website performance

YAML

Front matter allows page-specific metadata and functionality to be included at the top of a Markdown file.

In the documentation and the example site, we will predominantly use YAML to format the front matter of content files and TOML to format the configuration files and widget files. This is because TOML is more human-friendly but popular Markdown editors primarily support YAML front matter in content files.

A complete list of standard options can be found on the corresponding Hugo docs page.

The following is an informative example for this page:

## The title of your page (Core)
title: 'Markdown Elements for Hugo/Wowchemy'  # (Core)
## An optional subtitle that will be displayed under the title
subtitle: "A complete tutorial for writting markdown on Wowchemy"

## A one-sentence summary of the content on your page. 
##    The summary can be shown on the homepage and can also benefit your search engine ranking.
summary: 'This article gives an overview of the most common formatting options, including features that are exclusive to Wowchemy.' # (Core)

## Display the authors of the page and link to their user profiles if they exist.
authors: # (Core)
- Geo
- Herb

## Tagging your content helps users to discover similar content on your site. 
##    Tags can improve search relevancy and are displayed after the page content and also in the Tag Cloud widget.
tags: # (Core)
- Python
- Markdown
- Hugo
- Wowchemy

## Categorizing your content helps users to discover similar content on your site. 
##    Categories can improve search relevancy and display at the top of a page alongside a page’s metadata.
categories:
- Tutorial

## The RFC 3339 date that the page was published. 
date: "2020-11-03T00:00:00Z" # (Core)
show_date: true # Dates can now be hidden from pages by adding show_date: false in page front matter or by automatically applying it to all pages in a collection using Hugo's cascade:>show_date: false in the _index.md file.

## The RFC 3339 date that the page was published. 
##   You only need to specify this option if you wish to set date 
##   in the future but publish the page now, as is the case for 
##   publishing a journal article that is to appear in a journal etc.
# publishDate: "2020-11-03T00:00:00Z"

## The RFC 3339 date that the page was last modified. 
##   If using Git, enable enableGitInfo in `config.toml` to have 
##   the page modification date automatically updated, rather than manually specifying lastmod.
lastmod: "2020-11-03T00:00:00Z"

## By setting `featured: true`, a page can be displayed in the Featured widget. 
##   This is useful for sticky, announcement blog posts or selected publications etc.
featured: false   

## By setting `draft: true`, only you will see your page 
##   when you preview your site locally on your computer.
draft: false

## Featured image
##   To use, add an image named `featured.jpg/png` to your page's folder.
##   Placement options: 1 = Full column width, 2 = Out-set, 3 = Screen-width
##   Focal point options: Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight
image:
  placement: 1
  caption: "Credit by [**Wowchemy**](https://wowchemy.com/)"
  focal_point: "Center"
  preview_only: false
  alt_text: An optional description of the image for screen readers.


## Projects (optional).
##   Associate this post with one or more of your projects.
##   Simply enter your project's folder or file name without extension.
##   E.g. `projects = ["internal-project"]` references `content/project/internal-project/index.md`.
##   Otherwise, set `projects = []`.
projects: [GWDA]

## Page resources
##   Buttons can be generated in the page header to link to associated resources.
##   The example below shows how to create a Twitter link for a project and 
##   how to create a link to a post that was originally published on Medium:
links:
  - icon_pack: fab
    icon: twitter
    name: Follow
    url: 'https://twitter.com/Herb_hewang' # (required)
  # - icon_pack: fab
  #   icon: medium
  #   name: Originally published on Medium
  #   url: 'https://medium.com'   # (required)

## The following parameters can be added to the front matter of 
##   a page (such as a blog post) to control its features:
reading_time: true  # Show estimated reading time?
share: true  # Show social sharing links?
profile: true  # Show author profile?
commentable: false  # Allow visitors to comment? Supported by the Page, Post, and Docs content types.
editable: false  # Allow visitors to edit the page? Supported by the Page, Post, and Docs content types.    

## To enable LaTeX math rendering for a page, you should include `math: true` in the page’s front matter.
##   I have enabled math on the homepage or for all pages, by globally setting `math = true` in `config/_default/params`
# math: true

## Enable a Markdown extension for diagrams by toggling the diagram 
##   option in your `config/_default/params.toml` file or 
##   by adding `diagram: true` to your page front matter.
diagram: true

## Image gallery:
## To add an image gallery to a page bundle
# Discarded for any remote gallery images see: https://wowchemy.com/blog/v5.1.0/#apply-breaking-changes
gallery_item:  
- album: 'branch-bundle-1'
  image: 'GW150914Anniversary.png'
  caption: 'Write your image caption here'  # only shown when zoom out
  order: "asc" # "asc" or "desc"
  resize_options:  # which supports Hugo image processing options.
# - album: gallery        # can not be replaced
#   image: 'sketch5.png'  # `static/media/sketch5.png`
#   caption: A caption    # only shown when zoom out
# - album: gallery
#   image: https://vip1.loli.net/2020/11/11/OmVGhaz79iQJsvj.png
#   caption: Another caption  # only shown when zoom out


## (Optional) Header image (relative to `assets/media/` folder).
##   To display a full width header image, the header parameters below can be 
##   inserted towards the end of a page’s front matter. It is assumed that the 
##   image is located in your `assets/media/` media library
header:  # (It not works.....)
  image: "header.png"
  caption: "Image credit: [**MLflow**](https://mlflow.org)"

Don’t want to publish author pages?

To un-publish author pages from the site, update with hugo mod get -u ./... and then create a content/authors/_index.md file with the following: (Discord)

---
_build:
  render: never
cascade:
  _build:
    render: never
    list: always
---

Sub-headings

## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

## Reference A {#foo}
## Reference B {id="bar"}

<h2 id="foo">Reference A</h2>
<h2 id="bar">Reference B</h2>

## Reference
## Reference
## Reference

<h2 id="reference">Reference</h2>
<h2 id="reference-1">Reference</h2>
<h2 id="reference-2">Reference</h2>

Emphasis

Italics with _underscores_.

Bold with **asterisks**.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough with ~~two tildes~~.

Italics with underscores.

Bold with asterisks.

Combined emphasis with asterisks and underscores.

Strikethrough with two tildes.

Lists

Ordered

1. First item
2. Another item

1. First item
2. Another item

Unordered

* First item
* Another item

• First item
• Another item

Todo

Todo lists can be written in Wowchemy by using the standard Markdown syntax:

- [x] Write math example
- [x] Write diagram example
- [ ] Do something else

renders as

Images

Images may be added to a page by either placing them in your assets/media/ (Wowchemy v5.1.0) media library or in your page’s folder, and then referencing them using one of the following notations.

A figure from your assets/media/ media library:

{{< figure library="true" src="pic01.jpg" title="A caption" >}}

A figure within a page’s folder (e.g. content/post/writting-mardown/) :

{{< figure src="pic02.jpg" title="A caption" >}}

A numbered figure with caption:

{{< figure src="pic02.jpg" title="A caption" numbered="true" >}}

Or you can use the more portable Markdown syntax for displaying an image from the page’s folder, however it has limited options compared with the Figure shortcode above:

![alternative text for search engines](pic02.jpg)

You can now create figures using the standard, portable Markdown syntax ![screen reader text](image.jpg "caption") where the image is located in the page folder, media library, or remotely. This means that your figures can now be rendered by any Markdown editor, such as Visual Studio Code, Typora, and Obsidian :meow_wow:

• How to disable image spotlight on click? Put lightbox="false" in your figure shortcode.

Figures may be cross-referenced.

[Requires Wowchemy v5.1+]:

• It support custom figure IDs for easier cross-referencing
  • For example, {{< figure src="image.jpg" id="wowchemy" >}} can be cross-referenced with [A Figure](#figure-wowchemy)
  • This way, the cross-reference is unaffected by changes to captions
• Dynamically theme images according to the user’s light or dark theme
  • {{< figure src="image.jpg" caption="test" theme="light" >}} inverts image when browsing in dark mode
  • {{< figure src="image.jpg" caption="test" theme="dark" >}} inverts image when browsing in light mode

Image gallery

To add an image gallery to a page bundle:

1. Create a gallery album folder within your page bundle (i.e. within your page’s own folder)
2. Add images to your new album folder (Note that all galleries from the assets/media/albums/folder)
3. Paste {{ < gallery album="<ALBUM FOLDER>" >}} where you would like the gallery to appear in the page content, changing the album parameter to match the name of your album folder (in this case: /branch-bundle-1/)

{{< gallery album="branch-bundle-1" >}}

Note that album names should be lowercase.

Optionally, to add captions for your images, add the following instances to the end of your page’s front matter:

gallery_item:  
- album: 'branch-bundle-1'
  image: 'GW150914Anniversary.png'
  caption: 'Write your image caption here'  # only shown when zoom out
  order: "asc" # "asc" or "desc"
  resize_options:  # which supports Hugo image processing options.

Alternatively, create an image gallery with images from the internet or your static/media/ (Wowchemy v5) media library: (# Discarded for any remote gallery images in v5.1.0, see more)

1. Add gallery images to within your static/media/ media library folder

2. Reference your images at the end of the front matter of a content file in the form:

   gallery_item:
   - album: gallery        # can not be replaced
     image: 'sketch5.png'  # `static/media/sketch5.png`
     caption: A caption    # only shown when zoom out
   - album: gallery
     image: https://vip1.loli.net/2020/11/11/OmVGhaz79iQJsvj.png
     caption: Another caption  # only shown when zoom out      
   

3. Display the gallery somewhere within your page content by using

   {{< gallery >}}
   

Cite

To cite a page or publication, you can use the cite shortcode (Wowchemy v5+), referencing a folder and page name that you created:

{{<cite page="/publication/2012-krizhevsky-image-net-classification-deep" view="4" >}}

where view corresponds to one of the available listing views used throughout Wowchemy:

1. Stream:

   ImageNet Classification with Deep Convolutional Neural Networks

   Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton

   PDF Cite

2. Compact: (default)

   ImageNet Classification with Deep Convolutional Neural Networks

   Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton

   PDF Cite

3. Card:

   Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton

   January 2012 Advances in Neural Information Processing Systems 25

   ImageNet Classification with Deep Convolutional Neural Networks

   PDF Cite

4. Traditional academic citation, configured by the citation_style setting in params.toml:

   Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton (2012). ImageNet Classification with Deep Convolutional Neural Networks. Advances in Neural Information Processing Systems 25.

   PDF Cite

If you don’t specify a view, it will default to the compact view.

Audio

You can add a podcast or music to a page by placing the MP3 file in the page’s folder and then referencing the audio file using the audio shortcode (Wowchemy v5+):

{{< audio src="GW150914.mp3" >}} 
<!-- "Chirp" ringtones from the first GW LIGO detections -->

Videos

The following kinds of video may be added to a page.

Local video file

Videos may be added to a page by either placing them in your assets/media/ media library or in your page’s folder, and then referencing them using one of the following notations (Wowchemy v5.1.0).

A video from your assets/media/ media library:

{{< video library="true" src="mf_GW150914.mp4" controls="yes" >}}

A video within a page’s folder (e.g. content/post/writting-markdown/):

{{< video src="mf_GW151226.mp4" controls="yes" >}}

Youtube

The youtube shortcode embeds a responsive video player for YouTube videos. Only the ID of the video is required, e.g.: https://youtu.be/7jNUCOayjEA. Copy the YouTube video ID that follows / in the video’s URL and pass it to the youtube shortcode:

{{< youtube 7jNUCOayjEA >}}

Furthermore, you can automatically start playback of the embedded video by setting the autoplay parameter to true. Remember that you can’t mix named and unnamed parameters, so you’ll need to assign the yet unnamed video id to the parameter id:

{{< youtube id="7jNUCOayjEA" autoplay="true" >}}

Vimeo

Adding a video from Vimeo is equivalent to the YouTube Input shortcode. E.g.: https://vimeo.com/channels/staffpicks/146022717. Extract the ID from the video’s URL and pass it to the vimeo shortcode:

{{< vimeo 146022717 >}}

Links

- [I'm a link](https://www.google.com)  <!--open in new tab-->
- [I'm a link with title](https://iphysresearch.github.io/blog/about/ "Click This!")  <!--hovering-->
- [A post]({{< ref "/post/ML_notes/s-dbw-validity-index/index.md" >}})
- [A publication]({{< ref "/publication/2012-krizhevsky-image-net-classification-deep/index.md" >}})
- [A project]({{< ref "/project/CS231n/index.md" >}})
- [A relative link from one post to another post]({{< relref "../DL_notes/receptive-field/index.md#感受野计算" >}})
- [Scroll down to a page section with heading *Vimeo*](#vimeo)

• I’m a link
• About
• A post
• A publication
• A project
• A relative link from one post to another post
• Scroll down to a page section with heading Vimeo

To enable linking to a file, such as a PDF, first place the file in your static/files/ folder and then link to it using the following form:

{{% staticref "files/LiWeiWang_DL_From_Theory_to_Algorithm.pdf" "newtab" %}}Download the PDF{{% /staticref %}}

Download the PDF

The optional "newtab" argument for staticref will cause the link to be opened in a new tab.

Figures

To cross-reference a figure:

1. Retrieve the figure ID. The figure ID consists of a URL friendly equivalent of the image caption prefixed with figure-. To grab the exact ID, preview the page in Hugo, right click a figure and click Inspect in your browser to grab the value of the figure’s id field.
2. Create a link to the figure in the form [a link to a figure](#figure-FIGURES-CAPTION).

<!-- Only the first three figures have the same `id` field. -->
[a link to a figure](#figure-a-caption)  

a link to a figure

Tags and Categories

Use {{< list_tags >}} to provide a list of linked tags or {{< list_categories >}} to provide a list of linked categories.

Charts

Wowchemy supports the popular Plotly chart format.

Save your Plotly JSON in your page folder, for example chart.json, and then add the {{< chart data="chart" >}} shortcode where you would like the chart to appear.

Demo:

{{< chart data="contour_scatter" >}} 
<!--`content/post/writting-mardown/contour_scatter.json`-->

You might also find the Plotly JSON Editor useful.

Emojis

See the Emoji cheat sheet for available emoticons. The following serves as an example, but you should remove the spaces between each emoji name and pair of semicolons:

I : heart : Wowchemy : smile :

I ❤️ Wowchemy 😄

Icons

Since v4.8+, Wowchemy enables you to use a wide range of icons from Font Awesome and Academicons in addition to emojis.

Icon pack “fab” includes the following brand icons:

• twitter, weixin, weibo, linkedin, github, facebook, pinterest, twitch, youtube, instagram, soundcloud
• See all icons

Icon packs “fas” and “far” include the following general icons:

• fax, envelope (for email), comments (for discussion forum)
• See all icons

Icon pack “ai” includes the following academic icons:

• cv, google-scholar, arxiv, orcid, researchgate, mendeley
• See all icons
• To enable the academic icon pack in v5+, set ai = true under [icon.pack] in params.toml

Icon pack “emoji” gives you the ability to use emojis as icons

• See all icons
• Enter the emoji shortcode, such as :heart:, in Wowchemy’s icon field
• Wowchemy v4.9+ is required to utilise the emoji icon pack and can currently only be used in the Featurette (skills) widget.

Icon pack “custom” gives you the ability to use custom SVG icons

• Create an SVG icon in your favorite image editor or download one from a site such as Flat Icon
• Place the custom SVG icon in assets/images/icon-pack/, creating the folders if necessary
• Reference the SVG icon name (without .svg extension) in the icon field
• Wowchemy v4.9+ is required to utilise the custom icon pack and can currently only be used in the Featurette (skills) widget.

Here are some examples using the icon shortcode to render icons:

{{< icon name="terminal" pack="fas" >}} Terminal  
{{< icon name="chart-line" pack="fas" >}} Chart Line
{{< icon name="python" pack="fab" >}} Python  
{{< icon name="r-project" pack="fab" >}} R
{{< icon name="arxiv" pack="ai" >}} ArXiv
{{< icon name="google-scholar" pack="ai" >}} Google Scholar

renders as

Terminal
Chart Line
Python
R
ArXiv
Google Scholar

Optionally, left and right padding can be added to an icon using the padding_left="3" and padding_right="3" options, respectively.

Blockquote

> This is a blockquote.

This is a blockquote.

Highlight quote

This is a {{< hl >}} highlighted quote {{< /hl >}}.

This is a highlighted quote.

Mention a user

To mention someone (Wowchemy v4.6+ required), type {{% mention "username" %}} where username corresponds to a user account in Wowchemy.

{{% mention "Herb" %}}

Herb

Footnotes

I have more [^1] to say.
I have more more [^anymark] to say.

[^1]: Footnote example.
[^anymark]: Another footnote example.

I have more ¹ to say. I have more more ² to say.

Embed Documents

The following kinds of document may be embedded into a page.

To embed Google Documents (e.g. slide deck), click File > Publish to web > Embed in Google Docs and copy the URL within the displayed src="..." attribute. Then paste the URL in the form:

{{< gdocs src="https://docs.google.com/..." >}}

renders as (my file)

To embed slide from slides.com. Just copy the URL and do the same things as following:

{{< gdocs src="https://slides.com/iphysresearch/journal_club_20201020/embed" scrolling="no" >}}

or use the full Embed <iframe> code:

<iframe src="https://slides.com/iphysresearch/journal_club_20201020/embed" width="576" height="420" scrolling="no" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen ></iframe>

Diagrams

Wowchemy supports a Markdown extension for diagrams (Wowchemy v4.4.0+ required). You can enable this feature by toggling the diagram option in your config/_default/params.toml file or by adding diagram: true to your page front matter. Then insert your Mermaid diagram syntax within a mermaid code block as seen below and that’s it.

An example flowchart:

```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
``` 

renders as

An example sequence diagram:

```mermaid
sequenceDiagram
  participant Alice
  participant Bob
  Alice->John: Hello John, how are you?
  loop Healthcheck
      John->John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail...
  John-->Alice: Great!
  John->Bob: How about you?
  Bob-->John: Jolly good!
``` 

renders as

An example Gantt diagram:

```mermaid
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2               :         des4, after des3, 5d
``` 

renders as

Advanced diagrams

More advanced diagrams can be created in the open source draw.io editor. The editor has support for almost any type of diagram, from simple to complex. A diagram can be easily embedded in Wowchemy by choosing File > Embed > SVG in the draw.io editor and pasting the generated code into your page.

Alternatively, a diagram can be exported as an image from any drawing software, or a document/slide containing a diagram can be embedded.

One example from https://github.com/iphysresearch/drawio/blob/master/nifi-architecture.drawio:

Code highlighting

Pass the language of the code, such as python, as a parameter after three backticks:

```python
# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))
```  

Result:

# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))

The Wowchemy theme uses highlight.js for source code highlighting, and highlighting is enabled by default for all pages. However, several configuration options are supported that allow finer-grained control over highlight.js.

Jupyter Notebook

View the guide to blogging with Jupyter Notebooks.

Alternatively, a Jupyter notebook can be embedded in a page by following one of the approaches below:

1. Upload your notebook as a GitHub Gist and click Embed to copy and paste your hosted notebook into the body of content in Wowchemy.

   Example:

   <script src="https://gist.github.com/iphysresearch/bd6a647358697bc19b32375a04969f47.js"></script>
   

2. Convert your notebook to HTML using jupyter nbconvert --to html <NOTEBOOK_NAME>.ipynb. Then move the resulting HTML file to your page’s folder and embed it into the body of the page’s Markdown file using:

   <iframe
     src="./<CONVERTED_NOTEBOOK_FILENAME>"
     width="90%"
     height="1000px"
     style="border:none;">
   </iframe>
   

3. Upload your notebook to a cloud notebook service such as Microsoft Azure, Google Cloud Datalab or Kyso. Then click their Embed button, pasting their custom embedding code into the body of your page’s Markdown file.

4. Copy snippets of code from your notebook and paste them into the body of your page using Wowchemy’s code highlighting.

GitHub gist

Twitter tweet

To include a single tweet, just use the embed codes:

<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Data is/are <a href="https://t.co/pmacbnnaJN">pic.twitter.com/pmacbnnaJN</a></p>&mdash; PHD Comics (@PHDcomics) <a href="https://twitter.com/PHDcomics/status/1296758564594126849?ref_src=twsrc%5Etfw">August 21, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

renders as

Data is/are pic.twitter.com/pmacbnnaJN

— PHD Comics (@PHDcomics) August 21, 2020

$\LaTeX$ math

Wowchemy supports a Markdown extension for $LaTeX$ math. You can enable this feature by toggling the math option in your config/_default/params.toml file.

To render inline or block math, wrap your LaTeX math with $...$ or $$...$$, respectively.

Example math block:

$$\gamma_{n} = \frac{ 
\left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T 
\left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}
{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$$

renders as

$$\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |} {\left |\nabla F(\mathbf{x}{n}) - \nabla F(\mathbf{x}{n-1}) \right |^2}$$

Example inline math $\nabla F(\mathbf{x}_{n})$ renders as $\nabla F(\mathbf{x}_{n})$.

Example multi-line math using the \\\\ math linebreak:

$$
f(k;p\_0^{*}) = \begin{cases} p\_0^{\*} & \text{if }k=1, \\\\
1-p\_0^{\*} & \text {if }k=0.\end{cases}
$$

renders as

$$ f(k;p_0^{*}) = \begin{cases} p_0^{*} & \text{if }k=1, \\ 1-p_0^{*} & \text {if }k=0.\end{cases} $$

Table

Code:

| Command           | Description                    |
| ------------------| ------------------------------ |
| `hugo`            | Build your website.            |
| `hugo serve -w`   | View your website.             |

Result:

Callouts

Wowchemy supports a Markdown extension for callouts, also referred to as alerts or asides.

Callouts are a useful feature to draw attention to important or related content such as notes, hints, or warnings in your articles. They are especially handy when writing educational tutorial-style articles or documentation.

A callout can be created by using the Callout shortcode below. (For older Wowchemy versions prior to v5, replace callout in the examples below with alert.)

Wowchemy comes built-in with a few different styles of callouts.

The paragraph will render as a callout with the default note style:

{{% callout note %}}
A Markdown callout is useful for displaying notices, hints, or definitions to your readers.
{{% /callout %}}

This will display the following note block:

Alternatively, a warning can be displayed to the reader using the warning option:

{{% callout warning %}}
Here's some important information...
{{% /callout %}}

This will display the following warning notice to the reader:

Table of Contents

A table of contents may be particularly useful for long posts or tutorial/documentation type content. Use the {{% toc %}} shortcode anywhere you wish within your Markdown content to automatically generate a table of contents.

Or add side TOC for posts like this post:

Ref: Add table of contents for posts

Change the file <root dir>/layouts/_default/single.html as follows: (as default)

{{- define "main" -}}
<div class="container-fluid docs">
  <div class="row flex-xl-nowrap">

    <div class="d-none d-xl-block col-xl-2 docs-toc">
      <ul class="nav toc-top">
        <li><a href="#" id="back_to_top" class="docs-toc-title">{{ i18n "on_this_page" }}</a></li>
      </ul>
      {{ .TableOfContents }}
      {{ partial "docs_toc_foot" . }}
    </div>

    <main class="col-12 col-md-0 col-xl-10 py-md-3 pl-md-5 docs-content" role="main">
      <article class="article">

        {{ partial "page_header" . }}

        <div class="article-container">

          <div class="article-style">
            {{ .Content }}
          </div>

          {{ partial "page_footer" . }}

        </div>
      </article>
    </main>

  </div>
</div>

{{- end -}}