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.
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
hugo server --watch --theme bookish
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.
@mikeaja & @bep, thanks for the great suggestions. Looking at the Hugo site itself, navigation is handled as one big menu.main menu, and ordering is supplied by weights. That would work fairly well. Was hoping to be able to use Sections, possibly with some hints in the config.toml file. Ideally, the book could be groked from the file structure, with a creative theme.
I don’t really see why you can’t use Sections. I would say it doesn’t really matter what is officially navigation. For me the menu feature is more about pre-set front matter, and saving time for typical menu situations. But any Range on any defined set can make menu links.
After trying out a bunch of different documentation generators, I decided to use Hugo for building our Docs site.
I’ve altered the section/post output to display content in longform - as series of cards rather than nested pages… the idea being to build something with an I.A. more akin to ReadtheDocs, but with our own custom design approach and various effects.
The main reason was the availability to the ‘readthedocs’ theme and the ease with which I was able to set it up. I think that is because MkDocs is specifically built for Documentation. I think for Hugo to have the same ease we need some ‘starter packs’ which have stuff pre configured for ‘Project Documentation’, ‘Blog’, ‘Website’ etc,. I’ll add more comments after I spend some time analyzing MkDocs.
First, that site is gorgeous. Like Isaac Hayes sexy gorgeous. Second, I just took a really quick look at the way you did the sections as ‘cards’ which reminds me of a project I’ve been working on for eons in my ‘spare’ time. Lots of writers (not code writers, English/Spanish/etc writers) use some kind of virtual pasteboard layout for chapters/books. Using Hugo and/or gitbook to format output is a great idea, especially since the formats are already built into gitbook export. However, nobody has written a pleasant way to write prose and rearrange documents and then wired that up to something to spit it out. At least not that I’ve seen. I’d rather write in vim than gitbook’s interface.
Anyway, great work, I am very impressed and will look more into that public repo.
@flynnduism that doc site looks absolutely fantastic. I see that the license is MIT – but I expect there are some “not so generic” stuff in there that means that to use the theme for something else you would have to do changes to the theme itself? Or at lteast override some templates?
/cc @spf13 - we have had other people making the most beautiful themes wanting to be added to the themes repo – but as the themes are sub folders in another repo, I have not clue (don’t think it’s possible) to do so. It would be great if we could do that, but I believe that means adding another service outside of GitHub.
Agreed. The current solution works in that it’s easy and only depends on git.
An ideal solution would be a repository system that would be able to contain / share themes, partials and shortcodes and could support github full repos and files and directories within a repo. That would be a lot of work though and I don’t think worth it yet given some of the other priorities.
@flynnduism This site looks freakin’ fantastic!
I don’t suppose some of this design is MIT, eh? Haha. I’m looking for a really great theme for some internal-only documentation at my work. Nevertheless, looking forward to the blog post and nice work!