DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workkloads.

Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Functional Programming Patterns With Java 8
  • Comparison of JavaScript Pivot Grids for Developers
  • Unlocking the Power of Configuration Management Database (CMDB)
  • Leverage Lambdas for Cleaner Code

Trending

  • Failure Handling Mechanisms in Microservices and Their Importance
  • *You* Can Shape Trend Reports: Join DZone's Software Supply Chain Security Research
  • Zero Trust for AWS NLBs: Why It Matters and How to Do It
  • My LLM Journey as a Software Engineer Exploring a New Domain
  1. DZone
  2. Data Engineering
  3. Databases
  4. Writing in Markdown: An Introduction

Writing in Markdown: An Introduction

Markdown is a simple plaintext document format that makes it easy to focus on your writing.

By 
B Jones user avatar
B Jones
·
Feb. 11, 19 · Tutorial
Likes (2)
Comment
Save
Tweet
Share
6.7K Views

Join the DZone community and get the full member experience.

Join For Free

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,

* Item one 
* Item two 
* Item three 

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.

  • HackMD, collaborative markdown notes
  • Showdown Live Editor
  • Dillinger
  • StackEdit
  • JBT’s Markdown Editor
  • Minimalist Online Markdown Editor
  • Markdown-it Online Demo
  • JavaScript Markdown Editor — SimpleMDE
  • CommonMark Demo

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 plaintext 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.

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 GitHub Basic Writing and Formatting Documentation.
  • Style guides and syntax checkers that I’m aware of include markdown-styleguide, vscode-markdownlint for Visual Studio Code, markdownfmt and mdfmt for auto-formatting, and tidy-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 plaintext 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 plaintext 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:

  • marked
  • Showdownjs
  • commonmark.js
  • markdown-it
  • blackfriday
file IO Database IT code style Listing (computer)

Published at DZone with permission of B Jones, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Functional Programming Patterns With Java 8
  • Comparison of JavaScript Pivot Grids for Developers
  • Unlocking the Power of Configuration Management Database (CMDB)
  • Leverage Lambdas for Cleaner Code

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!