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.

So what is it? Markdown is a special syntax that consists of regular characters, e.g., #, *, [],<>, which in turn allow for rich formatting without interfering with text readability. In other words, we store formatting meta data in the text itself which is later converted by apps or online services into beautiful documents. This has various advantages:

  • Plenty of apps and web services to choose from
  • Abundance of styles, themes and Markdown flavors, e.g., I can add my own custom CSS stylesheets to Marked
  • Can be quickly edited in any text editor, e.g., Sublime Text 2 or Vim
  • Robust conversion to and from HTML, the language of the web, without the extra junk code from cumbersome WYSIWYG editors and MS Word

That’s all good, but my main and favorite reason for using Markdown and maybe even the reason I wrote a book and started blogging more is that Markdown and its apps allow for distraction free writing. I can use just the keyboard, enter focus mode and pour the words.

Flow

If you want to explore the Markdown web publishing, I recommend the following flow:

  1. Install WordPress or create a book on LeanPub
  2. Start a ByWord (or iA Writer) document in a Dropbox folder, because you’ll be able to continue whenever you have a spare minute via its iPhone/iPad apps
  3. Write 300–500 words (ByWord has a counter) for a blog post and about a thousand words for a chapter if you are writing a book
  4. Preview in Marked
  5. Copy and paste your Markdown draft into Draft or Editorially web services for collaboration with friends or editors
  6. Export/convert Markdown to HTML with ByWord or Marked and paste the code into your WordPress post. For LeanPub, just leave the Markdown files in the Dropbox folder, press ‘preview’ or ‘publish’ button and relax
  7. For PDF generation, use the same apps as in the previous step

Note: LeanPub utilizes the LaTeX technology which can be used directly for generating PDF files. The easier but less configurable approach is just to use one of the aforementioned apps which rely on Safari engine for rendering HTML and then printing it.

Syntax

For the complete syntax guide, please refer to the original post and to the documentation for the particular Markdown flavor that you’re using, e.g., GitHub Flavored Markdown.

In addition, here is a handy Markdown cheatsheet.

--
Best Regards,
Azat Mardan
Microsoft MVP | Book and Course Author | Software Engineering Leader
Azat Mardan avatar
https://www.linkedin.com/in/azatm
To contact Azat, the main author of this blog, submit the contact form or schedule a call at clarity.fm/azat and we can go over your bugs, questions and career.

2 thoughts on “Markdown Web Publishing

  1. Stefan Kroes

    We have recently been working on a new service that lets create websites by editing Markdown files on your Dropbox. Files are automatically converted to html and published on your site. The service also provides nice templates with an automatic menu and preview functionality. If you are looking for a way to create a site from your Dropbox, I encourage you to check us out!

    – Stefan Kroes
    (founder of Sitebox.io)

Leave a Reply

Your email address will not be published. Required fields are marked *