Docs: Add table shortcode in Features category, Shortcodes page

[jwflory]

Summary

Write new documentation to describe the table shortcode added in #70

Background

This feature was added to support rendering complex information in tables as part of an exercise @acabunoc put together when working with Venture Fund companies. The feature should be documented in the sample website to better capture the capabilities and unique features of this theme from what comes natively with Hugo.

Note that the example site was not originally made to be a functioning form of documentation for the project, so some liberty will need to be taken in removing old content or repurposing it as we go.

Details

The shortcode we use as found in /layouts/shortcodes/table.html:

{{ $_hugo_config := `{ "version": 1 }` }}

{{ $htmlTable := .Inner | markdownify }}
{{ $class := .Get 0 }}
{{ $old := "<table>" }}
{{ $new := printf "<table class=\"%s\">" $class }}
{{ $htmlTable := replace $htmlTable $old $new }}
{{ $htmlTable | safeHTML }}

The shortcode as it is used in a post from unicef/inventory#125:

{{<table "table">}}

| Stakeholder | Role | Motivation | Open Source Work |
|----------|----------|----------|----------|
| < stakeholder 1 > ||||
| < stakeholder 2 > ||||
| < stakeholder 3 > ||||

{{</table>}}

Its actual appearance:

Outcome

Easier to discover this feature when using the theme

[yokwejuste]

the link /layouts/shortcodes/table.html not working. The return is a 404.

[jwflory]

the link /layouts/shortcodes/table.html not working. The return is a 404.

Thanks, I used a shortcut that doesn't seem to work with GitHub-flavored Markdown. I fixed the URL. It should have pointed here:

https://github.com/unicef/inventory-hugo-theme/blob/main/layouts/shortcodes/table.html

[BeeBombshell]

Hi @jwflory, I'm having a little trouble understanding what needs to be done. 😅
The sample table on the elements page doesn't use the above-mentioned shortcode as of now. So, do we need to add a new table to document the shortcode or use it in an existing table?

Also, the shortcode table looks exactly the same as the normal HTML table. Even the styling done for the table element will affect both the normal HTML table and the shortcode table. So, I don't understand how a user will differentiate between the two.

[jwflory]

The sample table on the elements page doesn't use the above-mentioned shortcode as of now. So, do we need to add a new table to document the shortcode or use it in an existing table?

The documentation site should use the table shortcode instead of the Markdown table. This is because the shortcode works across both Markdown and Asciidoc content.

Also, the shortcode table looks exactly the same as the normal HTML table. Even the styling done for the table element will affect both the normal HTML table and the shortcode table. So, I don't understand how a user will differentiate between the two.

This is the documentation for content writers and not for readers/users. A content writer should use the shortcode when creating tables. A reader or user should not know the difference. So, the fix here is very simple! It is padding the existing Markdown table with the shortcode and perhaps adding a link to a Markdown table generator tool or other Markdown documentation.

Does it make sense?

[BeeBombshell]

@jwflory Yes, makes sense to me... 😊

Can I work on this issue?

[jwflory]

@BeeBombshell Definitely! 👍🏻