Embedding multiple markdown files into homepage

support
1

My homepage has a fairly complex structure with lots of <div>, <ul> etc. with specific classes. Hence I can’t express this within Markdown, but then I’d like to have my actual content sections written in Markdown rather than HTML. Is there a way to include the actual contents from multiple markdown files (or have a single markdown file which declares several named blocks)?

Searching this forum, I came across https://discuss.gohugo.io/t/single-page-with-nested-content/2645 which is pretty much the question I have. A workaround is provided as answer there, but I’m wondering whether there is a a supported way in between to fill several slots within one template from several Markdown files?

2

No elegant solutions for multiple markdown files (there is of course data files and the markdownify template func).

Also see

https://github.com/spf13/hugo/issues/2844

3

Hey, yes, data files + markdownify was what came to my mind, too. In fact, for my purposes it’d even suffice if I could specify Markdown inline within some sort of markdownify block, e.g. something like this:

{{ markdownify }}
**my markdown**
{{ end }}

My knowledge of (Go) template functions is quite limited, so I’m not sure whether it’s doable?

4

Don’t think so.

5

I don’t know how this would be an advantage over pulling from a markdown file directly or using a data file. Also, keep in mind that shortcodes can take markdown between their opening and closing tags if you need the convenience of markdown but want to wrap it in more complex html snippets in the middle of .md content files. I believe you can even create a shortcode that references a partial. There is a ton of flexibility here.

6

My rough estimate tells me that 60 percent of all the questions we get is the “how do I create this and that landing page type of site” – which I guess isn’t Hugo’s main force or the main use case.

7

This does seem common. We put together a lot of single-use, disposable landing pages at work. I’ve never recommended an SSG or full-blown CMS. One page can—and probably should in many cases—be coded in HTML with something like Emmet in a text editor. Or just make a free page on webflow or GH pages.

That said, for “single-page sites” with a lot of content, I don’t see how ranging through a series of markdown files in your layouts/index.html doesn’t cover almost all use cases. FWIW, I agree it’s not Hugo’s strength, but I also don’t see why it should be.

8

It’d combine powers of raw HTML usage where needed with simplicity of Markdown for contents parts where it is enough.

9

Cool. You should be able to do all of this between data files, markdown files, and shortcodes, no problem. How much content do you plan on having in your index.html? Have a repo to point me to?

10

Agreed it’s doable with the tools available (esp. data files + markdownify), I’ve got the feeling though that support for this could be smoother (at least from my perspective, thinking that support for complexely structured yet easily authorable landing pages should be part of the Hugo story, but YMMV).

I’m migrating http://mapstruct.org/ to Hugo. I don’t have the Hugo version on GitHub yet, but the existing landing page shows what’s needed.

Essentially I’d like to express the text-centric parts of that page by Markdown (either inline as suggested above (it’s similar to what I’ve done so far via HAML) or from multiple Markdown files, or from a single Markdown file containing named blocks which could be referenced from within the template). The rationale being that I’d like to benefit from simpler syntax for links, inline code etc.

Admittedly in this example it’s not a huge deal and I’ll just go for HTML all the way. It seems to be a common issue though hence I thought I’d start a discussion. Thanks btw. for providing this tool, I find it very useful!).

11

Okay, how about creating this content in markdown files in content/homepage. Then add a weight to your front matter for each page, and you’ll be to sort however you’d like in layouts/index.html. You can then use first and after to use the appropriate html classes/divs/whatever.

For example, with your “What is It?”, etc second row on your homepage:

<div class="row">
{{- range after 1 (first 4 (where .Site.Pages "Section" "homepage")) -}}
    <div class="span4">
      <h2>{{.Title}}</h2>
      {{.Content}}
    </div>
{{- end -}}
</div>

Then just make a markdown file in content/homepage/what-is-it.md:

---
title: What is it?
publishdate: 2016-12-28
description: 
---
MapStruct is a code generator that greatly simplifies the implementation of mappings between Java bean types based on a convention over configuration approach.

The generated mapping code uses plain method invocations and thus is fast, type-safe and easy to understand.

Etc. Does that make sense? This would work well for the code blocks you have in the subsequent rows as well, although I’m guessing you’ll need to build your own shortcode to get the ability to switch between, eg, Car.java and CarDto.java.

12

Thanks, that’s very helpful! It’s pretty similar to the solution given in https://discuss.gohugo.io/t/load-multiple-content-files-in-a-single-template/2566. There the author mentions that he’s using an empty template for the included files themselves, so they don’t get rendered into their own files.

I’ve got some good food for thoughts and will play a bit with it. Thanks again!

13

Ah, yeah. Forgot to mention that in my example. You’d also have to have a layouts/homepage/single.html that renders blank; something like the following:

{{define "main"}}
{{end}}

And that’s it. Glad that helped…

If you think of snazzier solutions (likely since this was off the cuff between work conference calls), please share in the forums!

14

@gunnarmorling I forgot to mention that you can just write a bunch of markdown in a partial and then add markdownify after calling the partial. Then you don’t need front matter, etc. The drawbacks are obvious, though: 1. You have a markdown file with a .html extension and 2. You have essentially a markdown content file in the midst of your templating rather than in the content folder; I guess this depends on how import source organization is to you.

So, for example, you can create layouts/partials/partialthatsreallymarkdown.html:

**Bold text** and then some *italics* text.

Then in layouts/index.html just call:

<div class="my-div">
{{partial "partialthatsreallymarkdown.html" . |  markdownify }}
</div>

And you’ll get the following output:

<div class="my-div">
<strong>Bold text</strong> and then some <em>italics</em> text.
</div>
1 Like
15

I’m dragging up this old thread, as I am also looking for some method to include multiple markdown files in a single page.

In my use case, it is a product page. There is a short description, long description, features and documentation. I’d like to split this to multiple markdown files or a single file with headers.

I’ve read through this thread, and the thread linked, and I’m wondering if this is still a valid approach or does the new Page Bundles handle this by placing multiple md files and somehow referencing them?

16

Yes the new Page Bundles handle this. But the multiple md files will not get their own URL.

17

Thank you for confirming @alexandros

I’m not looking for unique URLs, but I do need a way in the template to get the contents of each md file and I’ve not pieced together information that shows me how to do this yet. I’m slowly, slowly, learning Hugo.

18

You’re welcome. You will find everything you need at the Docs and @bep 's test repo for Hugo 0.32.

19

I know this is an old post. However, I wanted to do the same thing and my search brought me here. I’ve come up with what seems to be a solution… However, I’m new to Hugo and there could be something I’m not completely grasping.

  1. Create a headless page bundle in the content/home folder.
  2. Create a mardown file, let’s call it “mainContent.md”
  3. Create content as usual, but also create a new .Param in the front matter…

joesBio: “Joe is a great guy and everyone loves him.”
bobsBio: “Bob is rude and mean to clients. But he brings donuts, so we dont fire him”

  1. In your HTML, do this

    {{ $bundle := .Site.GetPage “/home” }}
    {{ $content := $bundle.Resources.Match “mainContent*” }}
    {{ range $content }}

    {{ .Param "joesBio" | markdownify }}
    {{ .Param "bobsBio" | markdownify }}

    {{ end }}

Seems to work. However, as I mentioned, I’m new to Hugo and could be missing something important.

Rick