Can we use hugo commands in markdown files?


I have recently discovered Hugo, and am now studying and testing it to see if I can rebuild with it some websites I have (some static, some in LAMP CMSes).

So far, unless I missed something, there one thing that I don’t understand, and don’t like. I found this issue building the home page, but I’d want to do what follows with many other pages.

I want a home page that is a fixed “welcome” paragraph, followed by a list of the latest N posts I published, which have a certain flag set in the frontmatter. I managed to do this by writing the welcome into a separate HTML file, and this into the index.html file:

{{ partial "welcome.html" . }} {{ range last 10 (where .Data.Pages.ByDate ".Params.onfrontpage" "true")}} <li> {{ .Date.Format "2006/01/06" }} - <a href="{{ .Permalink }}">{{ .Title }}</a> </li> {{ end }}

But… Do I really have to write stuff like that into an HTML file, instead of a .md file? If I write the same Hugo commands into an .md file they are not processed., and this is the thing I don’t understand.

Theme and pages layout are one thing, actual content another, even if it is not static. Why write content inside layouts, that are something else? Or why write pure static content (the “welcome” part in my example) in HTML instead of markdown? Can I put generic Hugo commands like the list generation above in a generic .md file, in a way that Hugo will process it correctly, even though it is not inside an HTML template/file?

For the record, before posting this I have searched this forum, and found and read these discussions (no links, sorry, the system says that being my first post I’m not allowed to post links…);

  • “Allow home page to be easily authored in markdown”
  • “allow inclusion of other content in a content file”

Being still new to Hugo, however, I confess I have not understood if what I am asking is possible with the current version of Hugo, and if yes how.

Thanks in advance for any help!


Ouch. Of course. Shortcodes. Sorry.

I already knew about shortcodes, had even tested them to embed slides from slideshows. But for some reason, I was really sure that they couldn’t be used in this case.

Thanks a LOT, bep! Now I need to understand:

  • why .Data.Pages.ByDate works in the HTML template, but to get the same list from a shortcode, I had to change it to .Site.Pages.ByDate
  • how to write a shortcode, since I did not find or recognize it yet, that includes in the markdown file calling it the text of another text file, passed as its parameter, i.e. “{{% insertfile path/to/ %}}”

Try .Page.Data.Pages.ByDate … which may or may not be what you want.

I would not, however, use content files for

I would just put the “welcome” file in site config or in a data file.

This “insert a specific markdown file” isn’t easy in Hugo (there are workarounds, but I will let others chime in maybe), but we should fix that. But I’m not sure it is the common Hugo use case.


maybe the “welcome” text is not the best example to explain what I meant by “include a markdown file in another markdown file”.

Thinking to the several sites I plan to build with Hugo, I would like to have something like “{{% insertmarkdownfile path/to/ %}}” to put, as part of the content of just a few pages, or maybe just ONE page, and those alone, one block of text that is common to them all, but:

  1. is not constant over time
  2. is not data already inside Hugo, like the list of posts of my original question
  3. is not CSV or similar data, that Hugo could fetch from a data file and display directly with its data functions

One example may be: a post describing a shell script that searches for some topic in the google news of the last 7 days and outputs a formatted summary as one big, multiparagraph block of markdown text, maybe with several lists inside… I would like that post to have at the bottom, as example, the actual output of that script, run once a day. One other use case would be having in several pages with one common block of text written and updated manually by myself.

From what I read in the Hugo datafiles page, i.e “data files must be YAML, JSON or TOML files” I understand that the quickest way to do what I want is to have the script save that big block of markdown text as ONE field of one YAML, JSON or TOML file, with just one record. Not as “natural” as just writing “{{% insertmarkdownfile path/to/ %}}” but if it works, it’s OK.

Am I right, or is there a better way?


A long post, so you just answer this: The above is correct, but they can easily contain multiline strings which can contain markdown – format it with the markdownify template func.

Also note that we have support for i18n strings in the /i18n folder.

1 Like

Agreed; it’s not the strength of any generator to really focus on single-page websites (note: although SPAs are a different story). That said, I actually thought this was the original thought behind .GetPage (you’ve already corrected me, @bep.

[quote=“mfima, post:5, topic:4937”]
I would like to have something like “{{% insertmarkdownfile path/to/ %}}” to put, as part of the content of just a few pages, or maybe just ONE page, and those alone, one block of text that is common to them all, but:

If the content is going to remain the same across multiple pages, I’d recommend a partial with HTML. This would give you the added benefit of dynamic values you can pull from the front matter and context.

If you’re talking about reusing the same block in different spots within content, perhaps a shortcode that just pulls in that HTML directly into where you want it on the page. If you want the added convenience of additional markdown within the shortcode, use the {{%%}} syntax.

Hi, @rdwatters ,

what actually prompted me to start this thread is a combination of two things (sorry if I didn’t put it this way at the beginning, it is something I realized afterwards, thanks to your feedback).

One thing is that I am not looking at “single-page websites”, but, so to speak, the opposite case. That is, how to handle, insite a full website, single pages that are special, because they should embed text content that, for whatever reason, is not constant, and Hugo knows nothing about (unlike, e.g. lists of pages).

The other thing is that I have no problem to learn and partials, shortcodes, templates etc. I am already doing it regardless of this specific issue, and I like how Hugo handles these things. But I have the idea, or wish, that ideally whoever writes content should never (have to) do it in HTML. Text content is text content. Why should it be written in a different, more complex format than all the rest of the website just because it happens to be for the home page?