Docs

File

Posted on August 14, 2024  (Last modified on June 20, 2025) • 5 min read • 971 words
Component  
Component  
Share via

The file shortcode prints the full content of any given file with syntax highlighting.

Overview   Arguments   Examples   Default File Preview   Collapsed File Preview   File Preview With Filename Only   Syntax Highlighting  

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  .

[en]
    languageName = "English"
    contentDir = "content/en"
    weight = 1
    [en.params.head]
        tagline = "A Hugo Theme"
    [en.params.footer]
        license = "Code licensed <a href='https://github.com/gethinode/hinode/blob/main/LICENSE' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>MIT</a>, docs <a href='https://creativecommons.org/licenses/by-nc/4.0/' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>CC BY-NC 4.0</a>"
markdown 
{{< file file="./config/_default/languages.toml" id="file-collapse-1" >}}

Arguments  

  Important

The definition of the default id field fails when embedding (multiple) file 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 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.
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      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.
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      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.

Examples  

Change the style and language of your file preview with shortcode arguments.

Default File Preview  

Use the file argument to print the content of a specific file. By default, the shortcode uses the site’s basePath (see Page Layout for more information).

# toml-docs-start lang-main
[en]
    languageName = "English"
    contentDir = "content"
    weight = 1
# toml-docs-end lang-main
# toml-docs-start lang-param
    [en.params.head]
        tagline = "A Hugo Theme"
    [en.params.social]
        title = "Follow me"
        caption = "I work on everything coding and tweet developer memes"
    [en.params.footer]
        # license = "Licensed under Creative Commons (<a href='https://creativecommons.org/licenses/by-nc-sa/4.0/' class='link-secondary' target='_blank' rel='noopener noreferrer nofollow'>CC BY-NC-SA 4.0</a>)."
# toml-docs-end lang-param
markdown 
{{< file file="config/_default/languages.toml" id="file-collapse-2" >}}

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

[en]
    languageName = "English"
    contentDir = "content/en"
    weight = 1
    [en.params.head]
        tagline = "A Hugo Theme"
    [en.params.footer]
        license = "Code licensed <a href='https://github.com/gethinode/hinode/blob/main/LICENSE' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>MIT</a>, docs <a href='https://creativecommons.org/licenses/by-nc/4.0/' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>CC BY-NC 4.0</a>"
markdown 
{{< file file="./config/_default/languages.toml" id="file-collapse-3" >}}

Collapsed File Preview  

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

[en]
    languageName = "English"
    contentDir = "content/en"
    weight = 1
    [en.params.head]
        tagline = "A Hugo Theme"
    [en.params.footer]
        license = "Code licensed <a href='https://github.com/gethinode/hinode/blob/main/LICENSE' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>MIT</a>, docs <a href='https://creativecommons.org/licenses/by-nc/4.0/' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>CC BY-NC 4.0</a>"
markdown 
{{< file show="false" file="./config/_default/languages.toml" id="file-collapse-4" >}}

File Preview With Filename Only  

Set full to false to show the filename only.

[en]
    languageName = "English"
    contentDir = "content/en"
    weight = 1
    [en.params.head]
        tagline = "A Hugo Theme"
    [en.params.footer]
        license = "Code licensed <a href='https://github.com/gethinode/hinode/blob/main/LICENSE' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>MIT</a>, docs <a href='https://creativecommons.org/licenses/by-nc/4.0/' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>CC BY-NC 4.0</a>"
markdown 
{{< file full=false file="./config/_default/languages.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

[en]
    languageName = "English"
    contentDir = "content/en"
    weight = 1
    [en.params.head]
        tagline = "A Hugo Theme"
    [en.params.footer]
        license = "Code licensed <a href='https://github.com/gethinode/hinode/blob/main/LICENSE' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>MIT</a>, docs <a href='https://creativecommons.org/licenses/by-nc/4.0/' class='link-bg-footer fw-medium' target='_blank' rel='noopener noreferrer'>CC BY-NC 4.0</a>"
markdown 
{{< file full=false file="./config/_default/languages.toml" id="file-collapse-5"
    options="linenos=table,hl_lines=2-4 6,linenostart=10" >}}
On this page: