Make static websites - Specifics

Modern technical writing - Andrew Etter 2016

Make static websites
Specifics

I have perhaps an irrational bias towards static websites. I love them. I love their speed, simplicity, portability, and security. You can host static websites practically anywhere, including Amazon S3 and GitHub Pages. They have no server-side application dependencies, no databases, and nothing to install, so migrating the entire site is as easy as moving a directory. Because all it has to do is serve pages (rather than generate them dynamically), the server needs very few hardware resources. You can test static websites on your local computer without installing anything and compress and ship them with software applications (although you shouldn't unless you have to). There's no WordPress instance for someone to hack or comments section for bots to spam. Nothing ever crashes, because there's nothing to crash5.

Sure, you could manually create a simple static website, but to do anything complex, you'll want to use a generator. The basics are that you provide a static site generator with content (lightweight markup) and a theme (templated HTML and CSS), and it processes everything into a working website. To update the site, just modify the content and process everything again.

Many static site generators exist, far too many to list. In fact, I'm sure some new, amazing static site generator is in development right now, and I already feel like a jerk for not mentioning it. But if I had to suggest a few:

· Sphinx

· Jekyll

· Hugo

· AsciiDoc

· Middleman

· Metalsmith

· MkDocs

· Hexo

Any one of these tools can create a beautiful, functional documentation website. Jekyll is the most popular. That said, I favor Sphinx for two major reasons:

· It was specifically built for documentation, rather than blogs or marketing sites, so it has a robust system for generating nested navigation menus.

· It features JavaScript-based search out of the box. Every other tool in that list (except MkDocs) does not have out of the box search and relies on Google Custom Search, Swiftype, Algolia, Lunr, or some other search solution. Adding a search solution to a static site often makes it a whole lot less portable, so Sphinx has the right idea here.

Whichever tool you select, take the time to customize the theme. Focus on navigation and approachability. Find a designer and ask for help with colors, typefaces, font sizes, page width, and spacing. This customization is your chance to differentiate your content from the thousands of ugly, disorganized sites of the world, so don't just use the default theme. If you don't have the skills to do this customization yourself, you might need to hire someone. It's that important.

And make sure you have a search solution.

If making a static website sounds like a lot of work, well, it isn't, but an even simpler solution exists: GitHub wikis. The secret with GitHub wikis is that they're really just a collection of lightweight markup files that you can edit using your favorite text editor or through a web browser. GitHub wikis support Markdown, reStructuredText, AsciiDoc, and some other languages that you shouldn't use.

You don't get a lot of flexibility in how the resulting pages are organized—just an alphabetical list—but you can make a table of contents on the home page and have a highly functional site with very little effort. You lose the ability to make your website beautiful and unique, and GitHub wikis do not have search. But those might be worthwhile trade-offs for simple sites. This way, at least you're storing lightweight markup files in a DVCS. You can always create a better site later using those same files.