Markdown Web Publishing

TL;DR: Know and use Markdown because it’s fast and convenient.

Meet Markdown

“What is a Markdown?” my editor asked me the other day. She is an experienced content and copy editor and has worked for magazines and book publishers. However, she is not familiar with the powerful and convenient Markdown because it’s still a rather unknown approach to publishing except for an elite circle of early adopters and technology professionals. Even the so called re-invented web publishing experience Medium doesn’t support Markdown, but many other services and apps including my favorites (ByWord and LeanPub) build their whole flow around Markdown! In fact, I’m such a huge fan of Markdown that I’m writing my daily journals in it as well as this blog post.

Continue reading “Markdown Web Publishing”

Wintersmith — Node.js static site generator

This past weekend was a very productive one for me, because I’ve started to work on and released my book’s one-page website —rapidprototypingwithjs.com. I’ve used Wintersmith to learn something new and to ship fast. Wintersmith is a Node.js static site generator. It greatly impressed me with flexibility and ease of development. In addition I could stick to my favorite tools such as Markdown, Jade and Underscore.

Wintersmith is a Node.js static site generator

Why Static Site Generators

Here is a good article on why using a static site generator is a good idea in general, An Introduction to Static Site Generators. It basically boils down to a few main things:

Templates

You can use template engine such as Jade. Jade uses whitespaces to structure nested elements and its syntax is similar to Ruby on Rail’s Haml markup.

Markdown

I’ve copied markdown text from my book’s Introduction chapter and used it without any modifications. Wintersmith comes with marked parser by default. More on why Markdown is great in my old post, Markdown Goodness.

Simple Deployment

Everything is HTML, CSS and JavaScript so you just upload the files with FTP client, e.g., Transmit by Panic or Cyberduck.

Basic Hosting

Due to the fact that any static web server will work well, there is no need for Heroku or Nodejitsu PaaS solutions, or even PHP/MySQL hosting.

Performance

There are no database calls, no server-side API calls, no CPU/RAM overhead.

Flexibility

Wintersmith allows for different plugins for contents and templates and you can even write you own plugin.

Getting Started with Wintersmith

There is a quick getting started guide on github.com/jnordberg/wintersmith.

To install Wintersmith globally, run NPM with -g and sudo:

$ sudo npm install wintersmith -g

Then run to use default blog template:

$ wintersmith new <path>

or for empty site:

$ wintersmith new <path> -template basic

or use a shortcut:

$ wintersmith new <path> -T basic

Similar to Ruby on Rails scaffolding Wintersmith will generate a basic skeleton with contents and templates folders. To preview a website, run these commands:

$ cd <path>
$ wintersmith preview
$ open http://localhost:8080

Most of the changes will be updates automatically in the preview mode except for the config.json file.

Images, CSS, JavaScript and other files go into contents folder.
Wintersmith generator has the following logic:

looks for *.md files in contents folder,
reads metadata such as template name,
processes *.jade templates per metadate in *.md files.

When you’re done with your static site, just run:

$ wintersmith build

Other Static Site Generators

Here are some of the other Node.js static site generators:

More detailed overview of these static site generators is available in the post, Node Based Static Site Generators.

For other languages and frameworks like Rails and PHP take a look at Static Site Generators by GitHub Watcher Count and the “mother of all site generator lists”.

Markdown Goodness

I’ve been introduced to Markdown by my co-worker through GitHub and the need to document the services we’ve been working on at Gizmo. And soon I’ve become a huge fan of Markdown. Honestly, I don’t think I would have been so productive writing blog posts, training manual and Rapid Prototyping with JS book without the help of Markdown and my favorite Markdown apps which I’ll list later.

Markdown is a lightweight text formatting syntax which allows you to write in a plain text, read what you’ve written, and convert marked text cleanly, without any additional mess, into HTML. It is a very accessible and efficient way of writing books, blog posts, articles, technical documentation and pretty much everything which is meant to be on the Internet. Markdown is de-facto a standard in a tech community, since it’s perfect for inserting code blocks and links. Also Markdown is gaining popularity in book publishing, e.g., LeanPub is accepting books only in Markdown.

Beautiful iA Write - my favorite Markdown app — Beautiful iA Write – my favorite Markdown app

Because Markdown doesn’t require typing too much extra code, like plain HTML, or using your touchpad/mouse, like Word, Pages, or Google Docs, Markdown is just a pure bliss. On the other hand if you’ve been dealing with plain HTML or WYSIWYG editors you know that it’s a matter of putting all those opening and closing angle brackets (<>) or cleaning up the extra mess. Really, who has time for that?

Here are the five most used styles, which according to 80/20 rule, aka Pareto Principle, will give you the most bang for you time:

Headers: use #,##, ###,…, e.g., # Markdown Post
Links: use: ([](), <>), e.g., [Cool blog](http://webapplog.com) will turn into Cool blog
Emphasis: for Bold use **bold** and Italic use *italic*;
Lists: just start with 1. item or * item and follow by space
Code: use var a=[]; or tabbed line before.

In case you have to dive deeper in to the markup, here is the original John Gruber’s Markdown: Syntax.

Note: there are many flavors of Markdown, such as GitHub or LeanPub, but those five styles should apply to all of them as they are considered to be the foundation.

And finally, here is my favorite Markdown tools which I can’t live without:

ByWord: apps which have nice UI/UX, tons of features, iCloud/Dropbox support, versions for: iPad/iPhone, and Mac OS X;
iA Writer: and similar to ByWord, although apps have less features which I guess was made on purpose to keep attention on the writing, versions for: iPhone/iPad, and Mac OS X;
Marked: preview app which supports multiple CSS files and many exporting functionalities, version for Max OS X;
Mou: free The missing Markdown editor for web developers which has live preview, version for Max OS X;
TextMate: plain code/text editor dubbed The Missing Editor for Mac OS X, version for Mac OS X.

And of course, you can use any text editor like Emacs, Vim, Sublime or Notepad for writing Markdown, — it’s just a text after all! Extra bonus: many websites and blogging platforms now support Markdown right off the bat, check with theirs FAQ/help.