标签 markdown 下的文章

如题,使用markdown格式写接口文档效率还是挺高的,因为你只需要关系接口的功能和内容,而不用在意排版,顺带提一下使用这个工具markdown_tables创建markdown格式的表格不要太方便!

需要说明的是如果是大型多人合作项目,还是老老实实用apidoc等工具吧。

接口大类
-----------
[toc]
-----------

### 接口1

#### 接口功能

> 接口说明

#### 接口地址

> 接口地址

#### 返回格式

> JSON

#### 请求方式

> GET

#### 请求参数

| 参数 | 必选 | 类型   | 默认值 | 说明                                    |
|------|------|--------|--------|-----------------------------------------|
| name | ture | string | foo    | 请求的项目名                            |
| type | true | int    | bar    | 请求项目的类型。1:类型一;2:类型二 。 |

#### 返回字段

| 返回字段 | 字段类型 | 说明                             |
|----------|----------|----------------------------------|
| result   | int      | 返回结果状态。0:正常;1:错误。 |
| reason   | string   | 错误说明                         |
| data     | string   | 数据                             |

#### 字段变化

字段变化说明

#### 接口示例

> 地址:接口地址示例


#```json
{
    "result": 0,
    "reason": "success",
    "data": []
}
#```

代码里的#请删除

什么是toc?

[toc]

table of contents 即文章目录

toc有什么用

废话,你说目录有啥用,方便查找呗

使用typecho的TX,一定会一点markdown吧,在文章中如果出现##this's h2 tag##,会被程序转换为

this's h2 tag

一个h标签就好比一本书的各个章节,如果我们能把他们清点一下,组成一个目录输出,岂不是妙哉!

TOC如何使用

简单到不能再简单,在你想插入目录的地方放一个[toc][TOC]即可(推荐大写)!

[TOC]必须处于顶格

typecho中的markdown

typecho的源代码中已经使用了激进的MarkdownExtraExtended类来转化md文件,为什么说他很激进呢?因为他扩展了标准的markdown,添加了很多个性化的语法,如直接给元素添加id或者class,还有脚注、缩写词等,用起来确实很爽!但需要注意的是:太多的非标准语法可能会带来移植性差的问题

具体的语法参考请看这里php Markdown Extra

如何使typecho支持toc

要使typecho支持toc需要替换位于源程序中的/wwwroot/var/文件夹下的MarkdownExtraExtended.phpMarkdownExtraExtended.php

原理

这个文件的作用就是为typecho提供md2html的作用,我修改了MarkdownExtraExtended类的__construct方法,为block_gamut数组添加了 doToc 处理模块,并把优先级降到最低。

转换细节位于doToc_doToc_callback中,在此不作赘述。

不完美的地方

  • 要是能加入一个锚点之间平滑滚动的效果就更完美了,改天写个插件弄一弄
  • 在首页也能看到目录,改天看看源代码研究一下,看能不能解决
  • 希望后台加一个选项,自动生成目录,这个比较麻烦,以后看情况解决

markdown是个好东西!让我们可以集中精力去写文章,提高文章质量,不过有几个方面还是值得吐槽的:

  • 超链接的target属性不能自定义
  • 在WP中插入图片太麻烦
  • 没有很好的支持或者支持标准不一
  • 待补充

推荐一个好工具:stackedit

还有他的升级版:stackedit-beta

2014年10月19日补充:

markdown标准语法请参考http://commonmark.org