Guide To Markdown: My Approach To Web Publishing

There are many tutorials around the internet on Markdown, and most of them are better than what you can find in this article. However, since I use it a lot, I feel compelled to add my take on this, in the hopes that this article might help some people write better and more efficiently.

What is Markdown? Markdown is, simply put, a text-to-HTML conversion tool for web writers. Created by John Gruber (of Daring Fireball), it is a syntax that you add to your drafts that converts easily to HTML for web publishing.

To give a very easy example, when I type as Markdown:

# Title goes here
## This is my subheading

upon conversion to HTML will yield:

<h1>Title goes here</h1>
<h2>This is my subheading</h2>

And the final product, after being rendered by a browser will look like this:

reeder
Output from a browser.

Markdown removes the pain of coding in HTML for your web articles, and allows you to focus on your writing. Of course, writing h1 tags by itself is pretty easy, but headaches rapidly ensue once there’s some formatting styles that you want to keep, like those pesky style attributes that you have to type in every single time.

 

Intro to Markdown

What it’s used for

Like the simple example earlier, it’s used to convert text into HTML as easily as possible.

It takes the pain out of editing longform content, in my opinion. Many blogging platforms like WordPress or Blogger have their own WYSIWYG (what-you-see-is-what-you-get) editors; you can edit as you write like how you would with a word processor like Microsoft Word.

Some blogs or sites are self-coded and hosted. You might find yourself in a situation where you don’t have a WYSIWYG editor, and are required to write your article out in HTML to be read by web browsers.

Markdown also has its uses in places other than in web publishing. Some note-taking apps like Bear or Outlinely are Markdown-capable. Even my favorite task management service Todoist supports formatting tasks with Markdown.

Why it’s great

It speeds up your work. It is an absolute joy to just be able to just pour out the words and format them at the same time. It takes some getting used to, but once you do, you can step back, admire your draft, and pat yourself on the back because it’s already formatted. All your bolds, italics, and underlines are all there, along with headings and subheadings.

You get to keep your hands on the keyboard. This is one of my favorite productivity hacks when I work. Your use case may vary, depending on the kind of work you do, but when I write I just want my hands on the keyboard at all times. Lifting up a hand to hold the mouse, click something, and bringing it back to the keyboard adds up seconds that accumulate over the hours.

You can prepare your CSS style tags in advance, and re-use them at will. I’ll go into this in more detail later. Basically I have a set of style tags that I re-use over and over again. Whenever I publish an article at work I just paste in those tags into the CSS section, and I immediately get how I want it to look like.

 

How to use Markdown

You can check out the original Markdown documentation by John Gruber here, or this fantastic tutorial. They can both explain it far better than I can, so I’ll just briefly go over it to expose you on what you can achieve with it.

Syntax

Headings are denoted with a ‘#’ (pound) sign. One # denotes h1. ## denotes h2, and so on, until h6.

To make words bold, simply cover them in two asterisks:

**this is bold**

To italicize, wrap them in one asterisk:

*italicize*

Inserting a hyperlink (Text here) is done in Markdown by wrapping with square brackets followed by the link wrapped in parentheses. It’s not separated by a space.

[Click here to go to this link](http://thislinkhere.com)

Adding an image using Markdown in your draft (insert text) is done by using the same syntax as a hyperlink, but preceded by an exclamation mark.

![alt text of image](linktosource)

So how does this all come together? Take this passage I wrote in Markdown, converted to HTML, and rendered by a web browser.

markdown
In Markdown
html
Converted to HTML

 

wow
Published product from a browser.

Converting to HTML

The Markdown editor that I use, Stackedit.io has a built-in publish-to-HTML feature. It converts what you write and stores the output file into Google Drive, Dropbox, and other services. Other alternatives like Browserling are good too.

My general workflow for writing goes like this:

  1. Write article with Stackedit
  2. Convert into HTML and store file in Google Drive
  3. Paste [style] tags into the HTML editor for my website.
  4. Publish!

<style type=”text/css”>.blog-post > p, .blog-post > ul, .blog-post > h4, .blog-post > li, .blog-post > ol, .blog-post > h1 , .blog-post > h2 {

  color: #3b3b3b;
  font-family: medium-content-serif-font,Georgia,Cambria,”Times New Roman”,Times,serif;
  font-size: 18px;
  font-weight: 300;
  font-style: normal;
  line-height: 1.58;
  letter-spacing: -.003em;
  margin-bottom: 1.5em;
  text-align: left;
  text-rendering: auto;
  }
  .blog-post > h3, .blog-post > h1{
    color:#3b3b3b;
    margin-top:-20px;
    padding-top:60px;
    font-family: medium-content-serif-font,Georgia,Cambria,”Times New Roman”,Times,serif;
  font-size: 21px;
  font-weight: 700;
  font-style: normal;
  line-height: 1.58;
  letter-spacing: -.003em;
  margin-bottom: 1.5em;
  text-align: left;
  text-rendering: auto;
  }
  .blog-post > h4, .blog-post > h2{
    color: #3b3b3b;
  font-family: medium-content-serif-font,Georgia,Cambria,”Times New Roman”,Times,serif;
  font-size: 18px;
 img {
    display: block;
    margin: auto;
    max-width: 100%;
      max-height: 100%;
}
  @media screen and (min-width: 900px) {
    .blog-post > p, .blog-post > ul, .blog-post > h4, .blog-post > h3, .blog-post > li, .blog-post > ol, .blog-post > h2, .blog-post > h1 {
        font-size: 1.7em;
        width: 767px;
        margin: auto;
          color: #3b3b3b;
        font-weight: 380;
         line-height: 1.58;
        letter-spacing: -.003em;
         margin-bottom: 1.8em;
         text-align: left;
      text-rendering: auto;
    }
}
</style>
The CSS styles I use to get the desired look in the above example.

Conclusion

Markdown is a great tool for all writers who primarily publish on the web. It’s a fast, easy way to obtain the style and look that you want without doing the repetitive and tedious task of dealing with HTML tags and code. Using a few services, you can really churn out a quick article, e-book, or web page content in a pleasingly beautiful format.

Notable apps that support Markdown:

Todoist
Bear
Outlinely
Stackedit.io
iAWriter
WordPress
Byword
Day One

One thought on “Guide To Markdown: My Approach To Web Publishing

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s