New theme for Hugo docs – http://hugodocs.netlify.com

[sjardim]

I created a new theme for the Hugo Documentation.

Check it out: http://hugodocs.netlify.com/content/organization/

What do you guys think? There's some issues to do, like the search box and some style improvements on the medium and small media queries. :)

Forgot to mention that the theme is based on a CodyHouse template: https://codyhouse.co/gem/responsive-sidebar-navigation/

[bep]

Wow, that's a nice Christmas present. Much nicer -- and much cleaner typography.

@spf13 would be the man to decide on a change, but I'm all for it.

Two small improvements I noticed:

• The titles are hidden under the navbar when following a link in the ToC. I remember putting a CSS rule in to handle that in the "old doc site".
• The menu icons is distractive when the screen gets smaller (mobile), maybe hide them on smaller devices?

[digitalcraftsman]

Awesome work @sjardim - a new year, a new facelift :+1:

[spf13]

This is fantastic. I love the new theme.

I think a few minor tweaks would make it perfect, but overall it's a significant improvement over the current site and we should launch as soon as it's ready.

Thanks @sjardim !!

When this is solid, any thoughts on the homepage?

[moorereason]

Can you make sure all of the colors (foreground+background) are WCAG 2.0 Level AA compliant? See #1678 for more details.

[anthonyfok]

:clap:

[sjardim]

Hey guys! I’m very happy that you liked it! I was thinking to do it for a couple of months, but didn’t have the time to create a design from scratch and after I found this nice template I gave it a shot.

I put it together in a few hours yesterday and posted it here to find out what’s the reception would be, but as everyone saw, there is a lot of small issues, like the ones @bep mentioned, and others. I need to check it in all major browsers and do other improvements. I’ll be working on them in the next days.

@spf13, first of all, thank you for Hugo. :) And yes, I have a plan to create a new design for the homepage, I’ll share my thoughts on it later.

@moorereason, great reminder! I’ll sure check the contrast of everything and I’m planning to improve the overall accessibility in the future.

I’ll keep you guys posted. What’s better, here or in the Discuss forum? Or both?

Happy holidays for all!

Best regards, Sergio

[sjardim]

Steve, I forgot to mention that I recreated, very quickly, Hugo's logo in SVG because I didn't find it in vector format anywhere to export. Do you have it there?

[spf13]

I have an illustrator file with a bunch of the hugo logos in it (many just ideas and never used). I can email it to you if you send me a dm on gitter or an email or something with your email address.

On Thu, Dec 24, 2015 at 11:20 AM Sérgio Alves Lima Jardim < notifications@github.com> wrote:

Steve, I forgot to mention that I recreated, very quickly, Hugo's logo in SVG because I didn't find it in vector format anywhere to export. Do you have it there?

— Reply to this email directly or view it on GitHub https://github.com/spf13/hugo/issues/1725#issuecomment-167132479.

[ghost]

Very nice, when will it go live ?

[digitalcraftsman]

@tuxy currently, this repo only contains a redesign of the docs and is a work in progress. @sjardim is mostly the man behind the redesign.

But by adding some CSS we could integrate the search in the current docs. What do you think @spf13?

[sjardim]

Hi guys, I pushed some changes (mostly UX corrections) but not yet the search. I'll be doing more improvements on the next days, including merging the new search system.

Also, there are some content organization I'd like to make to improve the information architecture.

After the docs are officially online

• A new homepage design (gohugo.io)
• Changes on text to make some pages more easily understandable (more examples with rendered output for instance).

[spf13]

@digitalcraftsman please make that happen. I would love for someone else to step up and take over the responsibility of the website. It would allow me to focus more on addressing some deep refactoring of Hugo, something that I feel is likely that only I can do.

I love the effort and direction @anthonyfok, @sjardim, @digitalcraftsman and others are doing with the site and look forward to what's coming.

[digitalcraftsman]

@spf13 sure. This way we could replace the current Google CSE form. It's great to hear that you find more time to refactor parts of the codebase, especially in the context of some redesign discussions that we had in the forum.

[spf13]

@sjardim Where are we at with this? It would be great to launch it soon! Do you need any help taking it over the finish line?

[sjardim]

Hi @spf13, @digitalcraftsman and everyone else! Sorry for my disappearing, things got crazy in my work when I got back from vacation with the family and I couldn't work on the things to finish it up.

So, what's need to be done: 1 - Merge the search using Algolia. @digitalcraftsman, can you help me on this? 2 - Small css adjustments on some tutorials pages. I can do it. 3 - Merge the content source files with the updated version. To build the menu, I made some changes on the front-matter on about 10-15 files. Can someone help me on this?

Steve, are you going to keep the url structure or move the docs to docs.gohugo.io? Or maybe gohugo.io/docs/?

[spf13]

I've not given enough thought to migrating the URL structure. I do think it's probably about the right time to split things into a Docs site and a landing page site.

Whenever we do it we should consider that the docs will likely be available in multiple languages in the future and should plan accordingly.

Additionally we will likely add a blog at some point as there has been interested expressed in doing that.

I think probably the right approach is gohugo.io/docs, gohugo.io/blog, etc. Future languages could use subdomains eg. es.gohugo.io/docs

Universal registries like the themes.gohugo.io are probably best left as a subdomain.. especially since they are likely to be hosted separately.

Do others have an opinion on this? @anthonyfok @digitalcraftsman @moorereason @bep

I can also help with #3 when we are ready.

[rdwatters]

How about the following?

/docs /themes /blog /tutorials /shortcodes-and-partials

This is ambitious, but maybe keep the docs to just talking about config, functions, templates, filters, deploy, and other parts of the core.

Thoughts?

Sent from my iPhone

On Feb 22, 2016, at 3:31 PM, Steve Francia notifications@github.com wrote:

I've not given enough thought to migrating the URL structure. I do think it's probably about the right time to split things into a Docs site and a landing page site.

Whenever we do it we should consider that the docs will likely be available in multiple languages in the future and should plan accordingly.

Additionally we will likely add a blog at some point as there has been interested expressed in doing that.

I think probably the right approach is gohugo.io/docs, gohugo.io/blog, etc. Future languages could use subdomains eg. es.gohugo.io/docs

Universal registries like the themes.gohugo.io are probably best left as a subdomain.. especially since they are likely to be hosted separately.

Do others have an opinion on this? @anthonyfok @digitalcraftsman @moorereason @bep

I can also help with #3 when we are ready.

― Reply to this email directly or view it on GitHub.

[digitalcraftsman]

Hi everyone,

@sjardim I can finish the pull requests for the search. Beside the need to fix the alignment of the input field I found another bug. After including the required Algolia Javascript file I noticed that the hamburger menu icon doesn't show up on smaller screens. I've no idea what causes this behavior. Could take a look this? If I remove the JS file everything works as expected.

Furthermore, we would need to adjust the crawler and API keys for the real website.

---

@sjardim you're working with codekit for the automatic compilation and compression of assets. This app seems to a great tool in your workflow. But it can be a bit annoying for users on other platforms (like me) or those who don't want to spent the money on this great tool.

It would be great to have something more platform-independent, especially if other users want to contribute changes but don't want to setup all of these tools.

I use a SCSS compiler plugin for Sublime and installed Bourbon at the path that is used in the main stylesheet. However, codekit seems to inject this dependecy somehow and everytime I commit I need to make sure that I don't include Bourbon accidently. .gitignore would be the rescue, but I think you got it.

---

@sjardim Currently, the landing page of the docs (see here) lists instructions for the installation etc. Wouldn't it be better to have some card elements that point to different major areas of the docs, like:

• first steps (installation, quickstart guide)
• configuration
• themes (themes.gohugo.io, not the explantion of "How to create your own design")
• shortcodes-and-partials / themes section (this would be the actual "How to create your own design" section)
• tutorials
• blog

It's just a suggestion.

---

@rdwatters you're planning to restructure the docs. I like the idea of decoupling the configuration from the styling. But I would merge /themes and /shortcodes-and-partials since they are very closely related.

We already had some great content ideas for the blog. Were would you put tutorials? They could be part of the blog but also an important part of the docs. The blog could showcase new features of upcoming releases in a compact way. Otherwise, the docs are the place where you would look if you've questions.

---

@spf13 you mentioned the use of custom subdomains for possible translations of the documentation.

Does this mean to create a new branch for each translation? If this is the case, assets and other things would be redunant in the repository and more difficult to update. Alternatively, we could just use a prefix in the URL, like gohugo.io/docs/es/some-content-here.

[gntech]

For translation of the docs site, may I suggest that we use the solution created by @abourget presented in #1734

[rdwatters]

@digitalcraftsman. About to takeoff so I'll keep this short, but I'm onboard with shortcodes and themes being packaged into one. As far as tutorials, hopefully the community will continue to generate those on their own blogs, but I think the docs can take a more tutorial-based approach. With the recent semi-rapid expansion of templating functions, etc, I don't think the current site architecture is going to be navigable for much longer. For one thing, I think each function should be a separate MD file and have a corresponding function archetype. Then new functions can be created from the command line and the author will have a better understanding of the expected examples. Same goes for variables. Again, an ambitious undertaking but not impossible.

Also, your port of the material docs is fantastic. I can help move the search to lunr.js until jsonify and the ability to write directly to an index.json are a reality. More to come when I land in Chicago.

[digitalcraftsman]

Hi @rdwatters,

it's for sure not ideal to create a huge list of template functions. I could image that new user feel lost in this (growing) jungle. But what do would you put on a page that documents a single functions? The most of them only have a one-liner as description and a little example.

A lot of people showed interest in the usage of the material theme. The question is what should happen with all the work that @sjardim already invested in his theme? Should we really switch? If this is hypothetically the case it would be the least. My port isn't finally finished. Furthermore, the original theme creator also announced some smaller work on the details of the theme.

The integration of the search shouldn't be difficult because @bep already created a good proof-of-concept.

[moorereason]

Putting a bunch of functions on a single page is not a problem to me. We just need to do it cleanly. Don't know how the Goa guys do this sidebar TOC, but it's handy.

[digitalcraftsman]

This is no magic. They used Javascript to generate the TOC.

I did the same with the Material theme. A JS-snippet searched all h2-headers in the current page, extracts the title, and appends a new item to the TOC with the header title and it's id as link.

[rdwatters]

@digitalcraftsman @moorereason it can still be on the same page, but I'm talking about managing each function as a separate file. Again, ambitious, but something like this would certainly be helpful for people that are new to Hugo. The sidebar toc is great. Here is another example of a way to do the same thing for SSG docs. Looks like GOA is using Bootstrap, so I'm guessing it's scrollspy.

<!--functions/delimit.md-->
---
title: delimit
description: Loops through any array, slice, or map and returns a string of all the values separated by the delimiter. An optional third parameter lets you choose a different delimiter to go between the last two values. Maps will be sorted by the keys, and only a slice of the values will be returned, keeping a consistent output order.
scope: [lists, taxonomies, terms, groups]
last_updated: 2016-03-14
---

### Basic Layout

Put the basic html layout here.

### Basic Output

Put the rendered html layout here.

### Advanced Layout

Put the advanced html layout example here.

### Advanced Output

Put the rendered html layout here.

This would be a lot of work, but you can see how the function, variable, archetype, etc would be created. This also wouldn't preclude the above GOA example, since you could range through the files and append the dasherized title to gohugo.io/docs/functions# if you want the single-page scroll, but I think that's confusing content with form.

The obvious need would be a sample repo that contains content files that relate to the docs. Something to the effect of:

|-content
  |-articles
  |-authors
  |-events

I like this approach because it combines the tutorial and the docsite into one. You see this sort of thing, at least to some degree, in a lot of open source projects with buttons like "see code," etc. Plus, standardizing the info for each function (it might not be needed for all the other content types) will be better for readers and sets expectations for improved features. Prototypes are always better, so I'm happy to pull @digitalcraftsman Material project and start hacking away at the way I think the docs could be organized....

Does that make sense?

[bep]

This would be a lot of work,

Yes it would.

[digitalcraftsman]

The reorganization of the documentation while take a while. But what happens with all the new commits that will be pushed to the current docs during the reorganization?

Having both versions in sync could avoid a lot of trouble afterwards.

[rdwatters]

@bep

Yes it would.

Nothing worth doing is easy.

I have a lot of questions about source reorganization and comments about how the content could be reorganized and rewritten, @digitalcraftsman. What do you think about where to ask these questions and make these suggestions? You make a good point about the new commits. I've started fiddling with an idea of how could be reorganized. I've sucked up enough from the Hugo community as a non-developer that working on the docs is the least I can do.

[moorereason]

@rdwatters, Those are interesting ideas. I think we should have the best documentation that we're willing to maintain. This looks ambitious, so I hope everyone is committed to this idea.

As far as the structure and re-organization is concerned, I'm thinking it will make more sense once we implement Steve's ideas around allowing multiple files to make up a page.

I'm hoping we can release 0.16 soon. I'd say we keep the docs site structured as it is for the 0.16 release (perhaps deploy a new theme) and create a new docs branch for the reorg with the 0.16 release as the starting point. During the 0.17 release cycle, we continue updating the old docs until you guys are done with the reorg.

So, the less time it takes to do the reorg, the less time it will take to catch up to changes in master.

[bep]

The docs for the functions should live in /data/template/functions.toml or whatever -- suitable for ranging and sorting. Not in hundreds of md files. That would be worth doing if we need the clever JS toc thingy.

[rdwatters]

@bep @moorereason works for me. If it's cool with both of you, I might still play around with this idea and just throw a prototype site out there, maybe even with @digitalcraftsman 's swanky Material theme. How can I get a grip on the new functions and features being added with v16 for my own sanity?

@bep, as far as "hundreds of md files," there are only 44 functions in my current folder, which I really don't think is that much. That said, with "hundreds" of functions and explanations, do you think it's going to be easier to edit and maintain an exceptionally long .toml file rather than allow people to write hugo new function/my-new-function.md and then have a markdown file auto-generated that tells them the necessary metadata for it to be added to the docs?

The JS TOC would work either way.

The data/template/functions.toml idea makes sense, but I don't see how that's any different than doing something similar with markdown files instead:

{{ range .Site.pages }}
   {{if eq .Section "functions" }}
   <li><a href="#{{.Title | urlized }}">{{.Title}}</a></li>
   {{ end }}
{{end }}

But DRYer, probably, or whatever....

[digitalcraftsman]

@moorereason So, the less time it takes to do the reorg, the less time it will take to catch up to changes in master.

Good approach.

@rdwatters What do you think about where to ask these questions and make these suggestions?

So, is an issue a good way for longer disucussions? Github allows us to create small TODO lists inside an issue. I don't know if this satisfies our needs. Let me know what you think.

You all are probably not sure when exactly the next version of Hugo will be released. I'll be inactive in the next week.

[bep]

But DRYer, probably, or whatever....

And less hacky. Markdown content files is great for prose, longer content. This is a list of short definitions, a database of sort, with a title a short text and an example.

[rdwatters]

So then something like this in a data file:

[functions]
    name = "delimit"
        definition = "Yada yada yada"
        scope = [lists, taxonomies,terms,groups]
        basicLayout = ""
        basicOutput = ""
        advancedLayout = ""
        advancedOutput = ""

And then have that for all the functions in a single file? So if adding new features requires adding a new entry to this list, do you think this is an easier approach? What about functions that require the wiggle room of some added description? For example, I'd offer that Scratch, which is awesome, isn't as well leveraged because it should probably be a function rather than an entry in "extras."

Either way, if I play around with making the separate markdown files and it's a PITA, it would be that much easier to script into a .toml. Added structure == freedom.

I think the docs site could benefit from some content strategy, particularly content modeling. I'm happy to help in whatever way I can.

[bep]

But I'm a little bit confused as why this discussion happens here -- it must be possible to release a new theme for the doc site and then do the changes as separate issues. Like doing one thing at a time. Iterations. This issue is getting old already. Get it out there.

[rdwatters]

@bep Agreed, and that's my fault.

@digitalcraftsman GH works for me as a separate feed.

And talk is cheap. I've talked long enough about resorting the docs. I might actually have free time in the next couple weeks, so putting together something I can just show the team makes more sense. Thanks all.

[digitalcraftsman]

@rdwatters by accident I discovered the docs of Grav, a flat-file CMS written in PHP. The project intersects many of Hugo's capabilities and I think it's a good example for structuring content.

[spf13]

@digitalcraftsman Wow. That's a great site. Really well designed and the content is really clean. Inspirational.

[spf13]

Which isn't surprising since grav was created by a theme company http://www.rockettheme.com/.

[rdwatters]

Wow, definitely looks fantastic. I like the method of structuring your docs in that order. I can pull some ideas from this.

[singh1469]

Any update on if/when this template will be going live?

Bump

[bep]

This issue has been automatically marked as stale because it has not been commented on for at least four months.

The resources of the Hugo team are limited, and so we are asking for your help.

If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.

If this is a feature request, and you feel that it is still valuable, please open a proposal at https://discuss.gohugo.io/.

This issue will automatically be closed in four months if no further activity occurs. Thank you for all your contributions.

[bep]

Note/Update: This issue is marked as stale, and I may have said something earlier about "opening a thread on the discussion forum". Please don't.

If this is a bug and you can still reproduce this error on the latest release or the master branch, please reply with all of the information you have about it in order to keep the issue open.

If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.

[sjardim]

Hi @jhabdas, the repo for the template is here: https://github.com/sjardim/docs.gohugo.io :) Codyhouse's terms are not an usual OSS license but its clear to me that we can use the resources even for commercial work (but not for resale): https://codyhouse.co/terms/, so I don't see a problem.

[digitalcraftsman]

@sjardim thanks for the initially pushing the idea of a redesign for Hugo's website. This issue is stale since a while and a few others pushed this idea further to a redesign that is likely to be deployed soon. Those are namely @rdwatters for the editorial part and @budparr who's finalizing the design.

Perhaps we can see turn the current code base into a documentation theme.

Cheers, Digitalcraftsman

[shyamal890]

@digitalcraftsman Sorry, I didn't get a clear answer from the thread, is making documentation possible with Hugo?

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.