Use of Flexbox for the Hugo documentation

I’ve heard the Hugo documentation site needs “a total revamp.”

To that end, I’ve submitted a pull request which converts the Hugo documentation site, so that it uses the new and exciting CSS3 features generally known as Flexbox.

Could please please try it, and let me know what you think?


We need a total revamp of the docs site.

@moorereason Actually, in a way, that pull request (which I mentioned above) kind of represents a total revamp of the docs site.

Alternatively, what kind of revamp do we need?

I’m fiddling with so much Hugo-related, so I try to stay away from the docs site … But I tried your PR a while ago, and while it may solve a lot of issues, it also looks different typographically (to little in the padding / margin department maybe).

1 Like

First of all it’s great to see that you took the time to address such issues. But I agree with @bep that the docs look typographically different:

  • the previous / next buttons to switch the article/post/page in a section seems to be a little bit too small in terms of their width
  • I preferred the old menu on the left were the menu entries of a section were seperated by a line
  • many elements have a relatively small font-size, e.g. the footer’s text (“Last revision: …”)
  • some of the ui elements should have a bit more margin / padding which makes them more distinguishable from others

This are just my 2 cents and opinions can differ.

I tried your PR a while back and felt the same as the others have said.

I’d prefer to see finished and merged. There’s a lot of discussion in that PR that have little to do with the design that we could do later (reorganize content, search, etc).

/cc @sjardim @rdwatters

1 Like

Sure, as long as the priority is to make the site prettier and remove some of the spaghetti front-end code from making the site less navigable, particularly on mobile. I’m deferring to @sjardim on this one since he is the one that reworked the docs to use the CodyHouse theme. As far as reorganizing content, search, etc later, I think that would likely necessitate a redesign, if for no other reason than things like titling and terms need to be changed in multiple areas to keep the site intuitive. Content before form.

@moorereason You mentioned here that…

I think we should have the best documentation that we’re willing to maintain.

Is there such thing as a “documentation maintainer” in OS projects? If so, I’m volunteering :smile:

1 Like

Good points.

@digitalcraftsman handles most of the docs PR vetting and merging, so he’s the acting “docs maintainer” in my mind. But contributions matter more than titles. If you have the time and talent to take over maintaining a portion of the project or leading a big redesign, I, for one, would be happy to have you come alongside us.

I think everyone was on-board with your reorg ideas. We just need to make it happen.


@digitalcraftsman, @moorereason, @rdwatters: I put up a demo site to show my revamped design of the Hugo docs. (It blocks robots, BTW.)

@digitalcraftsman: Just now, I’ve addressed this.

Just now, I’ve addressed this, too.

Just now, I’ve addressed this for the “Last revision” footer text, the GitHub buttons, and the Hugo version text. Any other elements?

Fitting as much of the sidebar menu as possible (on the screen) seems a desirable goal. Plus, some of its sub-menus are quite large (e.g., “Extras” currently has 19 sub-items).

Yet if you’d like more spacing in the sidebar menu, please let me know!

For which other UI elements would you like more spacing?

@MarkDBlackwell Did you rework any of the content, btw, or is this strictly a visual redesigning of the site? If nothing else, this seems to make the menu usable on mobile, which is an upgrade unto itself.

@rdwatters The demo presents (in effect) a complete (and exact) snapshot of the content, captured January 9, 2017.

So, the changes (to the docs site) which this demo presents are merely visual (and are mostly flexbox).

Right. :slightly_smiling:

On mobile, the demo continues to work (in a graceful, fallback manner) even if JavaScript is disabled. (That way seems faster and less memory-intensive on some smartphones—such as my wife’s.)

For instance, the menu is still usable, even if JavaScript is disabled (for instance).

Printing now works well (in the demo), too.

@digitalcraftsman @moorereason @rdwatters Note this demo handles, fairly well, the stress test (on the desktop) of the Automated deployments with Wercker page, when the browser width is constrained—for instance, anywhere from 772 to 1106 pixels.

@digitalcraftsman @moorereason @rdwatters I’ve borrowed some styling—font, colors, vertical menu spacing—from the Netlify hugodocs demo site. The results can be seen in a new flexbox demo.

The combination looks good. The successor theme for the docs didn’t made much progress in the past. Hence it’s a good idea to port some ideas to the current theme.

Having to much sub-items in a menu can be fixed by restructuring them. But it’s likely that this happens automatically with the reorganization of the docs.

Regarding the layout of the UI elements this would be some possible enhancements:

  • Add more vertical margin in the header of the page, especially for the title and logo.
  • Furthermore, the hamburger icon could be more visible by using a color with more contrast and by adding a margin on the left and right.
  • The GitHub buttons on the right could have more spacing as well

  • I prefer the sub-items of the menu to be left-aligned. But this is entirely subjective.

@digitalcraftsman Just now, I’ve implemented the improvements you suggested.

1 Like

Thank you @MarkDBlackwell for investing the time to push this ideas forward :thumbsup: The changes look great and I would like to see this theme going live.

Here are a few more points that could be discussed:

  • the menu sub-times could have a greater line-height (i.e. more vertical space to it’s neighbours)
  • the parent container of the bottom panel (with the text “Last revision: XXX XX, 2017”) add a margin on the left and right. Hence the bottom panel can’t fill the whole parent container
  • are previous/next page buttons actually required? I rarely use them and prefer to use the menu on the left because I can see sections are about. In conclusion this would make them obsolete. But my UX could differ from others.
  • the accordion menu on the left highlights the current menu entry (whose submenu is expanded) as well as the previously clicked menu entry. I’m using Chrome 56 on Linux.

@MarkDBlackwell ported much of the look and feel to the current docs theme and made a bunch of other optimizations. #1725 doesn’t make much progress and this PR is already in a good shape.

A second opinion on the latest changes would be great.

I’m not a fan of this new theme. It feels very cramped, like @digitalcraftsman already allured to with mentioning the line-height of the menu items.

The hamburger in the top is also crammed along the logo, and the Github buttons are also so close together that they seem one icon. Perhaps some of these icons can be left out, placed in the footer, or moved as the last menu entry?

What seems odd to me is that at other points, a lot (and I mean a lot) of screen space is used. For instance, the icons for next and previous, which are huge relative to the size of the menu.

But what I dislike most is how much space the TOC takes at the expense of the main content:

I think the TOC is much better handled on the current documentation site (by making it hover more). To me, giving a separate column to the TOC seems an excessive waste of space to me. Perhaps this can be made collapsible? With the current appearance I’d personally rather not have a TOC.

(Sorry for the pessimistic response of me. Besides the cramming and screen space issues I very much like this approach to Hugo docs.)

To be a bit more constructive, I personally would drop the left and right navigation buttons because (a) they take up a lot of space and (b) are redundant since the menu already offers this feature.

With those buttons removed, there’s also more room for padding of the article. That’s preferable to buttons I think, since a bit more padding makes the reading experience more pleasant and makes it feel less crammed. (Again, just speaking from my personal opinion here.)

And when the TOC cannot hover or collapse, I wouldn’t show it.

Personally, I find this a much cleaner reading experience (compared to the previous screenshot I posted):

Perhaps the title in the header can also be removed, since it seems redundant to have two titles. Perhaps the search, given its feature of performing a global search, is better placed in the header than in an individual article.

Alternatively, we could show the toc at the very top beneath the search field like here. This way it’s aligned with the text from top to bottom without taking to much space on the right, especially on smaller screens.

The only reason have not replaced the current site is because only Steve have technical access to do that kind of upgrade.

And that is a limitation for any such effort. So until that is fixed … looks smashing and works fine on my dekstop browser. I can understand the need for mobile, but not mobile first … People do Hugo development on their desktops.

And, while I appreciate the efforts of thread starter, this theme does not pass the “desktop test”, so to speak. Even after several people have made the same remarks, it still has the same issues (sub par typography). on the other hand, looks smashing. If it has some problems with contrast or mobile: Fix that and stop starting to invent a new wheel every time you get a flat tire!

1 Like