Proposed Source Organization for Hugo Docs Concept

dev
1

@bep @digitalcraftsman @spf13 @moorereason

I cloned the docs today and spent some time listing out and reorganizing the content/source in a way that I think might be a little bit more scalable and easy to manage. I ended up writing about 6 pages of notes as well, which are not included in this post.

This is an extremely rough draft, but I’d like some thoughts. In addition to this new organization, I’d be willing to put together everything else that would go with a full-fledged content management strategy, including, but not limited to, standardized front matter, content standards (eg, heading structure, input/output code blocks, taxonomies), more detailed instructions on how to contribute to the docs, etc.

I also have some ideas regarding shortcodes and perhaps sample source that can be referenced in the docs to make it easier for beginners to grock. This is a huge overhaul of the docs, so I’m not going to pretend that I can get this done in a week. Instead, I’d like some feedback with the goal of finishing the scaffolding (that is IA, not necessarily presentation or templates) for the new docs by the first or second week of December.

I’m curious as to how the site is currently being hosted. I’d like to use Wercker or Netlify (that is, if this actually takes off and the maintainers like it) so that I can build some image resizing, etc, in to make doc updates quicker, which will hopefully eventuate in a richer experiences for learners.

Here is what I have so far for organizing content/. This should provide some insight as well into what a new nav might look like:

  • About Hugo
    • Features
      • Introduction to Hugo
      • Aliases
      • Builders
      • Taxonomy Support
      • Development
        • LiveReload
        • Fastest SSG
      • Pagination
      • Theming
      • Etc…
    • Release notes
    • Roadmap
    • License
  • Getting Started
    • Installation (the “tutorials” for each install would move to this section, which is much more intuitive)
      • OSX
      • Linux
      • Windows
      • Download Hugo
      • Install from Source
    • Using the Hugo Docs
      • Sample source (essentially a very basic sample site source org that could be referenced throughout)
      • Sample Source Explained
        • Sections (posts, pages)
        • Data
        • layouts
        • static
        • etc…
    • Configuration
  • Project Organization
    • Source Organization in Hugo (Intro)
  • Content
    • Supported formats
    • Front Matter
    • Site Sections
    • Types and Layouts
    • Archetypes
      • Creating files from command line (Generators)
    • Content Summaries
    • Extending Markdown
    • Multilingual Mode
  • Templating
    • Hugo Templating Introduction
      • Golang Primer
    • Page Types
      • single
      • list/node
      • homepage
      • rss
      • sitemap
      • 404
    • Ace Templating
    • Amber Templating
    • Template Blocks
    • Template Partials
    • Template Functions
    • Template Variables
      • Site/global variables
      • List/node variables
      • Page Variables
      • Scratch
    • Homepage Template
    • List Page Templates
      • Cascade
      • Ordering/sorting/weight
      • Etc…
    • Single Page Templates
      • Cascade
      • Etc…
    • Content/Template views
    • Taxonomies
      • Terms List
      • Taxonomy List
    • Shortcodes
      • Shortcode Types
        • Syntax highlighting (built-in)
        • Rest of built-ins, etc…
    • Data Templates
      • Local files
      • Data-driven content
    • Template Debugging
  • Themes
    • Introduction to Themes
    • Installing and Using Themes
    • Customizing a Theme
    • Creating a Theme (pulled from tutorial as well)
    • Themes Showcase
  • Troubleshooting
    • FAQs
      • hugo new aborts with cryptic EOF error
      • Categories with accented characters inaccessible
      • CSS files will not load
    • File an Issue on GitHub
  • Developer Tools
    • Hugo Command Line Reference
    • Editor Plugins
  • Deployments and Hosting
    • Hosting on GitHub
    • Hosting on Gitlab
    • Hosting on Bitbucket
    • Hosting and Deployment on Netlify
    • Frontends
      • rango
      • enwrite
      • caddy-hugo
      • hugopit
      • lipi
      • etc
    • Commercial Services
  • Migrations
    • Migrating from Jekyll (formerly in tutorials)
    • Migration tools
      • JekyllToHugo
      • ConvertToHugo
      • ghosttoHugo
      • Octohug
      • wordpress-to-hugo-exporter
      • tumblr-importr
      • tumblr2hugomarkdown
      • drupal2hugo
      • hugojoomla
      • blogimport
      • contentful2hugo
      • etc
  • Site Showcase (Possibly “Built with Hugo?”)
  • Community
    • How to contribute (formerly in tutorials)
    • Mailing List
    • Discussion Forums
  • News & Articles

You’ll notice a few major changes. Don’t worry—if you see a missing sub-page or subsection of a page, it’s probably included in the "etc"s in the above list. That said, I think it’s worthwhile to get rid of the “extras” section and the “tutorials” section since some really good content gets lost in it’s current location. You’ll also notice that I don’t have a landing-page-style homepage like the current site. I don’t think it’s necessary to have an entirely different layout since most people want to get straight to the docs. That said, the index.html could include the “features” section mentioned above to make the About Hugo section that much smaller.

In my experience, website sections like “Extras,” “Resources,” etc tend to become attics and dumping grounds. For example, all references to working with data files are currently in “Extras,” which makes them less discoverable. Of course, I don’t have access to the site’s GA (content grouping should be a part of the new docs), so a lot of my decisions are based on assumptions rather than data, which I’m going to say right now is inherently faulty and subject to bias.

Any and all feedback is welcome. I’ll probably start tweaking this in my own repo and will keep the community updated as I make progress over the next month. Let me know the following:

  1. If you have any requests in terms of front-end frameworks as well (eg, bootstrap, Foundation), let me know: I’ve used them all. I’d rather focus on cleaning up the docs and the information architecture than making them pretty…and that might mean less generous browser support (as in, skipping IE altogether…or maybe just 11).
  2. I can’t decide if shortcodes should live under “templating” or “extending markdown” since both seem like good locations in their own way…
5 Likes
2

I think the Extras section should contain any 3rd party plugins which supplement and complement Hugo like fingerprinting asset/static files. This will help users apply the best practices. (which are not currently under Deployments)

Also, it might be nice to link some work arounds like Google AMP generator, Facebook feeds etc., from this forum into the documentation.

Hosting on S3 / FTP might be a good section to add under Deployments/Hosting

1 Like
3

Thanks for doing this, the order makes more sense – in that it lists what most users need first. My big gripe about the doc isn’t the info it doesn’t have, but that the info most people need are so hard to spot – so we get many repeated questions here on the forum. That is also a presentation thing, but better organization is a good start.

4

@bep This would be the new source organization—and it is still not finazlied—but I intend on going a step further and doing heavy rewriting to the actual content: not that it’s all that bad now, but I’d like to give each section the following:

  1. Introduction
  2. Quick Reference (since the examples might get tedious for more seasoned Hugoers)
  3. Input/output examples (code blocks, probably with a “Copy” button)

I would also make new archetypes.

Visually, I could use the Codyhouse template already semi-built-out here:
https://github.com/spf13/hugo/issues/1725

But I’m sure I will up make considerable modifications since content should come before form…

Once I have the basic scaffolding together, I’ll publish it to netlify and invite you and the other maintainers to the repo…

5

Thanks Ryan for taking the time to create this proposal and it’s great to benefit from your professional expertise :slightly_smiling:

Your organization makes a lot of sense and I like the idea to replace the homepage with new layout. This page should prominently feature the search with some kind of form and maybe we could add cards to highlight the most used content sections. With this combination users can either find things faster based on the categorization or dive into the documentation.

From a longterm perspective this reorganization will create a better experience for new users while browsing the docs.

6

@rdwatters,

Looks like a great plan. Go for it!

Regarding a new theme: my main complaint about the Codyhouse theme is that it’s unreadable. A Grav theme would have similar issues that need to be addressed.

The cleanest theme I’ve seen so far is DocuApi ported by bep. I’m curious what the DocuApi theme would look like with TOML, YAML, & JSON config examples on the side, but I haven’t had time to play with it.

7

I agree that the contrast in the Grav theme could be optimized.

The DocuApi theme is great for documenting an API; usually such a documentation doesn’t have to display a lot of paragraphs. The problem I see is that the code examples, e.g. for endpoints of an API, use a lot of space in the 3-column layout on desktop / 2-column layout on mobile devices (where the sidebar is hidden).

Especially on mobile devices, like on my tablet, the layout doesn’t leave very much space for Hugo’s documentation which is rather text-heavy. Our docs feature some code examples but a lot of space wouldn’t be used in the right column if we display paragraphs.

I rather prefer a single column layout as we have it right now where text and code examples a ordered vertically. The theme itself is good but might not be suited for every use case.

But this are just my two cents.

1 Like
8

Re. the theme discussion – if a theme is “hard to read”, there is a fix for that: It is called CSS. Fix it.

1 Like
9

That would be the way to “optimize” a theme. Changing colors for a better contrast, fonts and font-sizes can be done rather quickly.

10

In general, we talk too much about this when we should really do. I agree about your last post about vertical code samples – so I suggest we go with a theme and make it happen – and make the needed adjustments. It would be cool if someone could make a code example shortcode (JS driven?) so we could easily show TOML, YAML etc. versions of config sections etc.

1 Like
11

I was thinking the same thing. See the theme I’m porting over from a project at work for an example.

Here it is on another dummy/dev site with different styling.

Here is the source for the shortcode itself:

https://github.com/rdwatters/ryans-hugo-theme/blob/master/layouts/shortcodes/code.html

But I think I can make it simpler for the Hugo docs by having one less param needed from the content author.

I also have a download shortcode, which could come in handy for larger files like the sample configs. You can see a sort of sample of how this would work in the editor I built for the above theme I’m porting over, although you’ll need to fill out the fields (don’t worry, just throw in some dummy text). It would look the same as the “copied” button in code blocks but instead download the sample config.toml similar to what we currently have in the docs.

I agree that color is important since it relates to accessibility, which should always take precedence over things looking “pretty.” I really like the DocuApi theme a lot, but I don’t think it works for what I have in mind with some of this stuff. @bep makes a strong point. I will keep you posted.

12

But as to the docs reorg, I would suggest you wait until

https://github.com/spf13/hugo/pull/2649

lands …

13

Agreed…somewhat. There is enough to do that this is still going to take me a few months. It’s important to set realistic expectations.

14

With respect and appreciation: is there a timeline for this project? I’m partly asking because I see several issues for this project that are broad in scope (like creating new standards for theme submissions).

Speaking as a regular user who still often references the documentation (both sites), I’d prefer a focus on merging so we users don’t have to read up both websites (the official and expanded) when stuck with something.