Hinode - Docs

Docs

Share via

Link copied to clipboard

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

Overview

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.

config/_default/hugo.toml

title = "Hinode"
copyright = "Copyright © 2024 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 attribute of the tab control that wraps the docs 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			ID of the collapse panel holding the code snippet, defaults to `docs-collapse-n` with a sequential number `n` starting at `1`.
name	string	yes		Name of the code snippet, used to identify the relevant section of the input file.
show	bool		true	If unset, shows the panel with the code snippet in collapsed state. By default, the panel is expanded.

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 © 2024 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).

config/_default/hugo.toml

title = "Hinode"
copyright = "Copyright © 2024 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.

assets/scss/theme/theme.scss

.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.

assets/scss/theme/theme.scss

.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.

theme.scss

.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" >}}

• Use pagerSize instead of paginate (a541801)

On this page: