Include an md file

I am converting from Jekyll to Hugo

I have many code snippets in small md files that were included in other pages

{% include /COM/xap102/ops-change.markdown %}
{% include /COM/xap102/ops-read.markdown %}

How can I accomplish this with Hugo ?

Have a look at the shortcodes:

The inner content of these can be either Markdown or pure HTML (look at the docs). Combine it with the highlight template func and you should have a solid foundation:

And then there is this:

Something in the back of my mind makes me think that the mmark backend has
support for transclusion already - i’m not at my computer atm, so i can’t
confirm it though


Yes, that seems to be correct:

Then you just name your files .mmark and use whatever syntax that project provides.



Hi, bep, I’ve tried with the way of creating a short code like the following

{{$file := .Get 0}}
{{ $file | readFile | markdownify }}

The big problem of this way is , the headings of included markdown file will NOT be put into the TOC. Is there any solution for that?

If you include the shortcode using the “{{%” in the content file, this should work fine (assuming you have a reasonably new Hugo).

1 Like

I did using “{{%” in the content file, the details are in the following post, is there anything I missed?

Probably some detail WE missed. And that is hard to determine without knowing the details.

I packaged all relevant files in my project into a tiny zip file.

Just unzip it, run ‘hugo server’, and browse address ''http://localhost:1313/tut/03/" will show the problem.

As the following screenshot shows, headings in included md are missed, while I did use shortcode like {{% include "share/" %}} in the file content\tut\

hugo version : hugo_extended_0.61.0_Windows-64bit

1 Like

I guess i figured out why.

In Hugo 0.55 we changed how the % delimiter works. Shortcodes using the % as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.

The above description only applies to those shortcodes with included content directly in related html file.

But for those like having readFile command, the file content to be read is not fully rendered before sent to the markdown processor ( goldmark in my case).

So I have to write a pre-process script in Python to replace include direction with real file content.

Really hope Hugo guys could solve it in better way.

OK,finally solved

{{$file := .Get 0}}
{{ $file | readFile | markdownify }}

should be

{{$file := .Get 0}}
{{ $file | readFile | safeHTML}}

Thank you for this discussion – it taught me how to include files without having to pull their content using python first! However, the headings still don’t show up in the TOC – how can they be made to show up? I am including ~30-40 files and the TOC really is required here. You seem to have come across this problem – maybe you’ve found a solution?

Curious about the solution to this as well.

I’m new to Hugo and having an issue getting both the child headings to display in the TOC AND removing the front-matter from the imported MD file.

Using the above solution

{{$file := .Get 0}}
{{ $file | readFile | safeHTML}}

This topic had its beginning in 2015.

I think that a simpler way to render the Table of Contents of a file in recent versions of Hugo would be to include it as the Page Resource of a Leaf Page Bundle.

Then call the file in the template with the relevant method and within the context of the call render its .TableOfContents.

{{ with .Resources.ByType "page" }}
{{ range . }} 
        {{ .Content }}
        {{ .TableOfContents }}
{{ end }}
{{ end }}

This topic was automatically closed after 2 days. New replies are no longer allowed.