I really should stop browsing Hacker News. I keep seeing posts like the latest by Fabien Sanglard, “All You May Need is HTML”, where he writes about how you don’t necessarily need a static site generator, CSS, JavaScript, web fonts, or a content management system like WordPress.
I agree with him, but there’s something about him saying this that just annoys me.
I also add a, somewhat unsolicited, piece of advice. Writers who are getting started may not need any of this stuff. All you may need is HTML.
It might help if he could write decent HTML, though. It’s like the man has never heard of HTML5 or semantic tags, or of concepts like accessibility. Or maybe he just doesn’t give a damn; he has an aesthetic, even if it means using <div>
for everything instead of using actual header tags. I guess he doesn’t expect anybody to visit his website with a screen reader, that’s for damn sure.
There’s no reason I should care how Sanglard does his website. If he’s OK with crappy HTML that’s his business. Nevertheless, I’m of the opinion that if you’re not going to bother to write good HTML — by which I mean HTML that is well-structured (not a mess of <div>
tags) and accessible to visitors who use assistive technologies like screen readers — then you might as well get a machine to generate your HTML instead of doing it by hand and encouraging others to do the same.
My suggestion is that if you’re a writer and you want to put stuff on the web, don’t focus on learning HTML right away. That might have been the thing to do in 1993, but that was thirty years ago.
Instead, learn a lightweight plain-text format1 like Markdown and get Pandoc. Let Pandoc generate your HTML for you. The default template is clean, semantic HTML and will work on all devices. Once you’ve got a few dozen pages or so, learn how to use Makefiles to automate2 the process of building and deploying your website. Use a host that lets you connect to your space via SSH like Dreamhost or Nearly Free Speech; that way you can push using rsync or a graphical tool like Cyberduck.
You don’t need to worry about HTML, CSS, or web fonts if you write in Markdown and convert to HTML with Pandoc. Pandoc will give your pages a readable style. If you want to add headers and footers to the HTML Pandoc generates, you can do that. You can also tell Pandoc to include custom stylesheets once you get that far. Or, if you insist on learning HTML despite my advice, you can create custom HTML templates for Pandoc.
But before you do all that, you need three things:
- Pages and posts written in Markdown
- Pandoc
- a Makefile to automate conversion of Markdown to HTML with Pandoc
Of these three, the first is most important. If you don’t have anything to say, it doesn’t really matter how you say it. But once you’ve got something to share, good tools will make sharing it a lot easier. Why write your own HTML and CSS from scratch if you don’t have to?
Let Pandoc and Make do all of that grunt work for you. And don’t forget that Pandoc isn’t just for making HTML. If you consult the manual you’ll find that Pandoc is great for generating other formats as well.
What’s that? What if you want to use partials in your Markdown text? I’ve got you covered there, too. To start, Markdown is extensible with HTML; if you want something Markdown doesn’t provide, use HTML. Pandoc will render it as-is.
hxincl
from the HTML-XML-utils will let you include arbitrary HTML snippets; the format is <!-- include "foo.html" -->
, so Pandoc will ignore it as it would any other HTML comment. Only want a table of contents in some pages but don’t want to mess with Pandoc switches or templates? hxtoc
is there for you.
The tools are available. Depending on your operating system, you might even have them installed. If not, they’re probably not hard to install. Trust me; you might swear at these tools at first, but once you understand them you’ll swear by them3.
If it turns out that you do need a static site generator like Jekyll or Hugo after all; you’ve already got all your stuff in Markdown. Just copy the files.
I might be plugging Markdown in this post, but you can also use reStructuredText, AsciiDoc, Org mode, etc. Doesn’t really matter which; it’s just that Markdown seems to be the most popular format.↩︎
If you find makefile syntax intimidating, you can also write a shell script or (if you’re on Windows) to build your website with Pandoc; I used to use a shell script myself.↩︎
I eat my own dog food; you can see how I do it with my public git repo for this website.↩︎