Skip to content

Markdown for Writers and Hobbyists (Part 1)

UPDATED 7/16/2019

The following updates done on this tutorial are as follows:

  • Converted the Markdown tutorial parts from blog posts to pages.
  • Updating links and resources for usage, adding new sources and apps for Markdown conversions.
  • Updated the wording on some of the passages to make it sound more direct to the point and a lot less slangy talk.
  • Deleted the original blog posts.

General Overview

Are you a writer who isn\’t quite familiar with writing for the web, let alone familiar with the very basics of HTML? Or maybe a hobbyist web designer/developer who gets impatient with repeating the same HTML code all the time when you write down your content, regardless if you\’ve got some styling via CSS along with it?

Take a look at the syntax below:

If you type this out on a text editor/IDE, or even on a blank field to write your content on CMS (content management system) software like WordPress, the markup above will be converted to the following HTML:

… in which the content you will see on a web browser will look like this:

Yo, Yo, YO! Welcome to mah HOOOD~!!

(Translation: Welcome to my site~!!)

What\’s with all the dashes and equal signs underneath the top text? Can someone explain to me?

SOMEONE is very curious now!
Well, not that curious…

(Please ignore the styling of the quoted block above. The above code shouldn\’t have any CSS styling in it, but this is my blog, and it\’s heavily styled, so that\’s why it looks like that.)

The markup shown at the top is what we call Markdown. Markdown is a text-to-HTML converter syntax specifically created for web writers and web designers and developers who are frustrated with writing all these repetitive HTML tags and CSS styling when the primary focus is to create your content and deploy it to the web. The syntax will be converted to structurally valid (X)HTML when processed through the web server.

The syntax was created by 2004 by John Gruber and the late Aaron Swartz using Perl. It was built to create web text content from plain text with some help from designated characters without the hassle of using repeated HTML/CSS code. More information and history regarding Markdown can be found on John Gruber\’s site right here.

Some quick facts

  • File extensions of Markdown files are .md or .markdown, but you don\’t upload these on your web server. You do upload these on GitHub Pages (if you do plan on hosting a site over there) and will automatically convert to HTML files when viewed on a browser.
  • Markdown is now supported by (almost) every text editor and/or IDE available out there. Sublime Text, Notepad++, Nitrous, etc. If not, they should have extensions or plugins available.
  • Markdown is also supported by (almost) every blog and CMS software out there, which also includes the very popular WordPress and the lightweight blogging platform Ghost. You can extend your CMS software with Markdown support through plugins if available.
  • Chat community programs such as Slack and Discord also use Markdown.
  • GitHub, the most popular Git repository service, uses Markdown as its default content syntax. In fact, GitHub also extended Markdown with their own additions and modifications for easier content creation on README file.
  • Markdown is the default syntax used on static site generators such as Jekyll and Hugo.

The complete documentation about Markdown from its installation to everything else is at its primary site.

I am not a very tech-savvy person. What\’s the easier way to write my content using Markdown?

There are many online content editors that use Markdown. You can even use them to test Markdown for the first time too. You can try in a few of these places:

What\’s next?

We will be going to the basic nitty-gritty of Markdown, coming soon on the next part of this handy Markdown Tutorial. Thank you for joining in!