Advanced content formatting

support
1

I’m building a documentation site (sort of) with Hugo. I need some rather complex formatting, simple markdown is not enough. Right now I’m using short codes, but this is getting ugly already. For example, I just wrote this:

{{% tabs Ubuntu Fedora %}}

{{% tabcontent Ubuntu %}}
{{% step title="Ubuntu" %}}
Foobar
{{< highlight bash >}}
sudo apt install docker
{{< /highlight >}}
{{% /step %}}
{{% /tabcontent %}}

{{% tabcontent Fedora %}}
{{% step title="Fedora" %}}
Foobar
{{< highlight bash >}}
sudo dnf install docker
{{< /highlight >}}
{{% /step %}}
{{% /tabcontent %}}

{{% /tabs %}}

This lets you toggle instructions between distributions. As you can see, this is really not readable at all, and since I’m just at the beginning of building this thing I really wonder whether I’m on the right path here.

Is there any better way of doing this or is Hugo just the wrong tool for the job altogether?

2

Don’t know if it works well but would asciidoc help? Search this page:

3

if they are all similar, what if you put those instructions in a data file, covering all your different OS scenarios, then use a single shortcode to create your tabbed interface.

4

Ideally I’d be able to split content into multiple blocks and render each with a different layout. Data files would become unmaintainable because there will eventually be tens to hundreds of pages that share the same layout elements.

I’m currently considering Gatsby for this project, which uses React components to render pages.

5

Hugo still suport mmark render, but the author lost interest in the project, perhaps one day Hugo will stop supporting it.

Also, the new version promises to add support Pandoc possibly for small sites it will be the best solution.

6

@jgillich What do the tabs, tabcontent and step shortcodes do? Can you share those snippets too? I am thinking if there’s a way to do this in Org mode.