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

Question

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.

score 20 · Accepted Answer · answered Sep 30 '16 at 21:10

20

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.

answered Sep 30 '16 at 21:10

bep

1,662
15
16

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 ) – Vincenzo La Spesa Jun 08 '17 at 22:01
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`. – bep Jun 09 '17 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. – Vincenzo La Spesa Jun 09 '17 at 15:07
Documented where, exactly? I went through all the Hugo docs looking for this bud didn't see it. :/ – Brad Jul 08 '21 at 13:08
Note that mmark is deprecated in Hugo, so that rules out option 2. – bart Sep 27 '21 at 19:33
1

honestly I hate to say this but it's VERY unclear how to include something as simple as a ` – Alexander Mills Oct 06 '21 at 18:46

score 15 · Answer 2 · answered Jul 31 '17 at 16:48

15

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" %}}

answered Jul 31 '17 at 16:48

oodavid

2,148
2
23
26

2

To use relative file paths: `{{ $filename := (path.Join $.Page.Dir (.Get "file")) }} {{ $file := $filename | readFile }} {{ $file | markdownify }}`. – Stefan van der Walt May 07 '21 at 17:03
2

In newer Hugo `$.Page.Dir` becomes `$.Page.File.Dir` – Stefan van der Walt May 07 '21 at 17:11

GreenMatt · Answer 3 · 2016-09-29T18:05:15.803

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.

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

3 Answers3

Linked