DEV Community

loading...

The World's Simplest "Static Site Generator"

David Wickes
British. Strong opinions held weekly. No, that's not a typo. Teaches when and where and what I can.
Updated on ・3 min read

What's the fastest way to start a blog? Wordpress? Jekyll? Any one of the hundreds of static site generators out there?

Nah, it's pandoc and now.

What's 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 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!
Enter fullscreen mode Exit fullscreen mode

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:

pandoc --output=index.html --to=html5 --standalone hello-world.md
Enter fullscreen mode Exit fullscreen mode

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

now
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

and now

pandoc --output=index.html --to=html5 --standalone index.md
Enter fullscreen mode Exit fullscreen mode
pandoc --output=hello-world.html --to=html5 --standalone hello-world.md
Enter fullscreen mode Exit fullscreen mode
pandoc --output=my-second-post.html --to=html5 --standalone my-second-post.md
Enter fullscreen mode Exit fullscreen mode

finally, once again

now
Enter fullscreen mode Exit fullscreen mode

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!

Discussion (17)

Collapse
johnbokma profile image
John Bokma

I have considered Pandoc (it's great, I use it to generate my resume), but in the end I decided to write my own static site generator, also because I want a single input file (Markdown-ish). I use it to generate Plurrrr, a tumblelog.

Collapse
quii profile image
Chris James • Edited

Pandoc really is an amazing gift to the open source publishing community.

It does so much.

For instance the book I'm working on is also written in markdown and it's so simple to create a epub files github.com/quii/learn-go-with-test... and pretend you're a real author.

Collapse
weiji14 profile image
Wei Ji • Edited

Excellent post! Here's the oneliner bash loop ;)

for POST in *.md; do pandoc --to=html5 --output=$(basename ${POST%.md}).html --standalone $POST; done
Enter fullscreen mode Exit fullscreen mode

The $(basename ${POST%.md}).html strips out the .md file extension, and also removes the directory path (helpful if your posts are stored in a folder). I found this stackoverflow question a helpful guide.

I'd also recommend eleventy as a no nonsense static site generator.

Collapse
gypsydave5 profile image
David Wickes Author

Not seen the basename trick before - very, very nice.

Collapse
justinnoel profile image
Justin Noel

Thanks for the great post. Pandoc is pretty fun and simple.

A few edits :

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

instead of

pandoc --output=index.html --to=html5 --standalone index-world.md
# My Quick Blog

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

instead of

# My Quick Blog

- [Hello World][hello-world.html]
- [My second post][my-second-post.html]
Collapse
gypsydave5 profile image
David Wickes Author

Publish in haste - regret at leisure!

I'll make the changes - thanks!

Collapse
annarankin profile image
Anna Rankin

I love this! I've never used pandoc, gonna check it out now!

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

I cracked up 😂

Thanks David!

Collapse
gypsydave5 profile image
David Wickes Author

Thanks Anna - that made my day!

Collapse
otw profile image
Oliver Williams

Have you tried Netlify?

Collapse
gypsydave5 profile image
David Wickes Author

No - tell me about it!

Collapse
otw profile image
Oliver Williams

Its made specifically for hosting static sites, but it can have forms 😮. I hear it also makes working with AWS lamda functions a bit easier, although I haven't tried that yet.
You can use Github, Gitlab or Bitbucket and it will update the site with every merge.
I've personally only used it for single-page HTML websites, but I hear it integrates nicely with static site generators.
And it has a generous free tier :)

Collapse
bayuangora profile image
Bayu Angora

What's about Pandoc's performance speed compared to Hugo?

Collapse
gypsydave5 profile image
David Wickes Author

Good question! Maybe I'll benchmark it - or you could! 😁

Collapse
bayuangora profile image
Bayu Angora

Couldn't wait about the benchmark result.

Collapse
qm3ster profile image
Mihail Malo

So, build your own hugo out of seemingly conveniently shaped pieces?

Collapse
gypsydave5 profile image
David Wickes Author

Yes. Unix programming philosophy at work.

Collapse
schoenix profile image
schoenix

I have used the SimpleHTTPServer module of python instead of now for local testing.

Forem Open with the Forem app