Docs

File

The file shortcode prints the full content of any given file with syntax highlighting.
Overview   Default File Preview   Collapsed File Preview   File Preview With Filename Only   Syntax Highlighting   Styling   Arguments   Options Type  

Overview  

Added in v0.16.0     

The file shortcode prints and highlights the full content of a given input file. It recognizes the languages supported by Hugo’s highlight function  .

Default File Preview  

Use the file argument to print the content of a specific 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.

# 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
markdown 
{{< file file="./data/style.toml" id="file-collapse-2" >}}

Collapsed File Preview  

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

# 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
markdown 
{{< file show="false" file="./data/style.toml" id="file-collapse-4" >}}

File Preview With Filename Only  

Set full to false to show the filename only.

# 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
markdown 
{{< file full=false file="./data/style.toml" id="file-collapse-5" >}}

Syntax Highlighting  

Added in 0.27.6     

Use the Hugo syntax highlighting options  for marking lines in the file. Pass the settings to the options argument.

10
11
12
13
14
15
16
17
18
19
20

# 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
markdown 
{{< file full=false file="./data/style.toml" id="file-collapse-5"
    highlight-options="linenos=table,hl_lines=3-4 6,linenostart=10" >}}

Styling  

The file assets/scss/components/_docs.scss defines the Hinode-specific styling of the file 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 v1.0.0      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.
highlight-options string v1.0.0      Hugo highlighting options, see https://gohugo.io/shortcodes/highlight/#options-1  .
id string Unique identifier of the current element.
lang string Language to be used by the syntax highlighter. For files, the language is derived from the file extension when no language is specified. When rendering code examples with the example shortcode, use hugo to process Hugo (escaped) shortcodes and bookshop to render a Bookshop component using inline YAML data.
options string v0.27.6      v1.0.0      Use highlight-options instead. Hugo highlighting options, see https://gohugo.io/shortcodes/highlight/#options-1  .
path string v1.0.0      Use file instead. 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.
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
v1.0.0      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.
highlight-options string
v1.0.0      Hugo highlighting options, see https://gohugo.io/shortcodes/highlight/#options-1  .
id string
Unique identifier of the current element.
lang string
Language to be used by the syntax highlighter. For files, the language is derived from the file extension when no language is specified. When rendering code examples with the example shortcode, use hugo to process Hugo (escaped) shortcodes and bookshop to render a Bookshop component using inline YAML data.
options string
v0.27.6      v1.0.0      Use highlight-options instead. Hugo highlighting options, see https://gohugo.io/shortcodes/highlight/#options-1  .
path string
v1.0.0      Use file instead. 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.
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.

Options Type  

Name Type Required Default Comment
max int End of the value range (inclusive).
min int Start of the value range (inclusive).
values slice A slice of permitted select values.
Name Type Required Default
max int
End of the value range (inclusive).
min int
Start of the value range (inclusive).
values slice
A slice of permitted select values.
On this page