Simple Markdown

Posted on  by admin

Markdown has steadily become the dominant way I compose most text documents, which is saying a lot.Its convenience, simplicity, expressiveness, and increasing ubiquity make it a compelling choice for all but a small fraction of the written material I produce.What is Markdown, and what makes it so great?And could/should you use it yourself?

Markdown is a simple plaintext way to write moderately complex text documents—the types of content you might otherwise use a word processor to write.It’s composed of raw, unformatted text, with no images, bold, italic, or anything like that.But it lets you include extremely simple formatting instructions within the text, which look almost like you want the formatted document to look.

The most obvious example is bulleted lists.The following code,

If you're particularly fond of the way Markdown makes it easy to add simple formatting, headings, links, and images, and would rather not jostle with. ReText es un editor de texto simple para Markdown y reStructuredText documentos con resaltado de sintaxis y vista previa en vivo opcional.

Introduces ↓markdown↓ CMS, the flat file, no db, easy and simple content management system for web publishing. (Note this index description will go in the meta description tag.).

Creates the following bulleted list:

  • Item one
  • Item two
  • Item three

Markdown really is that simple.You basically write a code that doesn’t look like a code.

This lets you stop writing with WYSIWYG visual editors that somehow manage to mangle your writing and insert annoying invisible code that makes odd, frustrating things happen—like a bulleted list that has extra space between bullets that you can’t seem to get rid of.

Many people report that when they write with Markdown, they feel more focused.Markdown has a way of disappearing and getting out of the writer’s way.This might be why Markdown-based writing tools emphasize things like minimalism and getting into the zone, into a state of flow.

The tradeoff is that Markdown doesn’t support everything you might want, such as complicated table layouts and image formatting.But it does support nearly everything you probably use on a daily basis: headings, paragraphs, lists, images, links, footnotes, bold, italics, and so on.Anything not supported in Markdown is still possible as long as HTML supports it, because an explicit part of the Markdown spec is that you can insert HTML tags anywhere you want.This gives you a lot of richness without a lot of complexity, and makes sure that anything you can do in a browser is possible in Markdown.

Many Markdown editors also add support for extensions such as charts, diagrams, math equations, and so on.Usually these are implemented with plugins such as MathJax or KaTeX for math equations, Mermaid for diagrams, and Chart.js for charts.

Online Markdown Editors

There are lots of JavaScript Markdown implementations, and that means it’s relatively simple to create a basic Markdown editor in a browser.As a result, there are lots of online Markdown editors.Many of them are far beyond the basics, though.If you’re not sure about Markdown, trying one of them is a great way to see what it’s all about.

Markdown-Compatible Programs

An ever-increasing number of editing programs for computers, phones, and tablets use Markdown as the underlying storage format.The advantage is that since it’s simply plain text files underneath, it avoids lots of problems, and it’s interoperable with tools nearly everyone uses.An example in my own life is the Bear Notes program I use as a simpler replacement of Evernote.

Here’s a (very partial) list of programs that support Markdown, in no special order:

  • Many static website generators like Hugo and Jekyll
  • 1Password (in encrypted notes)
  • GitHub issues, comments, wikis, and so on
  • Stack Exchange posts
  • The Airmail email client
  • Markdown Here for writing Markdown in tools like GMail
  • Browser-based slideshow programs like Remark and Reveal
  • A huge variety of programs for serious note-taking and writing, many with a specialty or particular purpose, and some of them open source: Bear Notes, Ulysses, Simplenote, Byword, IA Writer, Paper, Editorial, Scrivener, Quiver, Boostnote, Joplin, Write, Agenda, Notion, Corilla, Inkdrop, Remarkable, TaskPaper
  • Lots of dedicated Markdown file editors: Typora, Mou, MacDown, MultiMarkdown Composer, Marked2
  • Many newer text editors designed for programmers have Markdown live preview, such as Atom and Visual Studio Code

Building Websites with Markdown

It’s easy to create websites with Markdown.When you do this, you avoid having to type all the HTML tags, and your websites are cleaner and easier to maintain.Most modern blogging platforms now support Markdown, and there are lots and lots of other ways to use Markdown to simplify and eliminate toil.

Best

Here’s a sample:

  • Most modern blogging platforms like Ghost, Jekyll, and Hugo not only support Markdown, but assume you’ll prefer it.
  • Most other static website generators support Markdown. There are so many static site generators now that there are at least two listing sites: one, two.
  • You can even host websites entirely in Markdown. Here’s one example.
  • This website is built in Markdown with the open-source Story Hugo theme, which bundles a lot of extended features together such as Markdown slideshows and music notation.

Markdown References and Tools

There are lots of tools for working with Markdown: quick-start guides, syntax checkers, linters, and so on.Using these tools can help produce clean, tidy Markdown files and avoid mistakes.Here’s a partial list.

  • This Markdown Reference is the best quick-start guide for learning the syntax that I know of. Other helpful references include the Mastering Markdown GitHub Guide and the GitHubBasic Writing and Formatting Documentation.
  • Style guides and syntax checkers that I’m aware of include markdown-styleguide,vscode-markdownlint for Visual Studio Code, markdownfmt andmdfmt for auto-formatting, andtidy-markdown for fixing formatting mistakes and standardizing syntax.
  • Markdown Table generator for easy table generation.

Markdown Specifications and Standards

Markdown was originally described in what was essentially a blog post and a Perl program, but since then it has been formalized, and now there are various specs.

  • The CommonMark specification has become more or less the canonical reference specification. There’s also some extensions to the original Markdown syntax, such as those supported by the GitHub Flavored Markdown Spec. Most of these processor-specific extensions are included in the CommonMark syntax specification.
  • The Markdown Wikipedia page has a lot of additional information and references.

Markdown Meta-Standards

In addition to standards for Markdown itself, there are related standards that specify things like file naming and organizational conventions, which—when followed—allow tools to add extra functionality like workflows and special-purpose uses.Many of these are built upon, or compatible with, Markdown.Here’s a list of some I’m aware of:

  • Textbundle is simply a folder containing a markdown file, a manifest (in JSON format) and assets, such as images.
  • CriticMarkup is a plain-text language for proofreading and adding commentary (redlines, corrections, etc) to plain-text documents like Markdown.
  • Markaround is a file organization convention that lets Markaround-aware editing programs enhance the editing and file management experience.
  • Fountain is a markup language for screenwriting. It’s sort of like Markdown, and it’s supported by some apps that also support Markdown.
  • TaskPaper is also “sort of Markdown.” It’s a plain text to-do list app for Mac.

Markdown Processors

A Markdown processor is a programming library that reads Markdown syntax and translates it to fully formatted output, usually in HTML for web pages, but often for other purposes too, like PDF export.There are many Markdown processors.Some of the most common are:

With Assemble you can use markdown however you want, wherever you want

An advantage of writing content with markdown is that it is free from the angle brackets and tags used in HTML, so it feels and looks more like 'content' than 'code'.

With Assemble you can:

  • Write entire documents in markdown, and choose where and when to compile them to HTML
  • Write document fragments in markdown, so they can be 'included' or used as partials within other larger documents
  • Write sections of markdown directly inside HTML documents (referred to as 'inline markdown')

'Include' extenal content

Use the markdown expression, {{md}}, to enable importing of external markdown content.

Example #1: using full path

Example #2: using variables Or use a variable instead of setting the path directly inside the template. For example you can add the content variable to the YAML Front-Matter:

then use it like this:

Markdown 'includes'

Using the {{md}} markdown helper, you can import markdown formatted content from another file, and render it to HTML. For example:

Assuming we have a file named index.hbs, and we add the following:

Markdown Apps

And give that content.md contains the following:

When we run grunt assemble, a file named index.html will be rendered containing:

The same can be accomplished by specifying the path to the file in the YAML Front Matter:

Markdown block expression

Simple Markdown Cheat Sheet

The {{#markdown}}...{{/markdown}} block expression is used to 'wrap' markdown content that is written 'inline' directly inside HTML documents:

In a layout, can also wrap the {{> body }} tag with the {{#markdown}}...{{/markdown}} block helper to convert any HTML pages that use that layout to markdown:

Related Information

Simple Markdown Editor

  • [options.marked][options-markded]