Template funcs docs should live in subsections

rdwatters / hugo-docs-concept

NO LONGER MAINTAINED. See the official Hugo docs at /gohugoio/hugoDocs

17 stars 10 forks source link

Template funcs docs should live in subsections #141

Open bep opened 7 years ago

bep commented 7 years ago

Matching the tpl/* namespaces where the implementation lives, see

https://godoc.org/github.com/gohugoio/hugo

rdwatters commented 7 years ago

cc/ @budparr for any theme/design considerations here...

bep commented 7 years ago

To add to this: I don't think each func should be listed in the left menu (I think we have discussed that before, it is very long and hard to navigate currently, and it will get worse), a list of the subsections would be nice.

digitalcraftsman commented 7 years ago

With subsections you refer to the namespaces, right?

rdwatters commented 7 years ago

I think we have discussed that before

Yes, we did. Agreed that left nav list is too big to be expanded by default, but also showing only NSs assumes too much of end users; i.e., newbs can intuit more from a function's name than it's namespace. I'll defer to Bud's thoughts on presentation.

rdwatters commented 7 years ago

As an FYI for this thread, ns is already a part of the new functions archetype:

https://github.com/rdwatters/hugo-docs-concept/blob/master/archetypes/functions.md

rdwatters commented 7 years ago

@budparr Would it be easier, at least navigation wise, for me to treat the ns as an attribute for each file in this section or put files individual directories? My thoughts are that it's still easiest for end users to see an alphabetical list of functions, but clumping them together (similar to current official docs) could have value. LMK how I can facilitate.

bep commented 7 years ago

To clarify what I mean by this:

Every single md-file for every template func should be put in a file folder corresponding to the Namespace they belong to (see Godoc).
Eeach "namespace section" should then have a content file with a reasonable title + description.
The section listings could sort sub sections alphabetically, but this will be a handful, so not very important.
This should not be an alphabetical list of all functions. There is a thing called search. Use that.

@rdwatters I suggest you start by just moving files into sub folders and "see how it looks".

budparr commented 7 years ago

I agree that, if we're using subsections, it would be easier to navigate that rather than the full list. But I disagree about there being a full list somewhere. I don't find Algolia search all that useful and find myself accessing the drop-down list pretty much 100% of the time.

budparr commented 7 years ago

@rdwatters when you've moved the files, share that branch with me, and I'll work on the design aspect.