Thanks!

You are now subscribed to our monthly blog digest. Happy reading!

Click anywhere to dismiss ...

Subscribe to the Jungle Disk monthly blog digest:

  

Behind the Scenes - Generating Web Pages with Markdown

by Ryan Veazey / Behind the Scenes, Product, Technical / Jan 6, 2017 / Comments

Most of the time when you write documents that end up on the web, you likely don’t want to manually write HTML. If you’ve seen some of the content generated by a word processor or one of the “friendly” web page editors, you may have abandoned the idea of something generating a web page altogether! Today, I would like to tell you about an alternative option that you may not have tried using before. The format is called Markdown.

Benefits

Here are a few of the benefits of using Markdown:

  • Smaller size
  • Separate content from formatting - create or find a style once and apply it to many documents
  • Easily searchable and machine-readable
  • Supported (sometimes a superset or subset) by tools you may already be using like GitHub or Trello
  • Freedom in editors - use your favorite text editor or use one of many free tools in your browser, desktop or mobile device

Paradigm Shift

Traditionally, most people use Word Processors to craft documents. These programs were most often designed to be easily approached by users accustomed to composition by hand or by typewriter. Automated spelling and grammar checking are wonderful but thinking of documentation, a wiki or a blog post in terms of pages, footnotes and margins can be distracting and counterproductive. The resulting HTML is also notoriously inefficient and difficult to style.

Separate Content from Presentation

Ever spend more time formatting your document than writing it? It’s easy to get sidetracked changing fonts, rearranging images or trying to get just that one section to indent without affecting its neighbors. In a file like a Microsoft Word document or PDF, content and formatting are inextricable but they don’t need to be. If your target is the web, you’re probably leaning heavily on CSS to style your content anyway.

While some formatting is structurally important, some is not. Grouping together ideas into a paragraph or into a list is important, but deciding on margins and indentation is less so. Identifying sections with a heading or subheading is important, but font sizes, colors and borders can be changed without affecting the meaning. This idea is one of the motivations behind separating CSS from HTML.

Markdown

Markdown is saved as a plain text file, usually with a file extension of .md, and can be edited in any plain text editor. To generate your final document, you’ll feed this into a Markdown Processor which will render your final document. The output is generally HTML, but some can generate formats like PDF as well. Several web publishing and blogging platforms have built-in support for authoring in Markdown and many rich text entry boxes on the web in various places have at least partial support for Markdown.

If you’re a developer, you can almost certainly find a package to render Markdown in your language of choice.

If you’re comfortable installing a node package, Markdown-to-html is a simple command-line utility to generate Markdown.

Syntax

For a complete reference, you’ll want to check something like this cheat sheet.

If you’re targeting a specific platform or renderer, you may want to check that documentation for additional features or quirks. There are also several popular supersets, such as GitHub Flavored Markdown.

There are also interactive tutorials for learning the syntax and online editors/previewers such as Dillinger

Basic formatting is notated with additional characters, such as:

*italics*

italics

**bold**

bold

- list item 1
- list item 2
  • list 1
  • list 2
[Link to a great backup product](https://www.jungledisk.com)

Link to a great backup product

If Markdown doesn’t quite fit your needs but sounds like a good idea, there are several very good formats similar such as Asciidoctor, which may suit your needs better. Even so, taking the time to learn just the basics of Markdown, like the basics of HTML, can often help you in unexpected places down the road.