[docs] Reevaluate Jekyll vs other docs / static site tools

[tiffon]

Alt candidates

• Sphinx
• Slate - example
  • Con: Seems like one large page?

References

Examples of nicely done docs:

• gRPC
• Flow
  • top-level TOC
  • content

[itsderek23]

Hugo - doesn't render a single page...looks like it supports multiple formatters (Markdown by default and Asciidoc as well).

[tedsuo]

When comparing solutions, there are a set of qualities I am looking for. FWIW, I believe our current solution, jekyll, mostly has these qualities. But perhaps another tool would be an improvement. Hugo in particular looks good.

Suggested Requirements

Change managed via GitHub

OpenTracing uses GitHub for project management, which includes website and documentation changes. Some solutions, such as CMS tools that store website data in MySQL, would make this difficult. Let’s stick to using a static site generator, paired with Markdown/Asciidoc.

We have a complex information architecture and site layout.

The website contains a fair amount of material. Whatever build tool we use must be able to create navigation elements, such as menus and footers, and handle nested pages.

Raw documentation is easy to read, well laid out.

The raw format for documentation should be structured sufficiently, so that it can be explored and edited without needing to build the website. For example, if should be possible to read the docs via the GitHub file browser.

Building documentation is only a single step.

It should be simple to run the website locally. Ideally, only one build tool would be needed to create the entire website, and that build tool would be easy to install. This makes it easy onboard new doc maintainers, and allows users to view documentation offline.

Special, one off pages are possible.

Some pages, such as the search page, may be their own single page apps. Some pages are simply external links. One-offs such as these must still be present in navigation elements, and themed properly. There needs to be a story for how this will work.

Multi-language support for computers.

Double check that all programming languages are well supported.

Multi-language support for humans.

Ensure that there is a reasonable story for how non-English versions of the website will be maintained.

[tedsuo]

Hugo vs Jekyll

I reviewed the documentation tools listed so far, and prefer Hugo over the other options. While Hugo and Jekyll are similar, I can see how a clean Hugo project has a couple of advantages over our current Jekyll setup.

Removes all build dependencies, other than the Hugo binary.

Installing Jekyll's ruby toolchain has a lot of hiccups, especially for mac users. Hugo is a single pre-compiled binary, with no dependencies, so it's much easier to install. The difference in experience is substantial enough to be important, especially for new users.

Cleanly separates site theme from content.

With Hugo, there are themes which appear to meet the standards I listed above under "Suggested Requirements." We may be able to start from a popular base theme, and use it without too much customization.

https://themes.gohugo.io/tags/documentation/

(To be clear, it's possible to obtain the same clean separation using Jekyll, but it would involve changing the current setup enough that it's not any less work than moving to Hugo.)

Proposed Next Steps

If we went with Hugo, I would suggest the following:

• Pick existing Hugo theme and stylize with current site colors and logos.
• Develop the new site in the same git repo, on a v2.0 branch.
• Don't port content; start writing new content from scratch.
• Continue to maintain support for the current site via master.

[tiffon]

Hugo looks great. Gitbook is also nice, but it seems like Hugo is more versatile. (Although, maybe you get a few more things for free with Gitbook, like the language selection on the top right).) FYI, Gitbook is free if you don't use the hosted service.

With Hugo, I would say we can do better on the syntax highlighting, though.

Hugo uses Chroma, which is a port of Pygments. Pygments is venerable, but it's showing it's age. I suggest we use something based on textmate grammars, which is the standard for text editors. I've done this on my personal site using the highlighter used in the Atom; seems to work pretty well. Using the textmate grammars vs the pygments lexers can make a subtle, but in my opinion substantial, difference. I can elaborate on the pros and cons, if anyone is interested.

[JStickler]

One of our teams ran into some serious problems with file formatting using GitBook and had to spend a lot of time trying to straighten it out. I wouldn't recommend GitBook. If you check out their GitHub, they've got 800+ issues, but the community doesn't seem to be very active about addressing them. It's been over six months since the last commit to Master.

[tedsuo]

Yes, the site currently sorta uses GitBook, and it's not great.

[reimertz]

Some Background

Hi all! I was the initial implementor if the redoing of the site and I agree the it would make sense to move away Jekyll. The initial requirement was to migrate over to a new design using the current stack while also adding proper documentation to it. At the time, Gitbook seemed promising, but I have to agree that it now seems to have stalled in development. 😔

Enter Gatsby.js

I have been keeping an eye on Gatsby.js for some time and it seems very promising. React is definitely getting a lot traction and would excite more developers to help us build the new site.

Further, some big players have used it for their static sites such as reactjs.org, https://about.sourcegraph.com/ and more.

One might think that this will make the entire site be JS-dependent but the cool thing with Gatsby is that it will pre-render each page that React than later hydrate client-side. What this means is that the entire page is <noscript> compatible. Try it yourself by disable JavaScript and visit https://reactjs.org.

Another perk is the elegant separation of templates and content. You can see it in action here:

• Templates
• Components
• Content

Editing

Content can for sure be edited as of now using Github and it's excellent PR solution but there are also other options, such as combining Gatsby with either Contentful or Prose. There are two really great articles covering both alternatives that can be read here and here.

The Future

I don't know, I might be biased but I've tried a bunch of static page generators over these past years and Gatsby seems to be that one solution I've been waiting for. I also love working in a React environment due to the strict separation of responsibilities.

Exciting times for sure! 🎉

[tiffon]

@reimertz Great work on the site!! :+1::+1:

Gatsby looks great and I'd be thrilled to use it on a project. But, the concern I'd raise is that it looks like it might be suuuper flexible at the cost of simplicity, and it's not clear that we'd benefit from most of that flexibility.

The biggest downside I can see is the flexibility / complexity may be a barrier to entry for contributors:

• Development / maintenance of the site is fine for React-devs but not-so-great for other devs
• Comparatively mature tools like Hugo have quality of life features that ease content creation (e.g. i18n, date formatting, etc.)... AFAIK Gatsby has not reached parity in that regard, yet (e.g. date formatting)

Please bear in mind I've never used either Hugo or Gatsby on a project. But, being a front-end dev, I gave Gatsby a serious look and considered recommending it after the docs meeting Thursday. I just figured it's well-suited to React-devs but probably a PITA for anyone else.

[yurishkuro]

I kinda second Joe's comments. I looked at Gatsby over a year ago for another website, and the React-ness of its template model seemed a big overwhelming to me.

I'm also curious how it fares against https://docusaurus.io/ recently released by Facebook.

The advantage of Node.js based generators is a single tool chain, and probably the most mature in the industry. Jekyll supports ruby plugins, but I am not sure Hugo does (being a single binary). With React-based generators plugins would be fairly easy to add.

[reimertz]

@tiffon @yurishkuro Fair points for sure! I guess I've been drinking the React kool aid for too long and gets excited every time I can utilize it. :)

I've never seen Docusaurus tbh, but it looks like a decent tool. Once we settle down on which ones are of highest interest, I'd be more than interested to play around with them.

Another point might be to get more feedback from people who might be interesting in contributing to this project in the future. So maybe using our Twitter/Gitter presence to get some more feedback before deciding?

[yurishkuro]

cc @lucperkins

[lucperkins]

I did a bit of a deep dive into GatsbyJS last week and I concur with @reimertz in finding it very intriguing. But I also second @tiffon's comments about it. I don't yet see it as a viable solution for large, fully featured, maintainable documentation sites. In addition to the Hugo features that @tiffon pointed out, I would also point to taxonomies and shortcodes as other Hugo features that would be tricky to live without. I'm sure GatsbyJS could be made to do just about anything you want, but at potentially significant dev and maintenance cost.

One other thing: the kind of integration between GatsbyJS and platforms like Contentful/Prose that @reimertz mentioned would be quite desirable, I think, in that it would enable a mixing of approaches (version-controlled approach via GitHub supplemented with a WYSIWYG, in-browser, CMS-style approach). This is where NetlifyCMS and Forestry come in. Both support Hugo natively and provide an experience very similar to what Contentful and Prose provide. I've used both NetlifyCMS and Forestry and they're both quite nice. If enabling less-technical folk to contribute to the docs directly is a goal, both are worth exploring.

[lucperkins]

Update: I also looked into Docusaurus and found the same set of issues. Both GatsbyJS and Docusaurus are interesting tools but I wouldn't call them full-fledged documentation tools just yet. I'd say they're really more like ReactJS boilerplate projects that (a) include some very straightforward Markdown-to-HTML conversion capabilities but (b) don't provide any of the data and content management capabilities that I would expect of SSGs suitable for projects like OpenTracing.

[tedsuo]

Thanks @lucperkins. After looking at the options, we are going to try Hugo. The reasons we found it attractive:

• Easy to set up and start editing
• Supports large sites with different sections
• Supports snippets for doc reuse
• Focused on generating flat-file site content from markdown, not react/js applications

GatsbyJS looks interesting, but because it's focused more on react and APIs and less on turning markdown into webpages, I'm concerned it would have some rough edges.

We can always try another tool if Hugo doesn't work out. :)

[lucperkins]

@tiffon Just out of curiosity, why do you see Pygments as insufficient?

[lucperkins]

@tedsuo Let me know if you'd like help. I could migrate the existing site to Hugo very quickly if you'd like.

[tiffon]

@lucperkins I don't think pygments is current with valid syntaxes in various languages. The one I'm most familiar with is JSX.

Pygments:

Based on the atom highlighter:

[lucperkins]

@tiffon How did you set things up on your personal site? Did you use some kind of client-side tool?

[tiffon]

@lucperkins No, I did some strange stuff and I wouldn't recommend the exact approach I took.

Instead, highlights has a cli which can probably be used in Hugo via the pygments-classic interface.

It's a non-zero amount of hassle, but I think the quality of the syntax highlighting is definitely better. The textmate grammars are straight out of what's used in atom. I had to jump through some hoops to get things like copy-and-paste without line numbers and anchors on line-numbers working, but I'd be able to port those things if there was some interest.

So, it would be all server-side when the site is generated, not client side.

[tiffon]

During our discussion Thursday we decided to stick with the Chroma syntax highlighting that ships with Hugo, noting the possibility of looking into alternatives at some point down the road.

For future reference, here is another comparison between the two approaches:

Pygments / Chroma - From the Hugo site

Textmate grammars - From atom, styling is via CSS and any atom theme can be used. These colors are kind of ugly, but the main thing is the syntax highlighting is more relevant.

[isaachier]

I think we really ought to split this into separate paths:

• Choosing "A mature, plain-text writing format for authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more." (Quote from https://asciidoctor.org/docs/what-is-asciidoc/.) The options here are Sphinx, Asciidoc, Markdown, etc. They are output agnostic platforms. That means you can generate a bunch of different formats and potentially use the output as input to a web tool or something else.
• Choosing a web template format. The limitation here is that it only generates a website by default, no PDF, XML, or whatever else you might need.

I feel the former is much more common in open source projects and have the advantage of easy notation. Also, the web templates can use the generated output as input, so that choice is still available.

[isaachier]

For a specification, I think this is typical: C++ Standards Draft.

[tedsuo]

We've agreed to start by using Hugo with "basic markdown" and only the tools Hugo ships with by default. We will add markdown features, additional tools, or switch to AsciiDoc, as the need arises.

Closing this issue for now.