entropyxyz/entropy-docs

Recreate docs site in Hugo.

Closed this issue · 1 comments

The docs site is currently created and managed by Docusaurus. While Docusaurus isn't the worst static site generator out there, it's got a lot of problems. Mainly:

  • Thousands of dependencies.
  • Restrictive customization options.
  • Slow site-build speed.
  • General project bloat.

In comparison, Hugo:

  • Runs from a single binary.
  • Doesn't require any NPM dependencies.
  • Builds offline by default.
  • Builds the site within half a second.
  • Is incredibly customizable.
  • Has an easy-to-use templating language.

I've been playing around with moving the docs site to Hugo recently in the test/hugo-ssg-with-hextra-theme branch. I've also created a preview deployment over on Netlify: https://entropydocs.netlify.app/

I haven't edited any of the content within the docs during this test. I've also kept all the links and directory structures the same. From a content creation point of view, the only change is that content now lives in /content rather than /docs. This change does not affect page URLs -- they're all the same.

Next steps

There are a few things I want to ensure we add before moving everything over to this new branch:

  1. Create a View site beta banner that pops up on the current site. This will give users the chance to see what the site will look like before everything goes live.
  2. Ensure all the content is up-to-date on both versions of the site.
  3. Confirm we're not breaking SEO.

Further tasks

While these tasks don't need to be completed before we launch the beta site, they're nice to have additions:

  • #156
  • #157
  • #158
  • Create a lead text variable from front-matter to introduce a page and its content.
  • #159
    • reference/cli
    • reference/rust-testing-interface
  • #160
  • Create interesting, section-specific index pages, similar to how DigitalOcean and Stripe handle their index pages:
    • Basics
    • Concepts
    • Guides
    • Reference
  • Add external link CSS, similar to how external links function in the current docs site.

Since the Hugo site is now live, we can close this issue :)