Best practices / techniques to separate content & structure / layout

support
1

Hi,

I would like to find out what others are doing to separate content from layout with Hugo. Essentially the content markdown files should ideally contain markdown. However I’m encountering a few situations where I’m tempted to just code the content in HTML to accomplish certain layouts.

For example, in the ‘content’ area of a particular page I would like to have a couple of panels with some lists etc - something like this Pen.

It is tempting to either code it completely in the template or do the code the full HTML in the content markdown file. But I’m sure there are better ways to accomplish this.

For example, one way I can envisage doing this is do pull the panels out into data templates. I’m sure I’ve seen somewhere where the data files contained copy etc, and can contain lists etc…

Are there any other suggestions how to accomplish this and to separate the content from the layout?

Looking forward to hearing your suggestions. Thank you.

2

For the Pen example I would create a short code, possibly nested.

2 Likes
3

OK so I have created a general purpose shortcode which wraps the inner content in a div and sets the class & id

So, layouts/shortcodes/mddiv.html looks like:

<div {{ with .Get "id" }}id="{{.}}" {{ end }} {{ with .Get "class" }}class="{{.}}" {{ end }}>
    {{ .Inner }}
</div>

In my content markdown file, I would use the shortcode something like this to generate the code in the above pen:

# Start of content
Some Text 1
Some Text 2
{{% mddiv id="info-panel-area" %>
{{% mddiv class="info-box" %>    
## Panel Heading 1
Panel 1 

* List item 1
* List item 2
* List item 3
{{% /mddiv %}}
{{% mddiv class="info-box" %>    
## Panel Heading 2
Panel 2 

* List item 1
* List item 2
* List item 3
{{% /mddiv %}}
{{% mddiv class="info-box" %>    
## Panel Heading 3
Panel 3 

* List item 1
* List item 2
* List item 3
{{% /mddiv %}}
{{% /mddiv %}}

So this helps in that the markdown is processed and I can still accomplish structuring the content with the div's. (Previously for some reason mixing markdown and html didn’t quite work. Any markdown within a div wasn’t being rendered. And I ensured that there was a line separating the html <div> and the markdown.)

But is this necessarily the most elegant way to go about this?

4

Can you start by making some arguments about the inelegancy of the above?

5

No I can’t. So this would be a perfectly flexible and pragmatic way of implementing the above.

6

hugo v0.111.3+extended

trying to use your code I get
unrecognized character in shortcode action: U+0025 '%'. Note: Parameters with non-alphanumeric args must be quoted
unrecognized character in shortcode action: U+003E '>'. Note: Parameters with non-alphanumeric args must be quoted

How to handle this?

Is there currently another possibility / best practice for getting structures/layouts into markdown/hugo ?

7

To me your example could be written with a mere unordered list, containing your heading, paragraph and the inner list.
Like this:

*	## heading 1
	
	paragraph1
	* element 1
	* element 2
	* element 3
*	## heading 3
	
	paragraph1
	* element 1
	* element 2
	* element 3
{.style}

producing this:

  • heading 1

    paragraph1

    • element 1
    • element 2
    • element 3

  • heading 2

    paragraph1

    • element 1
    • element 2
    • element 3

with {.style} defining your layout. No need for fancy html here. Do you want columns ? use flexbox or the “columns” property, which I found super useful.

the html produced is exactly what you asked for:

<ul class="essai">
<li>
<h2 id="heading-1" class="headings">
<a href="#heading-1">heading 1</a></h2><p>paragraph1
</p>
<ul><li>element 1</li><li>element 2</li><li>element 3</li></ul>
</li><li><h2 id="heading-1-1" class="headings"><a href="#heading-1-1">heading 1</a></h2><p>paragraph1</p><ul><li>element 1</li><li>element 2</li><li>element 3</li></ul></li></ul>

I flee shortcodes and html insertion like the plague.
If several pages get the same layout, you can give them a type so they get their own template, so you can render the content of a small page with that panel (in markdown, or not) wherever you want.
To some degree with flexblox/grid you can also change the display order regards to the main article: sidebar, navbar before or after content, etc.
With me it looks like:

<div id=container class="
{{with .Page.Params.style}}{{.}}{{end}}
{{if not .Page.Params.BookToc}} no_toc{{end}}
{{with .Page.Params.no_title}} no_title{{end}}">