Docs

Docs

Last modified on June 20, 2025 • 4 min read • 731 words
Component  
Component  
Share via

The docs shortcode captures a code snippet from a supported input file.

Overview   Arguments   Input Files   Examples   Default Code Snipppet   Collapsed Code Snipppet   Code Snipppet With Filename Only  

Overview  

Added in v0.8.0   

The docs shortcode captures a code snippet from a toml or scss input file. It scans for named markers in a local file. The snippet between the two markers is then rendered using syntax highlighting.

title = "Hinode"
copyright = "Copyright © 2022 - 2025 Mark Dumay."
enableGitInfo = true
markdown 
{{< docs name="main" file="config/_default/hugo.toml" id="docs-collapse-1" >}}

Arguments  

  Important

The definition of the default id field fails when embedding (multiple) docs shortcodes in an Example. Provide an explicit, unique id to prevent cross-interference.

The shortcode supports the following arguments:

Name Type Required Default Comment
class string Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element.
file string yes Path of the input file. The path is relative to the basePath defined in the docs section of the site’s parameters. If the file starts with ./, the path of the repository is used as base path instead.
full bool true If unset, shows the filename only. By default, the entire path (relative to the base path) is shown.
id string Unique identifier of the current element.
name string yes Name of the code snippet, used to identify the relevant section of the input file.
show bool true Flag to indicate an item should be shown. For elements with multiple items, only one item can be shown at a time.
Name Type Required Default
class string
Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element.
file string yes
Path of the input file. The path is relative to the basePath defined in the docs section of the site’s parameters. If the file starts with ./, the path of the repository is used as base path instead.
full bool true
If unset, shows the filename only. By default, the entire path (relative to the base path) is shown.
id string
Unique identifier of the current element.
name string yes
Name of the code snippet, used to identify the relevant section of the input file.
show bool true
Flag to indicate an item should be shown. For elements with multiple items, only one item can be shown at a time.

Input Files  

The docs shortcode supports .toml and .scss file formats. Use a marker to denote the start and end of a code snippet:

  • For .toml files, use # toml-docs-start and # toml-docs-end followed by the snippet name
  • For .scss files, use // scss-docs-start and // scss-docs-end followed by the snippet name

Click on one the tabs to see a full example of an input file.

# toml-docs-start main
title = "Hinode"
copyright = "Copyright © 2022 - 2025 Mark Dumay."
enableGitInfo = true
# toml-docs-end main
// scss-docs-start breadcrumb
.breadcrumb {
    padding-top: 0.3 * $navbar-offset;
}
// scss-docs-end breadcrumb

Examples  

Change the style and language of your code snippet with shortcode arguments.

Default Code Snipppet  

Use the name and file arguments to refer to a code snippet of a file. By default, the shortcode uses the site’s basePath (see Page Layout for more information).

title = "Hinode"
copyright = "Copyright © 2022 - 2025 Mark Dumay."
enableGitInfo = true
markdown 
{{< docs name="main" file="config/_default/hugo.toml" id="docs-collapse-2" >}}

Provide a path that starts with ./ to use the path of the repository as base path instead.

.card-shrink {
    transition: 0.3s transform cubic-bezier(0.155, 1.105, 0.295, 1.12), 0.3s box-shadow, 0.3s -webkit-transform cubic-bezier(0.155, 1.105, 0.295, 1.12);
    cursor: pointer;
}

.card-shrink:hover {
    transform: scale(0.99);
    box-shadow: none if($enable-important-utilities, !important, null);
}
markdown 
{{< docs name="styling" file="./assets/scss/theme/theme.scss" id="docs-collapse-3" >}}

Collapsed Code Snipppet  

Set show to false to hide the code snippet on page load. The code is revealed when clicking the tab control.

.card-shrink {
    transition: 0.3s transform cubic-bezier(0.155, 1.105, 0.295, 1.12), 0.3s box-shadow, 0.3s -webkit-transform cubic-bezier(0.155, 1.105, 0.295, 1.12);
    cursor: pointer;
}

.card-shrink:hover {
    transform: scale(0.99);
    box-shadow: none if($enable-important-utilities, !important, null);
}
markdown 
{{< docs name="styling" show="false" file="./assets/scss/theme/theme.scss" id="docs-collapse-4" >}}

Code Snipppet With Filename Only  

Set full to false to show the filename only.

.card-shrink {
    transition: 0.3s transform cubic-bezier(0.155, 1.105, 0.295, 1.12), 0.3s box-shadow, 0.3s -webkit-transform cubic-bezier(0.155, 1.105, 0.295, 1.12);
    cursor: pointer;
}

.card-shrink:hover {
    transform: scale(0.99);
    box-shadow: none if($enable-important-utilities, !important, null);
}
markdown 
{{< docs name="styling" full=false file="./assets/scss/theme/theme.scss" id="docs-collapse-5" >}}
On this page: