Online gh-pages generator

将 Markdown 文件转换为不同主题的 GitHub Page 网页

功能
示例
主题
- 通用配置
- 主题相关配置
  - Cayman
  - Minimal 和 Modernist
评论
- 多说
- Disqus
扩展语法
- Todo列表
- Mathjax
- 时序图
- Emoji
- ECharts
  - 配置
- 自定义扩展
其他说明

功能

支持多种页面主题
Prism.js / Highlight.js 代码高亮
自动生成目录
本地图片显示
导出 Html （包含样式）
评论
- 多说
- Disqus
扩展功能
- Toto 列表
- MathJax
- 时序图 (Js sequence diagrams)
- Emoji (Emojify.js)
- 图表 (ECharts)

示例

示例文件
 效果预览

主题

现在支持下面 6 种主题，以后会增加更多的主题。

通用配置

主题通用的配置如下所示，在 Markdown 文件中插入下面的代码块即可。

```ghpages
{
    title: "名称",
    desc: "描述",
    github: "github 地址",
    zip: "zip 文件下载地址",
    tar: "tar.gz 文件下载地址",
    footer: {
        owner: '作者信息', 
        credits: '相关声明'
    }
}
```

主题相关配置

Cayman

在 Cayman 主题中，可以添加新的链接。如下所示:

```ghpages
{
    link: [
    	{
    		order: 1,
    		text: "Other Link",
    		url: "#"
    	}
    ],
}
```

order - 链接显示的顺序。 github, zip, tar 对应的值分别为10, 11, 12。数值较小的链接在前面显示。数值相同的链接按出现的先后顺序显示。
text - 链接显示的文字
url - 链接的 url 地址

Minimal 和 Modernist

在这两个主题中，需要配置项目的名称信息，如下所示：

```ghpages
{
    project: {
    	url: "#",
    	name: "zhangjikai/online-ghpages-generator"
    },
}
```

多说

通过在 Markdown 文件中添加下面代码来配置多说

```comment
{
    "key": "filename",
    "title": "filename",
    "url": "filename.html",
    "short_name": "shortname"
}
```

Disqus

通过在 Markdown 文件中添加下面代码来配置Dsiqus，这里的 url 要使用完整的地址

```comment
{
    "key": "filename",
    "url": "http://xxx.xxx/filename.html",
    "short_name": "shortname"
}
```

扩展语法

Todo列表

- [x] 完成
- [ ] 未完成
- [ ] 未完成

Mathjax

支持原生的 Mathjax 语法。示例代码：

$$
        \begin{matrix}
        1 & x & x^2 \\
        1 & y & y^2 \\
        1 & z & z^2 \\
        \end{matrix}
$$

关于Mathjax 语法，请参考MathJax basic tutorial and quick reference

不过直接使用原生的 Mathjax 语法，marked 会将公式中的 \\ 转为 \，导致换行失效，为了解决这个问题，这里做了一下扩展，将 Mathjax 代码放入代码块中，代码块语言设为 mathjax 即可。如下面的示例

```mathjax
$$
        \begin{matrix}
        1 & x & x^2 \\
        1 & y & y^2 \\
        1 & z & z^2 \\
        \end{matrix}
$$
```

时序图

在 Markdown 文档中添加下面的代码块，会将代码块中的代码解析为时序图

```seq
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow
```

Emoji

Emoji表情参见 EMOJI CHEAT SHEET

ECharts

在文档中加入下面的代码块，会将代码块中代码解析为 ECharts 图表。只支持默认的数据显示，无法添加自定义的事件处理。

```echarts
{
    title: {
        text: 'ECharts 入门示例'
    },
    tooltip: {},
    legend: {
        data:['销量']
    },
    xAxis: {
        data: ["衬衫","羊毛衫","雪纺衫","裤子","高跟鞋","袜子"]
    },
    yAxis: {},
    series: [{
        name: '销量',
        type: 'bar',
        data: [5, 20, 36, 10, 10, 20]
    }]
}
```

配置

目前自定义了三个配置项：

width：图表宽度，可选，默认值是 100%
height: 图表高度，可选，默认值是 400px
theme: 图标主题，可选，有效的主题是： dark, infographic, macarons, roma, shine, vintage

其余的参数都是 ECharts 中定义的参数，具体的参考 ECharts 配置。下面是一个完整示例

{
    width: "600px",
    height: "400px",
    theme: "macarons",
    title: {
        text: 'ECharts 入门示例'
    },
    tooltip: {},
    legend: {
        data:['销量']
    },
    xAxis: {
        data: ["衬衫","羊毛衫","雪纺衫","裤子","高跟鞋","袜子"]
    },
    yAxis: {},
    series: [{
        name: '销量',
        type: 'bar',
        data: [5, 20, 36, 10, 10, 20]
    }]
}

自定义扩展

在现有程序的基础上，我们可以很方便的添加扩展功能。基本流程大概就是引入扩展的库文件，在渲染 Markdown 文件时调用库文件相应的方法。以添加时序图为例：

确定时序图的代码标记

```seq
时序图代码
```

修改 marked 中对于代码块的解析函数，添加对于时序图标记的支持

var renderer = new marked.Renderer();
var originalCodeFun = renderer.code;
renderer.code = function (code, language) {
    if (language == "seq") {
        return "<div class='diagram' id='diagram'>" + code + "</div>"
    } else {
        return originalCodeFun.call(this, code, language);
    }
};
marked.setOptions({
    renderer: renderer
});

引入 js-sequence-diagrams 相关文件

<link href="{{ bower directory }}/js-sequence-diagrams/dist/sequence-diagram-min.css" rel="stylesheet" />
<script src="{{ bower directory }}/bower-webfontloader/webfont.js" />
<script src="{{ bower directory }}/snap.svg/dist/snap.svg-min.js" />
<script src="{{ bower directory }}/underscore/underscore-min.js" />
<script src="{{ bower directory }}/js-sequence-diagrams/dist/sequence-diagram-min.js" />

渲染 Markdown 文件时，调用相关函数

$(".diagram").sequenceDiagram({theme: 'simple'});

如果不需要某个扩展功能，可以停用该功能，以加快文件渲染的速度。

其他说明

Markdown 文件解析

程序使用 marked 解析文件。

本地图片

如果需要显示本地图片，需要手动的将图片上传一下（支持批量上传），程序使用 FileReader 读取上传的图片，然后将图片的本地路径替换为图片的内容。图片压缩对 jpg 文件效果较好，对于 png 文件效果较差。

缓存

上次打开的文件和配置信息都保存在 localStorage 里，如果清理了缓存，就可能丢失这些信息。另外浏览器对于 localStorage 的容量有限制，所以不要保存太大的文件。

zhangjikai / online-ghpages-generator