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.
That color is mostly a placeholder, and in the actual theme you'll be able to change the color scheme in the site configuration (without needing to touch CSS).
I agree that aesthetics are absolutely CRUCIAL and this will be a MAJOR focus of the project.
Fuse.js works great and is client-side. Hugo can generate the necessary JSON outputs and there is documentation on how to set it up on their website. Please let me know if you come across anything better.
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.
I've seen this rule stated in various ways, but it seems to always be a fixed value, which presumably is derived specifically for the information-density of the English language. Is there a resource on what this number should be for other languages with different information densities? (I can't imagine that you should have 60 characters of Chinese per line, for example.)
> Anyone who knows me well (in the tech industry at least) knows that I’m a major Hugo bigot
"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"?
I think more in the sense of "I believe this is better regardless of objective reality". The others convey that you like or are into something, this conveys that you won't be swayed, so anyone reading further had better be ok with that.
I just configured VuePress ( https://vuepress.vuejs.org/ ) 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.
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].
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.
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.
You can see what's probably the same issue in Firefox/Chromium as well: You can't scroll e.g. https://tract-docs.dev/docs/getting-started/ with the keyboard without first clicking into the page.
Doesn’t seem fixed to me. Also, it’s impossible to fix it in the current structure without JavaScript, because you need to either move the caret into the desired scrolling element (`getSelection().collapse(document.querySelector('.main'))`), or focus it (`document.querySelector('.main').focus()`, also requiring tabindex=-1 or similar on the element). From the presence of tabindex=1 on .main, I’m guessing you tried that one.
For a documentation thing like this, I’d generally recommend avoiding a separate scrolling pane for the primary content, but rather arranging so that it can use the document’s scrolling element. This gets the scrollbar in the place people generally expect it in web things, and makes it work regardless of whether the JS loads.
I don’t know of any good articles about the trade-offs of the various approaches, but I’ve started writing one myself. (I’m drafting a series on the intricacies of various UI patterns and their implementations, and this was actually already on my list.) Email me if you’d like me to drop you a line when I publish it (being realistic, expect to wait weeks for it).
Docusaurus is a very nice tool but in my extensive experience React-based static site generators really suffer when building large sites, much like Jekyll does. I've worked on projects with well over 1,000 pages and Docusaurus, VuePress, and others simply don't have access to the jet engine that is well engineered Go. But if it works for you, run with it!
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.
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.
I strongly disagree with this view. "You use JS anyway" is not a single valid reason to adopt React.
Use it when you build interactive web applications (because that's what it was developed for), or if your site uses heavy content-changing animations commonly used in SPAs. Documentations, on the other site, are neither of that. At least this is what I expect: I am searching for information because I have to solve a problem, not to look at nice animations or give the docs page a thumb up.
Gatsbyjs is not a dynamic application. It is a React-based framework to generate static sites. Pretty much exactly like Hugo - except that Hugo uses Go templating and Gatsbyjs uses React.
If you open the link i gave, it would solve the problem you needed to solve (and also get nice animations if you are so inclined).
The other advantage is that in the future if you want to build a dynamic application, you can continue where you left off. You dont have to rewrite in another framework. Its React all the way down.
Thanks for the clarification. Based on the Gatsby website itself and the docs it seemed that the websites generated with it also use React for the site itself. Apparently this is not the case. Still, the argument that one should better not bet on heavy frameworks for simple documentation is kinda valid, even if not applicable for the given use case.
Why React? Because there's A LOT of developers familiar with it. Why Gatsby? Has a ton of plugins and starter kits. It's also super simple to use along with modern CMSes like Ghost, Netlify, Contentful, Tina, etc.
> That's what it was developed for
React's official website recommends using Gatsby if you're building a static website.
Anchor.js — Provides nice clickable/linkable anchors for Markdown content
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
The browser does it natively if you hand code it into every page and every sub heading. What the tool does is allow you to insert the script into any page and it will automatically create anchors for all the sub headings. This saves tons of time because you don’t have to do it manually (i.e. by inserting IDs in every H1, H2, etc.)
I mean sure, if you were writing the website by hand. But every markdown processor I've used is able to derive these from headlines. And everything you can do in JavaScript you can also do when generating the page in the first place if it's just a one time modifications of the page.
Markdown parsers can auto-generate IDs for headers but they don't create a nice icon next when you hover over the header. That's what Anchor.js is for. For an example, see this page: https://kubernetescommunitydays.org/organizing.
Those auto-generated anchors remind me of LaTeX references. You have to write the anchor IDs in manually ... but when you re-word your heading you don't suddenly break all of your links to it.
That looks really nice! Recently had to create documentation for Prism OS (https://prismos.dev/docs) 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!
I'm still looking for something that let me define a top-root level index for documentation of several products (much like https://learn.adafruit.com/) 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 :)
Not so easy for a casual user. Building a nice interactive dropdown search widget (or something of the sort) requires solid JS chops and you need to know your way around Hugo to generate a search index. But others have done it and there are some good tutorials out there, so by all means give it a shot!
76 comments
[ 1.8 ms ] story [ 133 ms ] threadI agree that aesthetics are absolutely CRUCIAL and this will be a MAJOR focus of the project.
You can see this in action here: https://github.com/tract-docs/tract-docs.dev/blob/master/con....
How could anyone include search in these static sites? Is there any theme that could provide such functionality?
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.
c. the more vanilla js the better.
d. can you make code blocks have tabs for different languages?
e. this is awesome (did I mention that already).
f. I will find an excuse to use this.
g. I use ddg for my site search, but Google custom search works too, and is a bit easier to work with.
See (for example) this: https://practicaltypography.com/line-length.html
"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"?
[0] https://github.com/riboseinc/jekyll-theme-open-project
[1] See, for example, https://www.rnpgp.com/
For a documentation thing like this, I’d generally recommend avoiding a separate scrolling pane for the primary content, but rather arranging so that it can use the document’s scrolling element. This gets the scrollbar in the place people generally expect it in web things, and makes it work regardless of whether the JS loads.
https://github.com/rust-lang/mdBook
[1]: antora.org
[1] https://github.com/rust-lang/mdBook
They have incredible themes
Remember, you need to write JavaScript anyway..it's probably far more productive to go all the way.
https://greglobinski.github.io/gatsby-starter-kit-docs/class...
Gatsbyjs is not a dynamic application. It is a React-based framework to generate static sites. Pretty much exactly like Hugo - except that Hugo uses Go templating and Gatsbyjs uses React.
If you open the link i gave, it would solve the problem you needed to solve (and also get nice animations if you are so inclined).
The other advantage is that in the future if you want to build a dynamic application, you can continue where you left off. You dont have to rewrite in another framework. Its React all the way down.
Gatsby is a React based static website generator.
Why React? Because there's A LOT of developers familiar with it. Why Gatsby? Has a ton of plugins and starter kits. It's also super simple to use along with modern CMSes like Ghost, Netlify, Contentful, Tina, etc.
> That's what it was developed for
React's official website recommends using Gatsby if you're building a static website.
For some reason the author dismissed it, but I personally find the project quite nice!
Anchor.js — Provides nice clickable/linkable anchors for Markdown content
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
I'm still looking for something that let me define a top-root level index for documentation of several products (much like https://learn.adafruit.com/) 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 :)
How hard would it be for a casual user to add some search capabilities ? IMO, that's a key point to have.