If you have fast machine and recent Google Chrome or Safari installed, please check a bit more "moving" version of that presentation

Otherwise, scroll down to see the slides

用Markdown写

程序员的文档

有没有在写技术文档的时候遇到这样的问题?

你写的文档用MS Office打开时格式乱了! 下次发出来前一定用MS Office调整一下.

这个文档和上一个版本到底修改了什么地方啊!? 看Revision history?

嗯…? 我也忘了具体改哪儿了, 咱们一行一行对比一遍吧!

我花了一晚上把文档格式修正了一下. 什么? 你也改了? 这word文档怎么合并?! 我的改动少, 我在你的版本上再修改一次吧!

这该死的Open Office, 这么难用!?

什么?! 我修改的文档有病毒?!

你得申请文档库的权限. 咱们的代码库不让放大量的二进制文件, 所以…… 我给你发邮件告诉你文档的路径.

对, 我们的代码分了三条线. 设计文档? 文档只有一条线. 这三条线的区别不大, 不会audit这么严格吧?!

如何解决???!!!

要求

容易书写

容易阅读

Windows, Linux, Mac都能进行阅读和修改

可以diff和打patch, 方便进行版本管理

能和代码放在同一个版本库中

可以转换成html/pdf/doc等通用格式

简单易学

推荐: Markdown

Markdown设计的目标:

易读易写的适用于网络的文本书写语言

Markdown支持的语法

标题


# 这是H1

## 这是H2

### 这是H3

###### 这是H6

段落


这是段落1。
这还是段落1的内容，换行并不表示新起一段。

这是段落2，因为上一行是空行，空行意味着新起一段。

区块引用


> 这是一个含有两个段落的区块引用。区间引用必须以`>`+空格开始。
> 这是区块引用的第一个段落，因为中间没空行。
>
> 这是区块引用的第二个段落，因为上一行是空行。

区块引用

区块引用的段落


> Markdown也允许你偷懒只在整个段落的第一行最前面加上`>`
同一段落的其他行可以没有`>`。

> 这是区块引用的第二个段落，因为上一行是空行。

区块引用

区块引用可以嵌套


> 区块引用可以嵌套
>
> > 这是嵌套的区块引用
>
> 返回到第一层区块引用

区块引用

引用的区块内也可以使用其他的 Markdown 语法，包括标题、列表、代码区块等


> ## 这是一个标题。
> 
> 1.   这是第一行列表项。
> 2.   这是第二行列表项。
> 
> 给出一些例子代码：
> 
>     return shell_exec("echo $input | $markdown_script");

列表

`*`加上1-3个空格开头


* Red
* Green
* Blue

或者, `-`也行


- Red
- Green
- Blue

列表

或者, `+`也行


+ Red
+ Green
+ Blue

或者, 有序数字后面需要加上句点


1. Red
2. Green
3. Blue

列表

可以缩进，写得好看点


*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

列表

当然，如果你懒，下面也行…


*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

列表

列表项目可以包含多个段落，每个项目下的段落都必须缩进 4 个空格或是 1 个制表符


1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

列表

当然，再次地，如果你很懒惰，Markdown 也允许首行缩进…


*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

列表

列表里可以放进引用，那`>`需要缩进


*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

列表

列表里可以放进代码，代码需要缩进2次，也就是8个空格或者2个制表符


*   一列表项包含一个列表区块：

        <两次缩进后，代码写在这>

代码区块

缩进4个空格或是1个制表符的段落是代码区块


这是一个普通段落：

    这是一个代码区块。

一个代码区块会一直持续到没有缩进的那一行（或是文件结尾）

分割线

可以用三个以上的星号、减号、底线组成的单独行来建立分割线，星号或者减号中间可以加空格


* * *

***

*****

- - -

---------------------------------------

链接

链接文字都是用 [方括号] 来标记


This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

链接

可以用相对路径相同主机的资源


See my [About](/about/) page for details.

链接

可以在文件的任意地方预先定义参考式的链接, 预定义的链接不会生成页面内容


[id]: http://example.com/  "Optional Title Here"
[Android]: http://www.android.com/  "Google Android"

[] 内的字串是这个链接的id，可以含空格.

链接

在其他地方就可以直接通过 id 引用这个链接了


This is [an example][id] reference-style link.

或者, 如果这个 id 就是你想显示的文字


[Android][] 4.1, Jelly Bean, is the fastest and smoothest 
version of [Android][] yet.

强调

Markdown 使用星号（*）和底线（_）作为标记强调字词的符号


*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

单个字符表示强调(em)，双字符表示加强(strong)

内嵌代码

如果要标记一小段行内代码，可以用反引号把它包起来（`）


Use the `printf()` function.

如果要在代码区段内插入反引号，你可以用多个反引号来开启和结束代码区段


A span of code: `` There is a literal backtick (`) here. ``

内嵌代码

在代码区段内，& 和方括号都会被自动地转成 HTML 实体，这使得插入 HTML 原始码变得很容易


Please don't use any `<blink>` tags.

图片

可以直接插入行内图片


![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

在链接的语法前面加上感叹号 (!) 表明是图片链接

图片

也可以使用参考式图片


![Alt text][id]

[id]: url/to/image  "Optional title attribute"

HTML

当遇到markdown不能表达的格式时，可以直接写HTML语法


<img src="url" alt="Alt text" width="50" height="50"></img>

对 Markdown 感觉如何?

「易读易写」

如何发布 Markdown 写的文档 ?

HTML
PDF
或者其他…

Markdown 编辑器

Windows: MarkdownPad(http://markdownpad.com/)
Mac: Mou(http://mouapp.com/)
Others: Vim/Emacs/Sublime Text/……
Eclipse Plugin: http://www.winterwell.com/software/markdown-editor.php

Markdown 实现

http://en.wikipedia.org/wiki/List_of_Markdown_implementations

参考网站

http://wowubuntu.com/markdown/

http://daringfireball.net/projects/markdown/

谢谢 !

Use a spacebar or arrow keys to navigate