The World's Simplest "Static Site Generator"
Tags: beginners, staticsitegenerator, tools, noframeworks
Published: 2018-10-19 16:30:24

---
title: The World's Simplest "Static Site Generator"
published: true
description: 
tags: 
    - beginners
    - staticsitegenerator
    - tools
    - noframeworks
---

What's the fastest way to start a blog? Wordpress? Jekyll? Any one of the hundreds of [static site generators](https://myles.github.io/awesome-static-generators/) out there? 

Nah, it's `pandoc` and `now`.

## What's `pandoc`?

[Pandoc][pandoc] is a 'universal document converter' - a swiss army knife for changing document type a into document type b. It's good for lots of things, but today it's going to be good for turning Markdown (what we like writing in) into HTML (what we read on a website). It's available to be installed through almost every package manager I've used - on a Mac, just `brew install pandoc`.

## What's `now`?

[Now][now] is a useful product from Zeit.com for deploying an application _really_ quickly. It's great for throwing up something to see how it works. It will serve up Docker images, NodeJS applications and static sites. I wasn't convinced to start with, but now I'd swear by it. Today, we use it to deploy our static blog website. You can install it with a simple `npm i -g now`, but there are other ways.

## On your marks, get set...

So, make sure that you've got `pandoc` and `now` installed, that you're in a nice clean directory and that you've got a connection to the Internet. And that you know what your favourite editor is. If you don't have a favourite, pick the one you hate the least.

## ... GO!

Quickly - open a file called `hello-world.md` in your least-hated editor and write something like this:

```
# Hello World

Hello world, this is the world's fastest blog!
```

Save it - faster, faster! And now run this in the terminal. What? I didn't tell you to open a terminal session? Quickly, open one and run:

```shell
pandoc --output=index.html --to=html5 --standalone hello-world.md
```

IGNORE THE WARNINGS, we don't have time to explain! Ship it now! Now! NOW!

```shell
now
```

and say YES!

`now` will put your `index.html` on the Internet. It'll even put the URL it uploaded it to in your clipboard. So open your least hated web browser drop in the URL.

Success!

The other fifteen seconds is to bask in the glow of your achievement - you've
earned it.

## More?

What, you want more than one blog post in your blog? Are you crazy or greedy? Or both? Such luxury, millenials are so spoiled and entitled yadda yadda yadda...

Sure! Try this: open a new file called `my-second-post.md` and write your second post in it - I don't care what you write about!

Now write `index.md` - like this:

```
# My Quick Blog

- [Hello World](hello-world.html)
- [My second post](my-second-post.html)
```

and now

```shell
pandoc --output=index.html --to=html5 --standalone index.md
```

```shell
pandoc --output=hello-world.html --to=html5 --standalone hello-world.md
```

```shell
pandoc --output=my-second-post.html --to=html5 --standalone my-second-post.md
```

finally, once again

```shell
now
```

Say YES again! Paste the new URL in your browser and...

BOOM! You now have a blog with an index page and two posts. Do a little dance - you've created a static site generator using existing tools - it's the Unix way. Hooray!

## Things you can try out

- We're programmers - we don't like to do things twice! Write something to loop over the `.md` files in your directory to turn them into `.html` with `pandoc` rather than doing every file by hand. Bash, Ruby, JavaScript - whatever is easiest!
- It's not fun to have to change the URL of your blog every time you deploy it. `now` has a way you can alias a deployment to a permanent URL - why not take a look at how that's done.
- Your blog is _ugly_. Not going to lie. You should add some CSS. `pandoc` has
a way to include a CSS file in the html - you need to add the flag `--css=file.css` to your `pandoc` call (once you've written some good looking CSS that is).
- Stop ignoring the warnings! Take a look at how to add metadata to your Pandoc markdown - it's all in the Pandoc documentation.

Have fun!

---

Edit: thanks to @calendee for spotting my mistakes!

[pandoc]: http://pandoc.org/
[now]: https://zeit.co/now