If you’re a software engineer，你可能花了很多时间来改善你的环境，以提高你的工作效率. You’ve got your favorite IDE. You’ve got your favorite debugger. You’ve got your favorite performance monitoring tool. But what about your tool for writing documentation, manuals, and reports? After all, writing does take a non-trivial amount of your time, doesn’t it? Indeed, it’s time to get serious about your writing tool.

And let’s remember that you are technical, so WYSIWYG editors may or may not be the best option for you. You don’t necessarily want (or even like!) navigating menus, toolbars, and ribbons to format your text.

So what if, instead, 您可以轻松地将所有格式化样式作为简单的内联语法添加到文本中，从而生成完全格式化的文本?

Well, in fact, you can. That’s Markdown and that’s what this tutorial is all about.

When More is Less…

文字处理软件的编写是为了满足极其广泛的用户和用例, as such, needs to provide all sorts of functionality. But clearly, 只有一小部分功能可能与每个用户相关. And for most users, 谁只是想写一个文档(不需要设计一个营销宣传册或海报), a very small subset of the many, many options available are relevant.

In fact, 微软在几年前就意识到了这一点，他们将Word的用户界面重新设计为不同的功能组，他们称之为“缎带”. Yet interestingly, 大多数用户会告诉你，他们发现新界面比之前的版本更令人困惑，更难以操作.

的确，在易用性和生产力方面，有时多则少.

… and When Less is More

Face it, you’re a software engineer, not a graphic designer. 你只是想写手册，或者技术文档，或者报告，然后完成它. 你会非常满意一些基本的格式化功能，比如标题, bulleted or numbered lists, and code blocks. And, oh yeah, some font formatting (bold, italics, etc.) would be helpful too. That’s about it. (And man, if you could even just do it in vi, that would really be awesome!)

Enter Markdown.

What is Markdown?

John Gruber (来自技术大师和互联网活动家的大量贡献 Aaron Swartz) created the Markdown language in 2004 with the goal of enabling people “to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid XHTML (or HTML)”.

Markdown was designed to be readable as-is, 而不会让它看起来像被标记或格式化指令(不像用RTF或HTML等标记语言格式化的文本，这些标记语言在原始格式下既难以编写又难以阅读)。.

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, that can then be converted into structurally valid HTML. So, to be entirely precise, Markdown is really two things:

1. A plain text formatting syntax
2. 一种将纯文本格式转换为HTML的软件工具(其第一个版本是用Perl编写的).

Markdown包含了一些简单、相当直观且易于使用的语法约定. 尤其是作为软件工程师的你——你不会因为需要学习和使用这些基本的语法惯例而拖延——Markdown确实可以是最有效的 path of least resistance between what you want to write and getting it written.

Learn Markdown: Getting Started

Markdown is easy to learn. Super easy. 你可以在五分钟内学会基本知识，很快就会成为你的第二天性. 而且——就像CSS和CSS预处理器之间的关系一样——你可以随心所欲地少用或多用.

If you’re used to any kind of plain text writing conventions, then you might already be familiar with some markdown conventions, such as numbers or dashes at the beginning of a sentence to create a list, asterisks around a word for emphasis, and so on. 因此，例如，如果您想以斜体显示某些内容，只需将其用星号括起来，就像 *this* (as opposed to clunkier HTML syntax like this).

类似地，您可以通过简单地在行(e .)前添加“#”前缀来指定H1标题.g., # Section Heading, rather than

Section Heading

).

Another great use for learning Markdown, especially for us software engineers, is to use it for documentation on source code repositories. Most repos include a README.md file (.md is the standard extension for a Markdown file). Github, for instance, has its own “Github-flavored Markdown”, which adds additional functionality specifically for development documentation. This can certainly save time over having to write this documentation in HTML.

举个简单的例子，假设你想在你的文档中包含以下代码片段:

Initiating Plugins

在你的容器上使用jQuery初始化pluginName，如下所示:

$(function() { $('#container').pluginName(); }); Using our container’s ID, we can initiate pluginName with the jQuery method .pluginName().

Here’s a comparison of how this would be done in HTML vs. Markdown:

For further help getting started, 网上有很多降价教程可以帮助你跟上进度，包括一个 Markdown overview by John Gruber (Markdown’s creator) as well as an online Markdown tutorial.

Markdown Parsers and Tools

在Markdown中编写完文章后，需要一个应用程序将语法解析为HTML. There are a few great ones that are free including:

• StackEdit -基于浏览器的Markdown编辑器，有一些同步选项与流行的服务，如Google Drive和Dropbox
• Online Kramdown Editor - another browser-based Markdown editor with an extremely simple interface
• Mou - the best Mac-based Markdown writer I’ve come across as a geekier option for developers; tons of features and free (while in beta) [this is what I used to write this article]
• MarkdownPad - great Markdown editor for Windows
• Texts - a nice cross-platform (Mac and Windows) editor; exports to multiple formats such as PDF, .doc and ePub

一些主流平台已经在编辑器中采用(或至少允许)Markdown功能，供希望使用它的用户使用. With others, such as WordPress, Evernote, and Google Docs, native support (at the time of writing this article) is not yet baked in, but custom solutions have been introduced by third parties. These include:

• Popular new blogging platform Ghost为了精简在线写作，该公司使用Markdown作为其内容编辑器.
• 对于WordPress, Jetpack插件现在正式支持Markdown，你可以在下面启用 Settings > Discussion if you use the plugin. Or you could use a plugin like WP-Markdown 这将转换你的帖子markdown内容为HTML，并回到markdown当你需要编辑它.
• For Evernote, some Markdown apps such as a the online editor Markable or the Mac editor Byword allow export and publishing directly to notes. 或者，如果你喜欢直接使用Evernote的web应用程序，你可以使用一个浏览器扩展名为 Markdown Here 按一下工具栏按钮，就可以将写入Markdown的选定笔记转换为格式化的文本.
• Google Docs doesn’t natively support Markdown yet, but a few editors (such as StackEdit) will export/sync directly with Drive.

The Downsides

Of course, with great simplicity comes limitations. As I’ve already explained, Markdown不是为需要高级格式化功能的复杂文字处理任务而编写的. If that’s what you need, Markdown is not the right tool.

But for developers who need to write a user manual or technical documentation or a technical report, Markdown在简单性和您需要的功能之间提供了近乎完美的平衡.

也许最大的缺点——尤其是对我们这些热衷变更控制的工程师来说——就是无法做到这一点 work collaboratively 并跟踪变化(不过，有一个值得注意的例外是 StackEdit plugin for Google Docs). And of course, with a minimal amount of effort, 你可以简单地通过git存储库在Markdown文档上进行协作，从而获得你通常需要的所有更改跟踪和协作.

Conclusion

So is learning Markdown for everyone? Of course not. No one tool ever is.

But if you’re a software engineer, it could very well be precisely the writing tool you’ve been looking for. So if you haven’t given it a try yet, you really should take it for a spin.