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