Docs

Docs

The docs shortcode captures a code snippet from a supported input file.
Overview   Default Code Snippet   Collapsed Code Snippet   Code Snippet With Filename Only   Input Files   Styling   Arguments  

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.

Default Code Snippet  

Use the name and file arguments to refer to a code snippet of a file. By default, the shortcode uses the site’s basePath. Provide a path that starts with ./ to use the path of the repository as base path instead.

[style]
    primary = "#d43900"
    secondary = "#6c757d"
    success = "#198754"
    info = "#0dcaf0"
    warning = "#ffc107"
    danger = "#dc3545"
    light = "#f8f9fa"
    dark = "#212529"
markdown 
{{< docs name="theme-colors" file="./data/style.toml" id="docs-default" >}}

Collapsed Code Snippet  

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

kbd {
    border-radius: #{$theme-border-radius};
}
markdown 
{{< docs name="kbd" show="false" file="./assets/scss/components/_kbd.scss" id="docs-collapse" >}}

Code Snippet With Filename Only  

Set full to false to show the filename only.

kbd {
    border-radius: #{$theme-border-radius};
}
markdown 
{{< docs name="kbd" full=false file="./assets/scss/components/_kbd.scss" id="docs-filename" >}}

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 of the tabs to see a full input file example.

# toml-docs-start theme-colors
[style]
    primary = "#d43900"
    secondary = "#6c757d"
    success = "#198754"
    info = "#0dcaf0"
    warning = "#ffc107"
    danger = "#dc3545"
    light = "#f8f9fa"
    dark = "#212529"
# toml-docs-end theme-colors
// scss-docs-start kbd
kbd {
    border-radius: #{$theme-border-radius};
}

// scss-docs-end kbd

Styling  

The file assets/scss/components/_docs.scss defines the Hinode-specific styling of the docs shortcode.

.docs-controls .nav-link,
.file-controls .nav-link {
    border-top-left-radius: #{$theme-border-radius};
    border-top-right-radius: #{$theme-border-radius};
    margin-left: #{$theme-border-radius};
}

.docs-panel,
.file-panel {
    border: 1px solid var(--#{$prefix}border-color);
    overflow: hidden;
}

.docs-panel, .docs-panel .collapse,
.file-panel, .file-panel .collapse {
    border-radius: #{$theme-border-radius};
}

Arguments  

  Important

The definition of the default id field fails when embedding (multiple) docs shortcodes in an Example Component . 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.
On this page