
Tract: A Hugo theme for ambitious documentation projects - biggestlou
https://lucperkins.dev/blog/introducing-tract
======
jdormit
> 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"?

~~~
nothrabannosir
or zealot!

~~~
jrowley
Yeah I agree, I think they are looking for zealot. Sounds similar but
different connotation.

------
sandGorgon
Here's Classy Docs for Gatsbyjs - a pure react based static site generator.

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...](https://greglobinski.github.io/gatsby-starter-kit-docs/classy-
docs-starter/)

~~~
Kovah
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.

~~~
sandGorgon
you are mistaken here.

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.

~~~
Kovah
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.

------
big_chungus
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.

~~~
biggestlou
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.

You can see this in action here: [https://github.com/tract-docs/tract-
docs.dev/blob/master/con...](https://github.com/tract-docs/tract-
docs.dev/blob/master/config.toml#L11-L13).

~~~
hprotagonist
“whatever looks like readthedocs” is good in my world.

~~~
biggestlou
I personally find RTD far too drab for my tastes but to each their own. If it
works for you, run with it!

------
x3ro
One dependency:

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

~~~
ImpressiveWebs
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.)

~~~
x3ro
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.

~~~
biggestlou
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](https://kubernetescommunitydays.org/organizing).

~~~
x3ro
I know these, but there's also CSS so I don't understand why this needs JS..

~~~
biggestlou
If you know of an all-CSS solution, I'm all ears

------
gouggoug
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.

[1]: antora.org

~~~
type0
It also seems to support combining multiple Git repos to generate everything
into one site which seems cool.

------
Uninen
I just configured VuePress (
[https://vuepress.vuejs.org/](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.

~~~
biggestlou
Yep. Love the static approach. I haven't yet a use case for a React/Vue static
generator but a lot of really powerful stuff is being built.

------
yingw787
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.

~~~
biggestlou
Sweet! Definitely stay tuned!

------
strogonoff
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].

[0] [https://github.com/riboseinc/jekyll-theme-open-
project](https://github.com/riboseinc/jekyll-theme-open-project)

[1] See, for example, [https://www.rnpgp.com/](https://www.rnpgp.com/)

~~~
biggestlou
Nice work! Very cool project. Love to see it.

------
nicoburns
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.

~~~
biggestlou
Definitely. Confluence is fine for some use cases, but personally I'm strongly
in favor of a version-controlled approach.

------
bovermyer
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.

See (for example) this: [https://practicaltypography.com/line-
length.html](https://practicaltypography.com/line-length.html)

~~~
derefr
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.)

~~~
bovermyer
That's a great question. I don't know the answer, but I'm sure similar
resources exist in languages with non-Roman writing systems.

------
reinhardt1053
My goto tool for documentation these days is mkdocs with material theme
[https://squidfunk.github.io/mkdocs-
material/](https://squidfunk.github.io/mkdocs-material/)

------
secstate
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.

~~~
biggestlou
Could you say more about this? What exactly is broken about the experience in
Tract? I have never heard of Qutebrowser.

~~~
The-Compiler
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/](https://tract-docs.dev/docs/getting-started/) with the keyboard
without first clicking into the page.

~~~
biggestlou
Okay, I believe I've fixed this.

~~~
chrismorgan
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.

~~~
biggestlou
Do you by chance have an article or some info you could share on this? I'm way
out of my depth here.

~~~
chrismorgan
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).

------
techntoke
Noticed on mobile when you click the menu button there is no way to return to
the page.

~~~
biggestlou
Yes, I'm working on the navigation. Tract is currently pre-alpha and this will
improve by leaps and bounds in the next few weeks.

------
SiDevesh
That looks really nice! Recently had to create documentation for Prism OS
([https://prismos.dev/docs](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

------
scoutt
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/](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 :)

------
axfan
Thanks, I have been looking for a good HUGO theme for documentation.

------
johnchristopher
I am not familiar with Hugo but I watch out for documentation stuff.

How hard would it be for a casual user to add some search capabilities ? IMO,
that's a key point to have.

~~~
biggestlou
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!

------
afandian
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.

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.

Has anyone been here? Suggestions?

~~~
gammaray
I've been using [mdBook]([https://github.com/rust-
lang/mdBook](https://github.com/rust-lang/mdBook)) for my wiki/documentation
needs lately.

It's great, the directory structure is straightforward and even supports
search (through lunr.js) out of the box.

------
Niksko
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.

[1] [https://github.com/rust-lang/mdBook](https://github.com/rust-lang/mdBook)

------
dgellow
The article made me discover Docsy:
[https://www.docsy.dev/](https://www.docsy.dev/)

For some reason the author dismissed it, but I personally find the project
quite nice!

~~~
biggestlou
I'm just not a fan of the aesthetic and it isn't as feature rich as I plan on
making Tract. But if Docsy works for you, I fully support that!

------
hprotagonist
How convenient -- because DocuAPI has been refusing to work for me all week.

------
melenaos
Thank you for your post, I like the theme and the idea of static generator
creating the documentation.

How could anyone include search in these static sites? Is there any theme that
could provide such functionality?

~~~
techntoke
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.

~~~
biggestlou
Nice! I hadn't seen Fuse but it looks like a great option. I've used lunr.js
on other projects and liked it but always open to explore new things.

------
heyarviind2
For more Hugo themes, you can check out [https://uicard.io](https://uicard.io)

They have incredible themes

------
aorth
Looks fantastic. I already use Hugo for some other things. I'll keep an eye on
this for documentation in some future projects.

------
chabad360
a. this looks awesome

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.

~~~
biggestlou
Do you know of any particularly good libs for copy buttons, code tabs, and the
like? I've seen a few out there but they seem pretty subpar to me.

------
msaharia
Nice! How does this compare with docusaurus?

~~~
biggestlou
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!

~~~
type0
Someone mentioned mdBook, that thing is written in Rust and is amazingly fast
even for huge sites.

[https://github.com/rust-lang/mdBook](https://github.com/rust-lang/mdBook)

