New docs content structure

[bep]

Reference

• Markup
  • Configuration
  • Render Hooks
  • Shortcodes
  • Front Matter
• Hugo Modules
  • Configuration
  • Imports
  • File Mounts
• Components
  • archetypes
  • content
  • static
  • layouts
  • data
  • assets
  • i18n
• Objects (interfaces)
  • Pages
    • Sorting (ByWeight etc.)
    • Grouping
    • Pagination
  • Site
    • Methods
      • .Pages
      • .RegularPages
      • ...
  • Page
    • Methods
      • .Kind, .IsPage, .IsNode
      • .RelPermalink
      • .Pages
      • .RegularPages
      • .RegularPagesRecursive
      • ...
  • Image
  • Resource
  • Menu
• Function namespaces
  • cast
  • collections
    • .Append
    • .Complement
    • ...
  • diagrams
  • resources
    • .Match
    • .GetMatch
    • .GetRemote
    • ...
  • strings
  • ...

Configuration

Templates

Lookup Rules

---

We should try to

• Keep the reference section mostly auto-generated so it's in synch with the code.
• We can create some naming scheme or something for the cases where we cant to add some more prose/examples to a given function/method.

[bep]

I will keep the intro post updated with my and others' thoughts about this. In this repo I have quickly (relatively) converted the old theme/site to a more modern stack in. Whether this was a great idea or not, I'm not sure, but I have had a few failed attempts building the old one (been looking at at non-fatal GitHub security report that I have not been able to fix), telling me that we at least need to do something.

I have been thinking about what to do with the content part of this. The preview build here currently builds the entire old docs content with some slight adjustments (documentation is now mounted below /documentation -- https://gohugoiotheme.netlify.app/documentation/), but ...

My take on this is that we need to somehow start fresh. It's lot of great content in the old, but it's much harder to remove/move stuff compared to re-adding stuff into a new structure.

So, I suggest that we 1) Agree on a structure and 2) Create that structure and move articles from the old repo.

/cc @jmooring @coliff etc.

[coliff]

Happy to see work on the 'new site theme' project picking up again!
Just had a quick look at the Netlify preview and it's looking great. Impressive page load times too - it's lightning fast.
I'd be happy to contribute some time to work on a few things on it tomorrow. I'll take a deeper look at the content and will post back if I have any thoughts to share on that side of things.

[rsolvang]

So, I suggest that we 1) Agree on a structure and 2) Create that structure and move articles from the old repo.

Totally agree. Are there any objections to using the Diataxis Framework as a high level structure for the docs? Some arguments in favor:

• Separating references from the other content into its own category makes it easier to keep it up-to-date by auto-generating the content based on the code.
• Lowers the bar for community members to add how-to's and tutorials, as these will stand by themselves and are not too intertwined with the rest of the docs (only linking to references and explanations where needed).
• Making it easier for newcomers to look up / search for explanations on specific aspects of Hugo.

[bep]

The Diátaxis makes sense (not so much the name they have chosen, though). I suspect much clarity will come from getting a solid and simple Reference section. Earlier today I tried to find the documentation for resources.Match to link to in an issue, but didn't find it (I added some ...). The interface declarations in the Go code are always up-to-date and precise, so we can get lot of value by using that directly.

With that, ref Diátaxis:

• The Reference, section will be mostly redone from scratch (and much less verbose than what's currently there).
• With that up and running, again according to Diátaxis, I think it makes sense to also create a Explanation section -- which can be referenced to/from.

[rsolvang]

The current docs mostly fit into the reference and explanation categories, although intertwined. I think that a lot of the existing content can be reused for the explanation category, although with some manual parsing and touching up to fit the new structure.

With that in place, the how-tos and tutorials can be written, covering specific use-cases. This is where we need input from the wider community, asking what we wished existed back when we starting to learn Hugo from scratch. Having written (most) of the reference and explanation material first, makes it possible to link back to the "dry" documentation from the how-tos an tutorials.

This could go both ways; the reference and explanation docs could contain a "further reading" section, listing related docs like how-tos ant tutorials based on tags or custom taxonomies. I believe something similar is done in the current docs?