# Include an md file

**URL:** <https://discourse.gohugo.io/t/include-an-md-file/1702>\
**Category:** support\
**Created:** [September 11, 2015, 3:17pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702 "2015-09-11T15:17:36Z")\
**Posts on this page:** 17\
**Page:** 1

<div class="post-metadata">

**Author:** ![croffler](https://avatars.discourse-cdn.com/v4/letter/c/13edae/32.png) [@croffler](https://discourse.gohugo.io/u/croffler)\
**Post date:** [September 11, 2015, 3:17pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/1 "2015-09-11T15:17:36Z")

</div>

I am converting from Jekyll to Hugo

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

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

How can I accomplish this with Hugo ?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [September 11, 2015, 3:50pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/2 "2015-09-11T15:50:31Z")

</div>

Have a look at the shortcodes:

> **[Shortcodes](http://gohugo.io/content-management/shortcodes/)**
>
> Shortcodes are simple snippets inside your content files calling built-in or custom templates.

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:

> **[Functions Quick Reference](https://gohugo.io/functions/)**
>
> Comprehensive list of Hugo templating functions, including basic and advanced usage examples.

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [September 11, 2015, 7:59pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/3 "2015-09-11T19:59:44Z")

</div>

And then there is this:

> <https://github.com/gohugoio/hugo/issues/247>

---

<div class="post-metadata">

**Author:** ![SvenDowideit](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/svendowideit/32/670_2.png) [@SvenDowideit](https://discourse.gohugo.io/u/SvenDowideit)\
**Post date:** [September 11, 2015, 10:50pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/4 "2015-09-11T22:50:19Z")

</div>

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

sven

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [September 12, 2015, 9:43am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/5 "2015-09-12T09:43:13Z")

</div>

Yes, that seems to be correct:

> **[miekg/mmark](https://github.com/miekg/mmark)**
>
> mmark - Mmark: a powerful markdown processor in Go geared towards the IETF

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

---

<div class="post-metadata">

**Author:** ![croffler](https://avatars.discourse-cdn.com/v4/letter/c/13edae/32.png) [@croffler](https://discourse.gohugo.io/u/croffler)\
**Post date:** [September 12, 2015, 10:24pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/6 "2015-09-12T22:24:54Z")

</div>

cool

tks

---

<div class="post-metadata">

**Author:** ![Jiang\_Patrick](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jiang_patrick/32/10073_2.png) [@Jiang\_Patrick](https://discourse.gohugo.io/u/Jiang_Patrick)\
**Post date:** [December 28, 2019, 3:03am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/7 "2019-12-28T03:03:09Z")

</div>

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

```auto
{{$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?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [December 28, 2019, 9:35am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/8 "2019-12-28T09:35:42Z")

</div>

> [@Jiang\_Patrick](#):
>
> 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).

---

<div class="post-metadata">

**Author:** ![Jiang\_Patrick](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jiang_patrick/32/10073_2.png) [@Jiang\_Patrick](https://discourse.gohugo.io/u/Jiang_Patrick)\
**Post date:** [December 28, 2019, 11:52am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/9 "2019-12-28T11:52:10Z")

</div>

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

> [@The short code way of including md cause headings missed](https://discourse.gohugo.io/t/the-short-code-way-of-including-md-cause-headings-missed/22511):
>
> I know there is existing topic about how to including anther md file into current md file. The popular way is to use shortcode, so I create a shortcode ‘include’ like the following {{ $file := .Get 0 }} {{ if strings.HasSuffix $file ".html" }} {{ $file | readFile | safeHTML }} {{ else if strings.HasSuffix $file ".md" }} {{ $file | readFile | markdownify }} {{ end }} and use that shortcode like this \<!-- Requests library introduction --\> {{% include "share/py/requests.md" %}} T…

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [December 28, 2019, 1:35pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/10 "2019-12-28T13:35:43Z")

</div>

> [@Jiang\_Patrick](#):
>
> is there anything I missed?

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

---

<div class="post-metadata">

**Author:** ![Jiang\_Patrick](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jiang_patrick/32/10073_2.png) [@Jiang\_Patrick](https://discourse.gohugo.io/u/Jiang_Patrick)\
**Post date:** [December 29, 2019, 1:59am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/11 "2019-12-29T01:59:27Z")

</div>

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

[https://github.com/jcyrss/baiyueheiyu/files/4007660/hugo-demo.zip](https://github.com/jcyrss/baiyueheiyu/files/4007660/hugo-demo.zip)

Just unzip it, run ‘hugo server’, and browse address ''[http://localhost:1313/tut/03/](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/requests.md" %}}` in the file ` content\tut\03.md`

hugo version : hugo\_extended\_0.61.0\_Windows-64bit

 ![image](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/2X/0/01de84d69947f790d8a65c4b4595cd78df3895f9.png)

---

<div class="post-metadata">

**Author:** ![Jiang\_Patrick](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jiang_patrick/32/10073_2.png) [@Jiang\_Patrick](https://discourse.gohugo.io/u/Jiang_Patrick)\
**Post date:** [January 1, 2020, 8:19am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/12 "2020-01-01T08:19:14Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Jiang\_Patrick](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jiang_patrick/32/10073_2.png) [@Jiang\_Patrick](https://discourse.gohugo.io/u/Jiang_Patrick)\
**Post date:** [April 20, 2020, 4:57am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/13 "2020-04-20T04:57:46Z")

</div>

OK，finally solved

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

```

should be

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

```

---

<div class="post-metadata">

**Author:** ![mulomulo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/mulomulo/32/11641_2.png) [@mulomulo](https://discourse.gohugo.io/u/mulomulo)\
**Post date:** [June 15, 2020, 3:00pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/14 "2020-06-15T15:00:01Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![Kimberley\_Brown](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kimberley_brown/32/13784_2.png) [@Kimberley\_Brown](https://discourse.gohugo.io/u/Kimberley_Brown)\
**Post date:** [May 12, 2021, 4:45pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/15 "2021-05-12T16:45:51Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![alexandros](https://avatars.discourse-cdn.com/v4/letter/a/ecc23a/32.png) [@alexandros](https://discourse.gohugo.io/u/alexandros)\
**Post date:** [May 12, 2021, 7:07pm UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/16 "2021-05-12T19:07:34Z")

</div>

This topic had its beginning in 2015.

I think that a simpler way to render the [Table of Contents](https://gohugo.io/content-management/toc/#usage) of a file in recent versions of Hugo would be to include it as the [Page Resource](https://gohugo.io/content-management/page-resources/#readout) of a [Leaf Page Bundle](https://gohugo.io/content-management/page-bundles/).

Then call the file in the template with the relevant [method](https://gohugo.io/content-management/page-resources/#methods) and within the context of the call render its `.TableOfContents`.

```auto
{{ with .Resources.ByType "page" }}
{{ range . }} 
    <article>
        {{ .Content }}
    </article>
    <aside>
        {{ .TableOfContents }}
    </aside>
{{ end }}
{{ end }}

```

---

<div class="post-metadata">

**Author:** ![alexandros](https://avatars.discourse-cdn.com/v4/letter/a/ecc23a/32.png) [@alexandros](https://discourse.gohugo.io/u/alexandros)\
**Post date:** [May 15, 2021, 8:00am UTC](https://discourse.gohugo.io/t/include-an-md-file/1702/17 "2021-05-15T08:00:07Z")

</div>

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