Interactive code examples in documentation?

feature
1

I think the documentation for Hugo is pretty brilliant, but more is a powerful word.

Would it be possible to have interactive code examples in the documenation?

My frontend brain says this would be nigh on impossible but I thought it would be interesting to put it out there :slightly_smiling_face:

1 Like
2

This kind of widgets are always interesting for programming languages.

But Hugo is mainly a templating platform, Iā€™m curious as to what kind of interaction your are referring too? Do you have an example?

3

The same kind of interaction really, as in you change the values, press enter and see how the changes are reflected in the outputted result.

I find the hardest part of Hugo is wrangling the templating: if there was an interactive element, you could see for example how menus are generated https://gohugo.io/content-management/menus/#multiple-menus

---
menu: ["main", "footer"]
---

Maybe one big fat interactive example website?? (thinking aloudā€¦)

4

Interesting idea! :slight_smile:

But if I put on my ā€˜pessimistic thinking hatā€™, Iā€™d be concerned that we only add to confusion for newcomers: Why does my example menu work in the playground but not on my site? That would give us two websites to ā€˜debugā€™: the repository and the code thatā€™s in the playground.

Problem of course is that Hugoā€™s strength (its flexibility) becomes a disadvantage in a playground, since that playground likely always differ from someoneā€™s local website. Or not?

1 Like
5

The pessimistic hat is a handy hat to have around! :slightly_smiling_face:

If there was one interactive playground website, I would imagine it to have the ā€œmost common use case scenariosā€ ā€“ a couple of menus, blog posts, categories, tags, a handful of pages etc. I think this would help beginners get off the ground. Then (blue sky hat on), when a user interacts with the playground website, a new instance of it is spun up just for that user.

Why does my example menu work in the playground but not on my site?

This question is much easier to answer if you actually have a working playground you can play with and break yourself.

All big conjecture but I do like the idea!

1 Like