Markdown For Content

Markdown For Content is a website that advocates the use of markdown for webpage content. As the world moves towards the clouds and the Internet gains more and more text data, it's becoming more and more important to find fast, efficient ways to create and transmit text. Markdown is a way.

What Markdown Is

Markdown is a lightweight markup language that is easy to read and write as plain text. It is frequently parsed and converted into corresponding HTML markup. Many webpages do this including this one, Github, Bitbucket, and Wikimedia sites such as Wikipedia.

Usually "Markdown" refers to a specific creation of markup language, but it may also refer more generally to a set of plain-text-compatible markup that can easily be converted into corresponding HTML (another markup).

The phrase plain-text-compatible may not make much sense, but all this means is that there is not much of a difference between the look up Markdown before or after it is pre-processed into HTML and displayed by a web browser.

What Markdown Is Not

This site does not intend for Markdown to replace HTML. Markdown is useful for text semantics such as headers, lists, and paragraphs. Using generic markdown syntax for form controls and attributes would be unnecessarily complicated when we have access to perfectly acceptable HTML.

The distinction

...is difficult to make. There is currently no exact line that separates markdown from more advanced HTML controls other than the decisions made by existing parsers. Markdown is commonly accepted as user input (Wikimedia articles are a good example) and allowing for form controls could be risky. On the other hand, a separate server side parser could be used to create forms and other embedded content from markdown.

What Content Is

Content is another general term when it comes to websites or any hypertext data. Markdown For Content holds content to be any static content served by a GET request. Content is certainly subject to change at any time, but it is generally nothing more than formatted text -- the site copy, if you will.

What Content Is Not

Again, this distinction is not easy to make. In the same way that Markdown is generally not used to create form controls and other methods for manipulating the persistance layer (e.g. a database on the server) or dynamic content.

Form Controls

This is anything including form, input, select, and many more are form controls. It can be dangerous and also difficult for Markdown to create form controls, so this page does not advocate using Markdown for that purpose. This is do to some issues including:

Dynamic Content

This is any content that changes between page reloads due to DOM manipulation. Entire blocks of Markdown-generated content may be added or removed with DOM manipulation, but it is not recommended to do this with content between the blocks. The reason is that there is no guarantee a Markdown parser will output HTML in any specific way.

Using Markdown for Content

Note: This section discusses the reasons why you should use Markdown for web content. The how is expanded upon below.


Why You Should

Markdown has many advantages over HTML (when used as intended) that cannot be overlooked. The web has been around for a long time and the fact that there is no replacement for at least markup for yet is actually shocking. Markdown-for-Content hopes to change that.

It is easier to read

This is important for several reasons:

It's more universal

Many web developers cover many scopes including the HTML/JavaScript/CSS client side and a variety of scripting languages on the server side. It is a lot to ask for organizations to also have them edit and format site copy. One could even make the argument that it is wasteful as a talented developer could better spend their time elsewhere.

It's apparent that Markdown can save time and steps with respect to creating content for the web.

It has less room for mistakes

As stated in the previous section, the usual concerns with improperly written HTML go away when Markdown is used. Markdown is more forgiving with its semantics by design. This saves time and frustration simultaneously.

Additionally, the outline of your site is easier to visualize and compose in Markdown.

How You Will

Fortunately for all of us, Markdown parsers exist in multiple languages. Do what you will:

Perl

PHP

Python

Django supports Markdown with the markup extension. Markdown can be triggered in templates by applying the markdown filter:

{% load markup %}
{{ post.body|markdown }}

A more thorough explanation is available in the Django documentation

Haml in Ruby on Rails

Others agree that template and coding languages are inferior for content

You can use the :markdown filter to easily convert markdown content to HTML for display as long as you have one of the necessary extensions installed:

The Markdown content must be indented accordingly. Remember to keep indentation consistent.

.element-containing-markdown
  :markdown
    #markdown will work here

    * including lists *with emphasis*

    [and links](http://aysites.com)

You can use partials to render Markdown with Haml in Ruby on Rails.

What Needs to be Accomplished

Markdown for Content has several goals that should be realized as soon as possible, especially as the number of parsers for and flavors of markdown continue to increase.

A Standard for Web Content Markdown

Markdown for Content suggests using the specification outlined at Daring Fireball, but with a few changes and clarifications: