# File

The file shortcode prints the full content of any given file with 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](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages).

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

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

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

```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](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) for marking lines in the file. Pass the settings to the `options` argument.

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

```scss
.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](example). Provide an explicit, unique `id` to prevent cross-interference.

The shortcode supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `file` | string |  |  | 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 |  |  | 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. |
| `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. |