As the documentation of Hugo is rendered by Hugo itself, I wonder if there’s any plan to add some documentation features to Hugo.
Actually the main feature I miss is valid for any website: an internal search. I couldn’t find any open issue for this. Maybe it’s outside the scope of Hugo? Would you recommend an external tool?
A feature more specific for documentation would be a classic ‘book index’.
What do you think about it?
Search seems outside the scope of hugo. Search is a very dynamic feature, and hugo only makes static websites. One possibility is to leverage google and just do a search on your site that way. It’s not integrated, but google’s likely to be better than anything we could code 
Oh, but generating an index (like in the back of a book) is certainly ok (since it’s static). The main problem with automatically generated indices is that they are generally terrible. Maybe there have been some advances in tooling to do that, though. That would be an interesting feature.
Sphinx, a static documentation generator written in python, has an internal search. I see that _build/html/searchindex.js (generated by sphinx) contains some keywords extracted from the contents and associated somehow with a location. In this form:
preset:[18,9,22],bsd:38,pyqt4:[25,27]
Perhaps it could inspire Hugo developers.
An internal search is more cool for any website; the search inside a small/medium website doesn’t need the power of google, I guess.
I’m used to enter the index items manually (contributing to projects using texinfo or sphinx), but I’ve experienced how hard it is maintaining them.
This is a feature very specific of documentation tools, IMO this one is probably outside the scope of hugo.
Did some quick Googling and found this: http://lunrjs.com/ Sounds interesting, but not sure if it’s something that should be integrated in Hugo…
So I agree that I think it’s likely beyond the scope of any static site generator.
I like the idea of lunrjs.com, but it would only work with rather small sites… which makes it an awful solution for documentation which is often hundreds of pages.
I think there’s a lot of logical improvements to make to hugo before we try to add any search features.
One thing hugo has going for it unlike other static site generators is that the server it provides is quite performant and can be used in a production environment. It wouldn’t be unreasonable to consider adding some non static features that can be used… These features wouldn’t change hugo from being a static site generator, but could provide additional functionality for those who option to use it in a hybrid “dynamic” mode.
I’d rather focus on getting things like related content done right first.
Can you share what are some of those ‘non-static’ features which you consider that might be added to Hugo?
I honestly haven’t given it tons of thought. The two things I thought of was search functionality and the ability to handle a “contact me” form. These seem to be the two most common uses for dynamic functionality across smaller sites I see today.
lunrjs was used to implement the search in MkDocs, see this comit
MKDocs is small though, even combining all the pages it’s not long enough to be a test for longer docs. Saying that, it is still fast and well thought out. I personally don’t see this as a client side task as I’m a js for non-essential behaviour only person.
As search and contact forms are clearly not static for me they are a job for php (+ mysql) or equivalent. As someone from the fully dynamic (dark) side, I cannot see past server side search and contact forms.
I am going to experiment with one idea, but I’m newish to Hugo and don’t know Go so there are limitations. The idea is building a search index during pre-processing of the static site. This seems the perfect time to do it (rather than indexing with PHP server side), because it is at the same moment new content is added.
Once there is an index which matches all content, this can be used either server side or perhaps even as a more efficient client side approach. Only this index file would need searching.
I suppose there is also the possibility on smaller sites of creating pages in pre-processing for each indexed term (if this could be limited only to important words), but this would be loads of HTML pages even for a small site.
If I get anywhere with this I’ll update.
There are some exellent third-party support for search in Hugo. Use search engine here and have a look at the tools page in the docs.
I personally don’t see this as a client side task as I’m a js for non-essential behaviour only person.
I’m not really sure how you would accept a response from a server with search results and display them on the page without at least a little javascript. In the Jekyll world Lunr.js search of a site index is a very popular solution. For larger websites where you decide a site index + javascript solution isn’t viable then it makes sense to pay Google a few bucks a month to get access to their site search functionality. (I don’t work for them!)
For contact forms try formspree, which takes care of the server side for you. It’s free up to 1,000 submissions a month. There’s a paid option, too. (I don’t work for them!)
Thanks for the info. The search here I’m guessing is dynamic anyway as this is Discuss powered. I didn’t reallly find any 3rd party suppoort. I saw the Bleve / Hugo project, but I might come back to that when I’m more familiar with Go.
I’m a PHP person so for me javascript wouldn’t be part of the process unless using ajax.
Thans for the link. I do think Lunr has done a pretty awesome thing client side.
For me such things are not an option. I mean, if this was what static sites needed to have this functionality, I would stay in the CMS domain (because why move from dynamic sites to static, to then have to use other peoples dynamic services?). I also wouldn’t use Google search because I’m not comfortable promoting the data storage / usage / advertising ethos they use.
Forms are not an issue. Actually I must admit to being confused why people use off-site form services (especialy with restrictions or cost). Almost any Linux based hosting will have PHP mailer, and building a HTML / PHP contact form is easy (or can be copied and pasted from online tutorials). Or I’d even go with a Joomla, Drupal or Wordpress install in the background to exist just for form pages, with styling to match the static site. Yes it’s overkill, but it’s not going to affect the performance of the static pages.
Interesting though as I’m leerning a lot from this thread. Thanks for that.
Some people just want to use simple and flat static pages without dealing and maintaining CMS’ like Drupal or Wordpress. Also, many users choose Github as a free hosting service which doesn’t support scripts at all. But the choice of the right tools depends on your needs.
And if you don’t want to use a third-party service for a contact form then write your own small PHP script. This could sanatize the input of your contact form and send you the actual email as a proxy. formspree does nothing else.
@digitalcraftsman I couldn’t agree more on both your points. I should stress I did not ask about building forms, i was only replying to a previous comment.
Your first point is exactly why I try to stear some users / admins away from CMSs, and why I’m here. I think many people ( and developers unfortunately for clients ) build sites with them when the dynamic nature of the CMS is not needed.
It’s just that when the alternative is a site with search quota restrictions, or that requires payment for the service of searching their own site, or relies on Google then it’s not what I want to offer, It’s not that the company providing the service should do it for free. It’s that the site then becomes something other than a static site replacing the CMS. It’s become dependent on 3rd party services that may or may not continue or remain free or at a certain price level. All I see that doing is going full circle back to the CMS.
Also on the search topic, the github explanation and code from sebz (hugo + grunt + lunrjs) is excellent.
We’ve started using gitbook for some of our documentation. Really like the feature set for easily generating high quality documentation. However, would really, really like to have a Hugo template like gitbook’s templates. Hugo seems much more versatile than gitbook.
Anyone look into porting gitbook themes to Hugo?
I think it shouldn’t be hard to do. It’s mostly someone taking the time to port the theme over. I don’t believe they support anything that Hugo doesn’t so it should be a pretty straightforward port.
I would say that this pull request will go long way towards getting GitBooks rendered in Hugo:
I took a stab at porting gitbooks more or less using their theme. The initial (unexciting) results are at https://github.com/dblezek/bookish-docs.
Not sure the experiment will work though, I can’t figure out how to organize into “Chapters”. Originally I thought of using Sections, but I couldn’t figure out how to order them. In the current checkout, I’m using Menus, but their ordering is ambiguous (they are a map). Need to be able to order Sections or Menus (or some other Hugo construct) to have a stable chapter order. If more people are interested, I’d be happy to continue working on this. But for the moment, I’m going to have to fall back to gitbook.
To try it out:
git clone --recursive https://github.com/dblezek/bookish-docs.git
cd bookish-docs
hugo server --watch --theme bookish
And open http://localhost:1313.
@blezek I opened up this issue:
So I’m interested. Really. Your section ordering issue will be solved when Nodes get their front matter (with weight). I have been thinking about this on-and-off, but haven’t found the simplest design, but it will arrive, and pretty soon.