theme: add multi column support

[DavidVargasxyz]

Being able to add multiple columns in a page would be awesome. I would really like to add a paragraph of text next to a picture or have tables next to each other. Is there a solution to this? Can not figure out how to do it with custom shortcodes.

[cagix]

would love to see this, too.

[McShelby]

I must admit, it's not something I plan to add in the near future. There are multiple reasons to this:

• I for myself have no use case for this
• it makes things complicated in mobile layout
• I really like the simplicity of pure Markdown - having shortcodes is nice, but each one used makes your Markdown more and more bound to Hugo or even this theme
• this can be easily added independtly of any theme with a generic module (although I don't know if there exists something like this for columns)

[cagix]

I don't know if this information is helpful: The Hugo Book Theme apparently supports columns via shortcodes. Perhaps these ideas can be utilised?

[postb99]

On my website my husband implemented the following in layouts\shortcodes\columns.html:

{{- $size := default "regular" (.Get "size" | lower) }}

{{- if not (in (slice "regular" "large" "small") $size) }}
  {{- $size = "regular" }}
{{- end }}


<div class="gdoc-columns gdoc-columns--{{ $size }} flex flex-gap flex-mobile-column">
  {{- range split .Inner "<--->" }}
    <div class="gdoc-columns__content gdoc-markdown--nested flex-even">
      {{ . | $.Page.RenderString -}}
    </div>
  {{- end }}
</div>

And css:

.gdoc-columns {
    margin: 1rem 0
}

/* Columns short code */
.gdoc-columns--regular>:first-child {
    flex: 1
}

.gdoc-columns--small>:first-child {
    flex: .35;
    min-width: 7rem
}

.gdoc-columns--large>:first-child {
    flex: 1.65;
    min-width: 33rem
}

.gdoc-columns__content {
    flex: 1 1;
    min-width: 13.2rem;
    padding: 0
}

.gdoc-columns .gdoc-post__anchor {
    display: none
}

.flex-mobile-column.gdoc-columns {
    margin: 2rem 0
}

.flex-mobile-column .gdoc-columns__content {
    min-width: auto;
    margin: 0
}

.flex-gap {
    flex-wrap: wrap;
    gap: 1rem;
}
.flex {
    display: flex;
}

So the use of this shortcode is not too cubersome:

{{< columns >}}

First column content

<--->
Second column content or can remain empty
<--->
Third column content

I use this on a single page on my website with empty middle column, here is the layout rendering:

It was indeed borrowed from aforementioned Hugo Book theme 😊

But is standard markdown for table layout not practical for you?

[DavidVargasxyz]

Where does the css file go and what to name it? Also, are there any other settings to change for this?

[cagix]

But is standard markdown for table layout not practical for you?

@postb99 not really - using markdown tables you get also separators and alternating line "highlighting", and there are use cases where i just want two or three columns (e.g. a figure and some text aside).

@McShelby i'd really like to have this "native" in the theme, but i also understand your hesitation. since i'm already performing some pre-processing w/ pandoc, i'd just need to add the custom css. however, i'd like to keep my customisations in my projects to a minimum :)

[McShelby]

But is standard markdown for table layout not practical for you?

@postb99 Additionally to @cagix comments, the width of the columns is automatically set. This is usually not what you want in a column layout as you want a fixed an reliable distribution of space.

@cagix The used shortcode is really basic and easy. While I personally dislike the column divider of <---> I agree this is quite easy to use. But it get's nasty if someone wants to write this text into a column.

Also shortcodewise, such a syntax feels alien. I would rather go with the (probably nested) syntax as with tabs/tab. But this would make it incompatible to the Hugo-book implementation (I've seen this exact same implementation in other themes, too!).

[cagix]

@McShelby yeah, this syntax using something quite like but not just html comments is kinda ... ugly (and not really standard markdown).

interestingly pandoc's implementation of columns (cf. https://pandoc.org/MANUAL.html#columns) is also using nested divs.

[DavidVargasxyz]

Is there a way to add a picture with text next to it? Maybe I don't need multi column for this?

[McShelby]

You could try out Hugo's build-in figure shortcode (I haven't tested if this looks good with the theme).

[McShelby]

I've styled the figure shortcode in #746

[DavidVargasxyz]

You could try out Hugo's build-in figure shortcode (I haven't tested if this looks good with the theme).

Ah, looks like this just puts some text under the picture. Where you able to get the Colum CSS mentioned above to work with this theme? They mentioned what file to put the html in but not the css.

[DavidVargasxyz]

On my website my husband implemented the following in layouts\shortcodes\columns.html:

{{- $size := default "regular" (.Get "size" | lower) }}

{{- if not (in (slice "regular" "large" "small") $size) }}
  {{- $size = "regular" }}
{{- end }}


<div class="gdoc-columns gdoc-columns--{{ $size }} flex flex-gap flex-mobile-column">
  {{- range split .Inner "<--->" }}
    <div class="gdoc-columns__content gdoc-markdown--nested flex-even">
      {{ . | $.Page.RenderString -}}
    </div>
  {{- end }}
</div>

And css:

.gdoc-columns {
    margin: 1rem 0
}

/* Columns short code */
.gdoc-columns--regular>:first-child {
    flex: 1
}

.gdoc-columns--small>:first-child {
    flex: .35;
    min-width: 7rem
}

.gdoc-columns--large>:first-child {
    flex: 1.65;
    min-width: 33rem
}

.gdoc-columns__content {
    flex: 1 1;
    min-width: 13.2rem;
    padding: 0
}

.gdoc-columns .gdoc-post__anchor {
    display: none
}

.flex-mobile-column.gdoc-columns {
    margin: 2rem 0
}

.flex-mobile-column .gdoc-columns__content {
    min-width: auto;
    margin: 0
}

.flex-gap {
    flex-wrap: wrap;
    gap: 1rem;
}
.flex {
    display: flex;
}

So the use of this shortcode is not too cubersome:

{{< columns >}}

First column content

<--->
Second column content or can remain empty
<--->
Third column content

I use this on a single page on my website with empty middle column, here is the layout rendering:

It was indeed borrowed from aforementioned Hugo Book theme 😊

But is standard markdown for table layout not practical for you?

Where do you put the css? Is there anything special I need to do to get this to work?

[McShelby]

You can supply your own layouts/partials/custom-header.html and put it in there.

[JohannOberdorfer]

Here is the minimum CSS + template code borrowed from the books theme which can be organized all together in one file and stored as ../shortcodes/columns.html. It can be used as described above in an easy way.
It is possible to compose text, markdown and other shortcodes within multiple columns.

Code:

<style>
.flex{display:flex}
.flex-auto{flex:auto}
.flex-even{flex:1 1}
.flex-wrap{flex-wrap:wrap}
.book-columns>div{margin:1rem 0;min-width:10rem;padding:0 1rem}
.markdown-inner>:first-child{margin-top:0}
.markdown-inner>:last-child{margin-bottom:0}
</style>

<div class="book-columns flex flex-wrap">
{{ range split .Inner "<--->" }}
  <div class="flex-even markdown-inner">
    {{ . | $.Page.RenderString }}
  </div>
{{ end }}
</div>

Usage:

{{< columns >}}
Faber est suae quisque fortunae. – Appius Claudius Caecus
{{% notice %}}
Cessante causa cessat effectus.
{{% /notice %}}
<--->
![](./images/image.png)
{{< /columns >}}

[satyagrahi]

Where does the css file go and what to name it? Also, are there any other settings to change for this?

Did not see an answer this question. I got @JohannOberdorfer 's solution to work, but i need to play around with the column widths. I want full width as shown by @postb99 and i can use flex to adjust column widths.

So repeating @DavidVargasxyz 's question. Please advice on how/where to insert the css.

Thanks in advance.

[McShelby]

#716 (comment)

[satyagrahi]

@McShelby : yes, i see where to put the html. But where does the css go?
Does it go in any of the existing css files or a new css file?
Or does it stay inside the html as <style> ?

[McShelby]

layouts/partials/custom-header.html will be included in the HTML head of every page. You can put any HTML you can put into a head. This includes style elements or linked stylesheets.

[McShelby]

At this point, I don't plan to add this shortcode to the release for the reasons mentioned above.

[JohannOberdorfer]

As hugo template engine is quite flexible, both ways are possible:

a) The css could either be placed directly in the shortcode (see code example at the beginning of this discussion).
In this case the css is only inserted into the actual page where it's needed (<style> ... </style> statement in the middle of the generated html page).

b.) css could also be placed in a static/css/custom.css file
This allows the browser to cache the css,and maybe there are other advantages.
To make the template aware of the customization, just use the partials/custom-header.html provided by relearn theme for overloading and add the following statement here:

{{- $assetBusting := not .Site.Params.disableAssetsBusting }}

I have written a briefe description which you can find here:
https://www.johann-oberdorfer.eu/blog/2023/10/15/23-11-10-hugo-relearn-theme/

[JohannOberdorfer]

oops the above statement has been truncated, should be:

{{- $assetBusting := not .Site.Params.disableAssetsBusting }}
<link href='{{"css/custom.css" | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}' rel="stylesheet">

[satyagrahi]

@JohannOberdorfer : Thank you very much. Appreciate it - will go and work on this avenue now. I do prefer (i am a novice, so its a preference only) the separate css file approach.