How can another file be Included in a Hugo/Markdown page?

Asked 16/9, 2016 at 20:43 Answered 10/11, 2023 at 2:10

Recently the re-development of a web site was given to me. The re-worked site is to be done in Markdown and run through the Hugo static site generator.

Is there a way to include other files in a Markdown web page processed through Hugo? If so, how? Unless I've missed something, this isn't addressed in the Hugo docs.

With HTML and some servers (Apache, at least) you can do something like:

<html>
<body>
Some content
<!--#include virtual="name_of_first_file_to_include" -->
More content
<!--#include virtual="name_of_second_file_to_include" -->
Still more content
</body>
<html>

I've tried creating a template page which puts stuff like "Some content" and "More content" into the template and then the included stuff in my .md file which gets "included" via {{ .Content }} in the template. However, 1) That seems like the wrong way to use a template. 2) I've not figured out a way to bring in more files if I need them.

Ostracize answered 16/9, 2016 at 20:43 Comment(0)

For content files there are two options:

Shortcodes. Powerful and documented.
Use mmark as the markdown rendering engine with its include feature. Rename the content files to "*.mmark". See https://github.com/miekg/mmark

I am the maintainer of Hugo.

Recriminate answered 30/9, 2016 at 21:10 Comment(6)

the include directive of mmark does some content filtering, am I wrong? What if I want to include a raw piece of html with scripts inside? (an interactive chart for example ) – Phelips 8/6, 2017 at 22:1

I'm not familiar with mmark, but I suspect you can wrap it in a div. But there is a third option: Hugo has a template func named readFile, but understand that the result isn't cached in any way, so if you use it from a heavily used template, I suggest you wrap it in partialCached. – Recriminate 9/6, 2017 at 12:13

readFile sounds good :D I haven't noticed that! thank you. So I need to write a shortcode for including pieces of raw text. – Phelips 9/6, 2017 at 15:7

Documented where, exactly? I went through all the Hugo docs looking for this bud didn't see it. :/ – Proser 8/7, 2021 at 13:8

Note that mmark is deprecated in Hugo, so that rules out option 2. – Mundane 27/9, 2021 at 19:33

honestly I hate to say this but it's VERY unclear how to include something as simple as a <script> tag in a markdown/content file. let alone how to use the {{ }} template notation stuff in a markdown file. this should be a basic feature and easy to use. been searching for an hour online. IMO the way it should be down is in the markdown you set a key to the name of the html file you want to include and hugo should take care of it. – Scrutable 6/10, 2021 at 18:46

I have a custom shortcode for rendering my static demo files as code via markdown, it's simple:

layouts/shortcodes/code.html

{{ $file := .Get "file" | readFile }}
{{ $lang := .Get "language" }}
{{ (print "```" $lang "\n" $file "\n```") | markdownify }}

content/post/some-post.md

 {{% code file="/static/some-script.js" language="js" %}}

Wedge answered 31/7, 2017 at 16:48 Comment(2)

To use relative file paths: {{ $filename := (path.Join $.Page.Dir (.Get "file")) }} {{ $file := $filename | readFile }} {{ $file | markdownify }}. – Bandy 7/5, 2021 at 17:3

In newer Hugo $.Page.Dir becomes $.Page.File.Dir – Bandy 7/5, 2021 at 17:11

A colleague suggested creating a shortcode to help with this. While this isn't quite what I had in mind - it is a more complicated than I would have liked - it's not too bad and I've not found a better way. Thus I've implemented a solution using a shortcode and a CSV file. Simple example files are below:

The content file is still (mostly) Markdown and looks something like:

+++
date = "2016-09-29"
title = "short_code_test"
type = "pages"
+++

## Short Code test

Test table should appear below:  

{{< display_table_csv "static/test_data.csv" >}}
  <tr><th>Name</th><th>Birthday</th>
{{< /test_table_shortcode >}}

(Note that the type = "pages" just pulls in a template which modifies/overrides the hugo-uno default pages/single.html template to make the output cleaner for purposes of display below.)

layouts/shortcodes/display_table_csv.html:

<table>
  <thead>
      {{ .Inner }}
  </thead>
  <tbody>
  {{ $url := (index .Params 0) }}
  {{ $sep := "," }}
  {{ range $row_i, $row := getCSV $sep $url }}
  <tr>
    {{ range $col_i, $col := $row }}
    <td>{{ $col }}</td>
    {{ end }}
  </tr>
  {{ end }}
  </tbody>
</table>

static/test_data.csv:

John, 1940-10-09
Paul, 1942-06-18
George, 1943-02-25
Ringo, 1940-07-07

This image shows how things rendered:

The Data-driven Content page in the Hugo docs was helpful also.

Ostracize answered 29/9, 2016 at 17:58 Comment(0)

I've manage to include markdown files with a shortcode like:

create the file layouts/shortcodes/include.html as:

{{ $file := .Get 0 }}
{{ (printf "%s%s" .Page.File.Dir $file) | readFile | replaceRE "^---[\\s\\S]+?---" "" | safeHTML }}

then include the markdown as:

{{% include somefile.md %}}

here's a reference link for it: https://roneo.org/en/hugo-include-another-file-with-a-shortcode/

Loftin answered 10/11, 2023 at 2:10 Comment(0)

Recommended topics

Hot tags