> Anyone who knows me well (in the tech industry at least) knows that I’m a major Hugo bigot<p>"Bigot" is likely not the word you are looking for here - it generally has the connotation of someone who looks down or discriminates against those they consider lesser, e.g. racists or sexists. Maybe "champion" or "fanatic"?
Here's Classy Docs for Gatsbyjs - a pure react based static site generator.<p>Remember, you need to write JavaScript anyway..it's probably far more productive to go all the way.<p><a href="https://greglobinski.github.io/gatsby-starter-kit-docs/classy-docs-starter/" rel="nofollow">https://greglobinski.github.io/gatsby-starter-kit-docs/class...</a>
I like it, but would you consider toning the color scheme a little down? Or maybe be a bit more sparing with color? The massive field of bright pink smacked me in the eyes when I opened it up. A good documentation theme should get out of the way so the reader can focus on the text rather than the colors.
One dependency:<p>Anchor.js — Provides nice clickable/linkable anchors for Markdown content<p>Almost 6K minified to do something that the browser can do natively?... I know I've been out of frontend for almost three years but I'm still confused :D
Related: for anybody looking for [another] great tool to create a documentation website, take a look at Antora[1]. It uses the Asciidoc/Asciidoctor toolchain.<p>[1]: antora.org
I just configured VuePress ( <a href="https://vuepress.vuejs.org/" rel="nofollow">https://vuepress.vuejs.org/</a> ) for our frontend project docs at work. Having statically built docs is great and having the ability to document your Vue code with Vue-enabled markdown is a great bonus.
I love Hugo. My personal blog and my tech blog are both built with Hugo, with an extremely simple AWS deployment pipeline. I’ve been looking for a great documentation theme , but I haven’t found one to my liking yet (closest is maybe hugo-theme-book or hugo-theme-docuapi). If v0.1 is out by end of 2019 I’d love to test drive it for a project I’m planning out early 2020.
An example of a (somewhat) similar type of static documentation site theme, but for Jekyll, is a project I’ve been participating in[0]. Born primarily as a side effect of putting online the projects from Ribose Open, it’s somewhat idiosyncratic and (ironically) lacking its own site, but we’re getting there. It’s being actively dogdfooded[1].<p>[0] <a href="https://github.com/riboseinc/jekyll-theme-open-project" rel="nofollow">https://github.com/riboseinc/jekyll-theme-open-project</a><p>[1] See, for example, <a href="https://www.rnpgp.com/" rel="nofollow">https://www.rnpgp.com/</a>
This is an excellent idea. My workplaces have often used github or confluence for documentation, but they're slow, and offer limited customisation. Static site generators make a lot of sense for this use case.
The line width (number of characters per line) is way too long. You should aim for 50-60 characters per line in a column for maximum legibility.<p>See (for example) this: <a href="https://practicaltypography.com/line-length.html" rel="nofollow">https://practicaltypography.com/line-length.html</a>
My goto tool for documentation these days is mkdocs with material theme <a href="https://squidfunk.github.io/mkdocs-material/" rel="nofollow">https://squidfunk.github.io/mkdocs-material/</a>
Docsy doesn't break keyboard scrolling in Qutebrowser. Tract does not work for me at all. Also, while I'm sure it's configurable, the neon pink is burning my eyes in a dark room and constrasts terribly with bright white.
That looks really nice! Recently had to create documentation for Prism OS (<a href="https://prismos.dev/docs" rel="nofollow">https://prismos.dev/docs</a>) and I decided to use docusaurus since it seemed like the quickest way with sane defaults but it ended up taking way longer to setup everything before I could focus on writing the documentation. Is there a easy to use platform to quickly spin up documentation pages without coding ? That would also be really helpful since non technical support or content writing staff could then also contribute
A while ago I looked into all Hugo solutions for documentation and have to say this looks very clean and simple!<p>I'm still looking for something that let me define a top-root level index for documentation of several products (much like <a href="https://learn.adafruit.com/" rel="nofollow">https://learn.adafruit.com/</a>) but found none (also Jekyll-based). I rolled my own based on Hugo but my CSS-formatting and HTML-generating skills are those from a firmware developer :)
I am not familiar with Hugo but I watch out for documentation stuff.<p>How hard would it be for a casual user to add some search capabilities ? IMO, that's a key point to have.
I'm looking for something a bit more powerful than the Wiki bundled with GitLab (which uses Gollum). I started with MkDocs but moved it over to GitLab Wiki because I thought the instant feedback. I now have mixed feelings.<p>I've used Hugo in the past for a few sites, but the amount of boilerplate required, even though minimal, is a bit of a hurdle for an internal wiki.<p>Has anyone been here? Suggestions?
We've started using mdbook [1] at work for our docs. It has search, it's customizable, and if you really need HTML in places you can do that inside your markdown to get the best of both worlds.<p>[1] <a href="https://github.com/rust-lang/mdBook" rel="nofollow">https://github.com/rust-lang/mdBook</a>
The article made me discover Docsy: <a href="https://www.docsy.dev/" rel="nofollow">https://www.docsy.dev/</a><p>For some reason the author dismissed it, but I personally find the project quite nice!
Thank you for your post, I like the theme and the idea of static generator creating the documentation.<p>How could anyone include search in these static sites? Is there any theme that could provide such functionality?
For more Hugo themes, you can check out <a href="https://uicard.io" rel="nofollow">https://uicard.io</a><p>They have incredible themes
a. this looks awesome<p>b. if you're looking for a copy button for code blocks, I've seen it done (and done it myself) with some vanilla js.<p>c. the more vanilla js the better.<p>d. can you make code blocks have tabs for different languages?<p>e. this is awesome (did I mention that already).<p>f. I will find an excuse to use this.<p>g. I use ddg for my site search, but Google custom search works too, and is a bit easier to work with.