Proposal to add a new shortcode "table" to Hugo


I propose adding the below shortcode to Hugo so that I can do:

{{% table style="width:50%" %}}
| a | b |
| c | d |
{{% /table %}}

<style>.toto { width:20%; } .toto th, .toto td { padding: 15px; text-align: left; }</style>

{{% table class="toto" %}}
| a | b |
| c | d |
{{% /table %}}

{{% table "zuzu" "border:3px dashed red;" %}}
| a | b |
| c | d |
{{% /table %}}

To result in:

table Shortcode

{{ $.Scratch.Set "__table.class" "" }}
{{ $.Scratch.Set "" "" }}
{{ if .IsNamedParams }}
    {{ with .Get "class" }}
        {{ $.Scratch.Set "__table.class" (printf "%s%s%s" " class=\"" . "\"") }}
    {{ end }}
    {{ with .Get "style" }}
        {{ $.Scratch.Set "" (printf "%s%s%s" " style=\"" . "\"") }}
    {{ end }}
{{ else }}
    {{ if len .Params | le 1 }}
        {{ $.Scratch.Set "__table.class" (printf "%s%s%s" " class=\"" (.Get 0) "\"") }}
    {{ end }}
    {{ if len .Params | eq 2 }}
        {{ $.Scratch.Set "" (printf "%s%s%s" " style=\"" (.Get 1) "\"") }}
    {{ end }}
{{ end }}
{{ replace .Inner "<table>" (printf "%s%s%s%s" "<table" ($.Scratch.Get "__table.class") ($.Scratch.Get "") ">") | markdownify }}
1 Like

Do you mean to propose that as an internal shortcode? It seems a poor candidate, since it will be something folks handle in different ways, and many will never use. But it works for you, so instead how about just posting to #tips-tricks?

Yes, it’s a proposal for internal shortcode.

since it will be something folks handle in different ways,

I couldn’t find a cleaner way. Do you have pointers to other ways? I searched this forum, Hugo and Blackfriday issues, Google, and I came up with this solution as I couldn’t find one.

and many will never use.

This will be useful for the cases where people want to customize the looks of a particular table, without applying something globally in the CSS file.

But it works for you, so instead how about just posting to #tips-tricks?

I plan to make an external tool rely on this shortcode. It would be nice for Hugo to support this or anything that would allow specifying table attributes from the content. If it’s a user shortcode, that tool won’t work seamlessly… I’d have to tell people “put this snippet in your theme or layout”.

Are there technical demerits of baking this into Hugo?

I am not sure that is the way to approach adding a feature. And I don’t have a clear answer, it is more of a feeling, I want to be upfront about that.

This is the part that raises a flag for me. The other internal shortcodes have a nice balance of broad use case and example code. Adding a table shortcode as you have is very opinionated and personal, as opposed to an observable consensus. And I am not sure it is a good example for learning shortcodes.

That is where I am coming from. I think it is a very cool shortcode! :slight_smile:

@bep Bumping this thread again to see if there can be interest in having a table shortcode just like figure shortcode, because today I realized the need to have table captions too.

Canonically table captions are put as:


But for the lack of a shortcode like this, I am resorting to a hack like this (Hugo rendered HTML).

<div class="table-caption">
  <span class="table-number">Table 1:</span>
  Awesome table

| h1  | h2  | h3  |
| abc | def | ghi |

It would be great if we can have a table shortcode that can be use to specify the table class and caption, and then may be more tags in future as needed.

@maiki I agree that inline styling and css in shortcode raises some flags for me as well.

However, I agree that better table support would be helpful, in particular certain html specifications that aren’t implemented fully through blackfriday or mmark. For example rowspan and colspan would be very helpful for more complex tables in markdown, even being able to specify a cell as a header<th> but it hasn’t been ironed out yet in mmark or attempted to be implemented in blackfriday as far as I know.

Advanced features like caption elements, a summary attribute, or being able to specify the header scope attribute or id and header attributes for better semantics and accessibility would be nice as well.

While being able to edit elements and attributes directly has been discussed some, there is one work-around that I saw @bobvanvliet share in a couple of his posts using regular expressions (replacRE) to edit the code generated from the markdown parser. Perhaps using this technique with some partials and/or shortcodes could get us by until there is more functionality implemented in the markdown parsers or within hugo itself?

EDIT: @kaushalmodi it seems some of this functionality is possible using asciidoc tables, have you tried using that instead of markdown? It is possible to convert markdown to asciidoc in pandoc and asciidoctor lets you edit the templates so you can add in the ability to use your table styling with it.

Hello @O_O (John), I actually use Org mode as my main content markup, and then auto-export that to Markdown using ox-hugo. As you see in the below screenshot, the syntax in Org is quite compact (left)… it just gets ugly in Markdown (right). The right side of that screenshot is completely ox-hugo generated. (If interested, that Markdown gets rendered by Hugo like this — Scroll down that whole page to see how much table styling I can pack in the content itself :slight_smile:.)

It’s while working on the Org to Markdown translation that I realized how much the plain Markdown was lacking for formatting/styling tables (like specifying caption, class, id, etc. and also rowspan, colspan as you said, and column grouping which Org mode supports).

My suggestion for a table shortcode would fill most of these gaps (Even though it wouldn’t affect my Org mode tables, it would at least make the exported Markdown tables prettier, easier to read, without those empty <div> hacks.)

But unfortunately, looks like not many people care about better tables…

It seems that many markup languages have issues with tables, and a lot of parsers have issues handling them. From what I’ve read it seems like a common issue, and of course each has its own unique ways of handling them. Pandoc is trying to implement tables better and the discussion on it is interesting to read to see all of the different formats and suggested solutions.

I guess that this is an issue for the markdown or asciidoc processor to implement but if pandoc implements tables well and is able to convert from OrgMode maybe there is a way for you to have the just the tables convert to html and then hugo(through blackfriday) could process the rest as markdown.

Another thought is linking the tables through metadata in the header or externally, either in one of the data formats (json,yaml,toml) or a csv and having a shortcode that reads it in and implements tables, though I guess that kind of puts us back where we started.

In the sites I’m working on complex tables are used fairly often for charts showing rates for various tiers of services and conditions, using nested headers on both the top and side of the table as well as cells that span across both columns and rows. Trying to figure out a simple way to implement it for the content writers who don’t know code is difficult, and each time I think i’ve found a solution it seems a bit complex.

Right now for me the simplest way seems like it will be using asciidoc and then either setting up a regular expression in the hugo template when reading the content, and/or editing the rendering template in asciidoctor to modify the html output to suit the site needs. The easier alternative is just making it in word, exporting as an image and just posting that, but that doesn’t work well for people on mobile or who rely on screen readers.

If something similar to GitHub - jeffreytse/jekyll-spaceship: 🚀 A Jekyll plugin to provide powerful supports for table, mathjax, plantuml, mermaid, emoji, video, audio, youtube, vimeo, dailymotion, soundcloud, spotify, etc. it would be great! Most flexible table scheme.