hugo-geekdoc/exampleSite/content/shortcodes/includes.md
Robert Kaussow 5c5e2d59cb
refactor: replace gulp by webpack and npm scripts (#258)
BREAKING CHANGE: We have replaced `gulp` with `webpack` and `npm scripts` to build this theme. If you build it on your own or use build commands during the deployment, you may have to adjust your setup.

BREAKING CHANGE: The `GeekblogIcons` font is using the icon name as Unicode now. As a consequence, you have to replace all references to Icons from this font if you have customized the theme.

BREAKING CHANGE: We have refactored the search integration to split Hugo templates from JavaScript code. To get it working again, you need to adjust the `outputFormats` and `outputs` in your Hugo configuration file, as [documented](https://geekdocs.de/usage/configuration/#site-configuration).
2022-01-06 13:58:10 +01:00

3.9 KiB

title
Includes

{{< toc >}}

Include shortcode can include files of different types. By specifying a language, the included file will have syntax highlighting.

{{</* include file="relative/path/from/hugo/root" language="go" markdown=[false|true] */>}}

Attributes:

Name Usage default
file path to the included file relative to the Hugo root undefined
language language for syntax highlighting undefined
type special include type (html,page) undefined
options highlighting options linenos=table

Examples

Markdown file (default)

If no other options are specified, files will be rendered as Markdown using the RenderString function.

{{< hint warning >}} Location of markdown files
If you include markdown files that should not get a menu entry, place them outside the content folder or exclude them otherwise. {{< /hint >}}

{{</* include file="/static/_includes/example.md.part" */>}}

{{< include file="/static/_includes/example.md.part" >}}

Language files

This method can be used to include source code files and keep them automatically up to date.

{{</* include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" */>}}

Result:

{{< include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100">}}

Special include types

HTML

HTML content will be filtered by the safeHTML filter and added to the rendered page output.

{{</* include file="/static/_includes/example.html.part" */>}}

{{< include file="/static/_includes/example.html.part" type="html" >}}

Pages

In some situations, it can be helpful to include Markdown files that also contain shortcodes. While the default method works fine to render plain Markdown, shortcodes are not parsed. The only way to get this to work is to use Hugo pages. There are several ways to structure these include pages, so whatever you do, keep in mind that Hugo needs to be able to render and serve these files as regular pages! How it works:

  1. First you need to create a directory within your content directory. For this example site _includes is used.
  2. To prevent the theme from embedding the page in the navigation, create a file _includes/_index.md and add GeekdocHidden: true to the front matter.
  3. Place your Markdown files within the _includes folder e.g. /_includes/include-page.md. Make sure to name it *.md.
  4. Include the page using {{</* include file="/_includes/include-page.md" */>}}.

Resulting structure should look like this:

_includes/
 ├── include-page.md
 └── _index.md

{{< include file="/_includes/include-page.md" type="page" >}}