Enginursday: An Ode to Markdown
How and why I use markdown everyday, for all of my documenting needs.
We've had a few Enginursday blog posts proclaiming our love for one programming language or another. Today I'd like give a shout-out to another syntactical wondertool: Markdown.
Markdown can create HTML-formatted code out of an eminently easier-to-read-and-write plain-text format. It's not really a programming language; it's a simple syntax that, when parsed by the right script, produces an HTML-tagged equivalent. It creates something like this...
...out of a happier, more readable something like this:
Writing your notes, documentation, or comments in Markdown is cleaner and faster than HTML could ever be. I use Markdown every day, whether I'm writing tutorials, taking notes, or just commenting on SparkFun product pages. Heck, this very blog post was written in Markdown. Even for an electrical engineer, I think it's a useful "language" to learn. Here's why:
Where It's Used (and Why You Should Learn It)
There's more to electronics projects or products than just creating and assembling a circuit -- documentation is critical! Markdown can make the process of documenting your project at least a little bit less painful. More and more websites are incorporating the syntax into their services; GitHub, our go-to version control system, is a great example of that. On GitHub you can Markdown-ize your readme's and your wiki's. You can turn those boring README.TXTs, into stylized, visually organized README.MD's.
GitHub's even created their own flavor of Markdown with additional syntax rules to help create tables, syntax-highlighted code blocks and more.
Markdown is also incredibly useful "offline." It's well-purposed for outlining your to-do lists, or taking notes because it's so easy to create headings, lists, and text emphasis. Even if you don't end up turning it into HTML, it's a great standardized tool for organizing your thoughts. Once you get a hang of the syntax, it can be quicker write in plain-text Markdown than some heavy rich-text editor.
Finally, if you're a regular SparkFun visitor, you should know that you can use Markdown to add extra formatting flavor to your comments. Use it to hide ugly URLs inside clicky links, or to formulate your gripes in a lovely ordered list. Click on "Formatting Help" below the text-box before clicking "Comment" to see what zest you can add.
Various flavors of Markdown exist, but if you want to get an overview of the syntax straight from the source, check out this page. It's all pretty sensible:
| Markdown | What You See |
|---|---|
| _italic_ | italic |
| **bold** | bold |
| [link!](http://www.sparkfun.com) | link! |
| *bulleted *list *fun |
|
| 1. ordered 2. lists 3. too |
|
| # Heading 1 ## Heading 2 ### Heading 3 | Heading 1Heading 2Heading 3 |
| `code block` | code block |
|  |  |
How to Use It
How you incorporate Markdown into your workflow depends a lot on how you're going to use it. If you use Markdown offline, you can use any plain-text editor (Notepad, Textedit, etc.) to create it. More advanced text editors, like Notepad++, may even have options or plugins to enable syntax highlighting. Later on you can use a tool like dingus to convert it to HTML. Or, because it's already nice and readable, you can just leave it be.
When I'm writing README's or tutorials, I like using specialized Markdown editors -- tools which usually combine a simple text editor with syntax highlighting, and even live-updating previews. Markdown Pad serves me well on my Windows machine, and I make every excuse I can to use Mou on my Mac. Most editors even allow you to plug in your own CSS to get a better preview.
The dual-view power of Mou and similar MD editors.
If you're more interested in customizing the syntax, you can run the script yourself as long as you have Perl installed. Download "Markdown.pl", then run a UNIX command like perl Markdown.pl readme.md >> readme.html to turn a "readme.md" file into its equivalent HTML. It's open-source, so you can riff on the script to create your own version!
Are you a fellow Markdown-ian? Have any other tips, tricks, or uses for the language? Leave your Markdown-flavored comments below!
Nice writeup, Jim.
For a bit more background on SparkFun's usage of Markdown, we used to use one of the pure-PHP implementations - PHP Markdown most recently, I think. We've since switched to a wrapper around Discount, a pretty fast and likeable C library with some useful features.
I was resistant to Markdown at first - there are a million lightweight markup languages out there, and I liked various elements of other designs better - but it's grown on me to the point that I use it for most of my personal writing projects. I recently switched to using the Perl wrapper for Discount instead of Gruber's original pure-Perl code.
Vim heads may want to try installing plasticboy/vim-markdown - seems like I've had better luck with the syntax highlighting in that one than the bundled stuff, although it can still be a bit fragile on complex documents.
Serious users might also want to have a look at Pandoc, which we're thinking about using to generate tutorial PDFs.
Edit: And if you want the Markdown used to describe some SparkFun entity, you can often just check the JSON:
Awesome, awesome info, Brennan. Thanks!
When I wrote my tutorial for the Papilio for you guys, I didn't know what to use to help with the Markdown, but I did search and found Markdownpad 2.
It does on-the-fly rendering of the "webpage", and if you do the proper linking for images and things like that, it will show up appropriately. It was extremely helpful.
I suggest anyone writing a tutorial to give to SFE, give this program a shot. It is worth it, cause it's free.
Great intro article and I agree that Markdown is an important "language". It is very useful for Readme files Github, documenting IoT projects, etc. I have published an online page to enable people to Copy a Table from Excel and Paste as a Markdown Table that some might find useful.
A quick follow up comment on this: Finally got around to publishing our Markdown wrapper stuff.
Not criticizing Markdown and its ilk, but I find this article funny. I've been seeing this same article, more or less, since the mid-70's. Only the languages change. Sometimes it's text formatting languages, other times it's programming languages, but every time it's a new and superior whatsit that replaces that old inconvenient thingy. Right up until the next one pops out. Which actually ends up looking a lot like the old ones, except that the current author has his/her idiosyncrasies in it instead of the other author's. Look at RUNOFF from 1964 and see how similar it is in spirit to Markdown. Then there's the whole herd that followed - roff, troff, nroff, etc.
The one big difference is that the other programs formatted marked text into plain text, while Markdown goes to HTML, but if HTML had been invented in the 1960's, Strachey's macroprocessor could have easily accomplished the same thing.
So everything old is new again. Join us again next year for the latest whiz-bang that will replace everything that came before, but is very much like a re-implementation of what we had 50 years ago. Until then, have fun with Markdown, it's sort of cool.
There's a funny pattern here:
See also build systems, text editors, programming languages, web frameworks, GUI widgets, templating engines, etc. ad infinitum. But, ok, a couple thoughts:
First, I've written a lot in raw HTML, and I favor it for the general case: Stable and expressive trump pretty syntax a lot of the time. That said, there's a real advantage to be found in using a more restricted syntax for the bulk of similarly-formatted prose. One of the clever things about Markdown's design is that it's well-aware of its status as a utility syntax for HTML, and was originally built to pass the stuff through untouched.
Second, Markdown.pl has been around since like 2004, and emerged from a stew of extremely similar ideas going back at least to the wiki markup of the mid-1990s. In terms of the lifetime of the web, human-readable plaintext shorthand for basic markup was an obvious idea that occurred to people early on, and it's persisted for a reason. Its widespread adoption on the web is, if anything, maybe more of an indication that the software community has grown up some than it's an indication we're all still chasing whatever the latest shiny bauble is. (There are plenty of those; I just don't think this is one of them.)