MDoc Maker

简介

MDoc Maker是一个简单、易用、免费的文档生成工具。

使用者可以轻松地使用超文本标记语言（html）或轻量级标记言语（markdown）编写文章。

使用类似Liquid语法（一种广泛的用在Ruby on rails和Django等框架中）可以扩展文章的表现能力。

用者只需要关注写作内容本身，而无需要关注文字的排版和文档的结构。

MDoc Maker会帮助使用者轻松生成技术文档、博客或者网站，自动导出Word,PDF等格式的电子文档。

如何使用

1. 首先下载MDoc Maker软件，该软件基于dotnetcore编写可以运行在windows， linux， mac等主流的操作系统上。下载完成后解压到合适的目录下。
2. 然后确保你的电脑上已经安装dotnetcore
3. 在windows上，使用管理员权限运行install.bat安装。
4. 在Linux上，使用以下命令安装：

   ln -s ~/writer.dll /usr/local/bin/mdoc
   

5. 通过以下几个简单的命令即可创建文章：

   //编辑文章
   mdoc path
   //保存修改到本地版本库
   mdoc save [comments]
   //查看文档的历史
   mdoc log
   //回退到历史版本
   mdoc reset version
   //生成文档的结构
   mdoc generate|g
   //同步远程的文档
   mdoc sync
   //发布到远程
   mdoc public|b
   

文件目录

mdoc没有明确的目录结构，除了配置文件，其它文件或文件夹都不是必须。但建议使用以下的目录结构：

• config.yml
• config.json
• asset
  • img
  • css
  • js
  • file
• data
  • *.csv
  • *.json
• doc
• themes
  • layout
• public

其中config.yml或config.json最重要，配置了网站所有设置，其它的目录也是在这个文件中配置。

1. asset里存储其它文件
2. data里存储数据
3. doc里存储文章
4. themes/* 里存储模板文件夹, 文件夹名称为模板名称
5. public是执行生成命令后的输入目录

配置文件

Mdoc中使用config.yml或config.json作为配置文件，用户可以根据自己的喜好选择，配置文件对整个站点进行设置。

如下所示：

# Configuration
## Url http://blog.zhumingwu.cn
## Source: https://github.com/bzway/dotWriter/

# Site
title: Demo
subtitle: subtile
description: this is a description for the site/book
author: zhumingwu

# Directory
data_dir: data
doc_dir: doc
theme_dir: theme
asset_dir: asset
public_dir: public
# Writing
default_theme: default
default_layout: uncategorized
date_format: YYYY-MM-DD
time_format: HH:mm:ss

或

{
  "title": "Demo",
  "subtitle": "subtile",
  "description": "this is a description for the site/book",
  "author": "zhumingwu",
  "data_dir": "data",
  "doc_dir": "doc",
  "theme_dir": "theme",
  "asset_dir": "asset",
  "public_dir": "public",
  "default_theme": "default",
  "default_layout": "uncategorized",
  "date_format": "YYYY-MM-DD",
  "time_format": "HH:mm:ss"
}

文章

文章的设置

文章的设置以结束作为文章相关的设置。例如：

<!---
title: 说明
category: '首页/产品'
layout: default
sort: 12
--->

• layout - 指定使用模板名称，必须是模板目录中的任意无后缀文件名。
• title - 文章需要显示的标题，默认为文件名。
• sort - 同一个目录下的文章出现顺序，默认文件名排序。
• date - 指定文件的更新时间，默认为文件的更新时间。

文章中参数

所有参数通过 {{ page.parameter }}引用，相关内容可以参考Liquid 语法

命令

简介

mdoc命令格式如下：

mdoc [<command>] [<args>]

不同的命令支持的参数不相同。

编辑

mdoc edit path

编辑，编辑已经存在的文件或创建一个新文件。该命令是默认命令，edit可以省略，所以它与下面的命令等效：

mdoc path

编辑命令会自动打开一个默认的文件编辑器，不同的操作环境编辑器可能不相同。

保存

mdoc save [comments]

保存已经修改过的文件，虽然系统的编辑器可以保存文件，但不是所有文件编辑器可以保留文件的历史版本。此命令可以保存文件修改的历史，从而保证了数据的安全和可回退。

如果需要回退版本可以参见：

mdoc reset version

历史

mdoc log [all]

查询文档的历史修改，这个功能可以让我们了解文档的历史和回退文档。

回退

mdoc reset version

回退到历史版本，其中version是通过log查询得到。

生成

通过mdoc generate|g可以快速生成文档目录相关的文件并存储在Data目录中。

manifest

列出所有使用的文件,格式如下：

<manifest>
<item id='' href='' media-type=''/>
<item id='' href='' media-type=''/>
</manifest>

spine

线性阅读顺序,格式如下：

<spine>
<itemref idref='manifestId'>
<itemref idref='manifestId'>
</spine>

ncx

{
  "navigation": {
    "uid": "guid",
    "title": "我的文档",
    "auth": "Adm Zhu",
    "child": [
      {
        "path": "/Folder1",
        "name": "第一章",
        "child": [
          {
            "path": "/",
            "name": "第一节"
          }
        ]
      },
      {
        "path": "/",
        "name": "第二章"
      }
    ]
  }
}
  

或在yaml中指定如下：

navigation:
 uid: guid
 title: '我的文档'
 auth: Adm Zhu
 child:
 -
  path: '/Folder1'
  name: "第一章"
  child:
   -
    path: '/'
    name: 第一节
 -
  path: '/'
  name: "第二章"

• path是文件所在目录的路径不可以修改，
• name为实际显示的内容。

menu

如果你希望自己的文档可以比较像一个网站包含菜单，你可以在yaml中指定

menu:
 -
  name: "主页"
  path: "/"
 -
  name: "博客"
  path: "/blog.html"
 -
  name: "关于我们"
  path: "/aboutus.html"

注意：菜单和导航的显示依赖于模板，如果模板中没有显示，需要自己编写相应显示。

同步

mdoc sync [pull|push|all]

同步远程的文档对象

发布到远程

mdoc public|b [version]

指定版本作为发布的版本，默认使用最新的版本。

开发

网站信息

网站的配置信息，即config文件中的信息，在代码中可以使用 {{ site.key }}访问

页面信息

在任何一个文件头设置的信息，在代码中可以使用 {{ page.key }}访问

数据

其它数据可以存储在data目录中，数据的格式可以是csv，json或yaml。在代码中可以通过 {{ data.filename }}访问到数据。

主题Theme

主题以文件夹的形式存储在Layouts中，包含样式使用的所有文件，比如：css, img 和layout。每个主题至少都应包含一个 index 模板，可以包含：

• index 首页
• post 文章 默认：index
• page 网页 默认：index
• blog 网页 默认：index
• tag 标签 默认：index

模板Layout

模板中可以使用{% include "head.html" %}引用其它文件内容。
使用 {{ body }} 指定主体内容的加载位置。

以下为网页的一个示例：

<html>
<title>{{title}}</title>
<meta name="description" content="{{description}}">
{% include "head.html" %}
<body>
    {{ body }}
    {% include "footer.html" %}
</body>
</html>

默认模板中的所有文件都会发布到网站中，也可以在模板根目录下增加ignore.txt文件，编辑需要排除的文件。比如：

*.[Oo]bj
*.html
[Oo]bj/
/css
bin

1. 其中以*开关的是文件类型的排除
2. 以/开头的目录从模板的根目录算起下属的所有文件夹和文件排除
3. 以/结尾是任意指定目录下属的所有文件夹和文件排除
4. 单独名称，只要包括此名称部分即排除
5. 同时可以使用[]列表多个可能字符。

[注：通常用户可以通过官网下载现成的模板]

相关资源

• yaml online
• liquid语法 or 官方标准
• yaml dotnet
• jekyll 文档
• hexo 文档