mdout我开源了一款Markdown转Pdf命令行工具一获取安装使用说明

jiezi

5 年前

以下文档来自 JabinGP/mdout，如果觉得对你有帮助，不妨点个 star 鼓励一下~

一个 Go 语言实现的 Markdown 转 PDF 命令行工具，基于 headless chrome，简单、可靠、易安装、可定制化、易拓展

mdout 会根据后缀，自动识别输入类型

mdout markdown.md
mdout local_html.html
mdout http://www.baidu.com

mdout 可以完整保留你 md 文件里的代码格式，图片，甚至是数学公式，支持代码格式语法高亮

电脑不会如人一般等待页面加载完全再选择打印，电脑自动执行打印时页面尚未渲染完全是件非常头疼的事情，对此，mdout 没有简单地使用 sleep 休眠机制去碰运气，而是实现了一套非常简单的同步渲染机制，即便是你有 1 万行的 mathjax 数学公式、1 万行的代码语法高亮要渲染，mdout 都能完美的保证你的 pdf 上不会有任何一个未渲染完成的元素

除了 chrome，mdout 不依赖于其他任何环境，你只需要选择对于系统的安装包，下载并解压即可使用，更为 macOS 和 linux 提供了一键安装脚本，为 windows 提供了丰富的图文教程

mdout 将每个模板独立为主题，并且支持指定输出 html 文件，可以很方便地自定义页面配色，自定义语法高亮配色

mdout 基于 headless chrome，这使得 mdout 几乎兼容市面上所有能用于的前端组件，并且 mdout 将组件归类为主题的一部分，你同样可以输出 html 来调试自己的自定义拓展插件

由于 Github 下载速度实在是太过寒酸，只有 30KB/s，以下的链接全部来自于阿里云服务器，尽管服务器有带宽限制，但是应对这个大小的文件还是没问题的

mdout 同时支持 windows，linux，macOS，但目前只支持 64 位的系统

linux：mdout.linux.x86-64.tar.gz
macOS：mdout.macOS.x86-64.tar.gz
windows：mdout_windows_x86-64.zip

mdout 已经为各平台打包了可执行文件，因此无论何种方式安装，无非就是下载可执行文件压缩包后解压缩，解压完就可以在 mdout 所在文件夹使用 mdout 了

但是为了命令行使用方便，我更推荐将 mdout 配置到系统的环境变量中，这样随时随地随心所欲 mdout

稍微懂点命令行的使用以下命令即可轻松安装

linux

wget http://112.74.177.253:8000/f/edcb3b9e460d4d18ab3f/?dl=1
tar -xvzf mdout.macOS.x86-64.tar.gz
sudo mv mdout /usr/local/bin
mdout install

macOS

wget http://112.74.177.253:8000/f/100873c74622474da4d9/?dl=1
tar -xvzf mdout.linux.x86-64.tar.gz
mv mdout /usr/local/bin
mdout install

非常感谢 Fisher 的脚本支持! 自己日用的脚本

linux && macOS 推荐使用脚本安装

curl 方式

sh -c "$(curl -fsSL https://raw.githubusercontent.com/FisherWY/Shell/master/mdout/install_mdout.sh)"

wget 方式

sh -c "$(wget https://raw.githubusercontent.com/FisherWY/Shell/master/mdout/install_mdout.sh -O -)"

点击前文给出的各版本链接，下载成功后解压缩，你会得到一个 mdout 可执行文件

点击下载
- windows：mdout_windows_x86-64.zip

下载后使用 zip 工具解压缩，解压后会得到一个 mdout.exe 可执行文件

放置软件
将 mdout.exe 可执行文件放置平时放软件的地方，比如 D:\mdout 这个文件夹里面，此时你的 mdout.exe 的全路径应该是D:\mdout\mdout.exe
设置环境变量
如果不设置环境变量也可以使用，但是缺点是你需要使用 cmd，powershell 或者 gitbash 手动进入 D:\mdout 才能使用 mdout 命令

确定路径

设置环境变量，右键我的电脑 -> 选择属性 -> 左边的高级系统设置

选择高级 -> 点击环境变量

找到下半部分的系统变量，双击 Path 行

在弹出来的窗口选择新建

填入D:\mdout，然后一定要连续点完三个确定
检验
打开 cmd，或者 powershell，或者你有 gitbash 都 ok（推荐使用命令行的 windows 用户都装一个 gitbash），输入mdout，看到如下输出就是成功了

下载 linux 版本

点击下载
- linux：mdout.linux.x86-64.tar.gz

下载完成后解压 tar.gz 包，解压后会得到一个 mdout 可执行文件

将软件放入可执行文件库

打开终端，定位到刚刚下载的文件所在路径
```
cd 你的文件所在文件夹
```
然后将可执行文件直接移动到 /usr/local/bin，linux 环境下需要 sudo 权限
```
sudo mv ./mdout /usr/local/bin
```
输入密码就可以了
检验是否成功
输入mdout --version，看到版本号输出就是成功了

下载 macOS 版本

点击下载
- macOS：mdout.macOS.x86-64.tar.gz

下载后使用工具解压 tar.gz 包，解压后会得到一个 mdout 可执行文件

将软件移动到可执行文件库

打开终端，定位到刚刚下载的文件所在路径
```
cd 你的 mdout 可执行文件所在文件夹
```
然后将可执行文件直接移动到 /usr/local/bin
```
mv ./mdout /usr/local/bin
```
检验是否成功移动
输入mdout --version，看到版本号输出就是成功了

mdout 依赖于 chrome 浏览器，如果你的电脑已经安装了新版的 chrome 浏览器，无需更多配置，可以直接运行 mdout，如果是旧版的 chrome 浏览器，建议进行升级后使用，如果还未安装 chrome 浏览器，请安装后再使用 mdout

如果你不是使用脚本安装的，或者脚本安装不完全成功的，需要手动执行初始化，如果脚本安装成功，则跳过这一步

mdout 依赖于 html、css、js 的模板，但是模板没有打包进程序，这是出于自定义化的考虑，执行初始化命令，程序会自动下载需要的文件到配置文件路径，至于这个路径在哪，在后面会提到，同时初始化程序执行结束后也会输出这个路径，请记住这个路径，在一些自定义和设置默认值时会使用到

mdout install

mdout 文件路径

文件在当前目录
```
mdout yourfile.md
```
或文件在上级目录
```
mdout ../yourfile.md
```
文件路径也可以是绝对路径
```
mdout /tmp/markdown/yourfile.md
```

每个命令行程序都有帮助文档，mdout 也不例外

mdout -h
mdout --help

mdout 支持许多输入类型，其中最普遍的就是 markdown，但同样也支持 html 输入，url 输入，但是注意，如果输入是 url，不要忘记带上http:://

markdown
```
mdout yourfile.md
```
html
```
mdout yourfile.html
```
url
```
mdout http://www.baidu.com
```

对于 markdown 输入，mdout 支持输出中间过程的结果。但对于 html 输入或者 url 输入，它们的唯一输出结果就是 pdf 文件了

markdown 输出 pdf（输出 pdf 为默认选项)
```
mdout youtfile.md -t pdf  
mdout yourfile.md
```
markdown 输出解析后 html 标签（这个选项可以得到 markdown 解析器的解析结果）
```
mdout youtfile.md -t tag
```
markdown 输出经过处理后的完整 html 文件（常常用来调试主题）
```
mdout youtfile.md -t html
```

mdout 支持指定输出路径，输出文件名

你可以使用 -o 来指定输出路径，-o选项同样做了防呆设计，你可以指定路径但不带文件名，mdout 会自动识别你输入文件的文件名和你指定的输出类型为你设置名称，但你同样可以指定路径 + 文件名

指定输出到上级文件夹，自动命名
```
mdout yourfile.md -o ../
```
指定输出到 /tmp/markdown 文件夹，自动命名
```
mdout yourfile.md -o /tmp/markdown
```
指定输出到当前文件夹下的badoutput.name
```
mdout yourfile.md -o badoutput.name
```
千万不要这么干，尽管程序不会阻止你设置你的文件名，但是使用规范的后缀是个好习惯。
指定输出到当前文件夹下的goodname.pdf
```
mdout yourfile.md -o goodname.pdf
```

主题系统只对 markdown 输入有效

mdout 有着方便易用的主题系统，你可以很自由地自定义主题，mdout 预设了三套主题

默认主题：default
数学公式拓展主题：mathjax
github 风格主题：github

你可以使用 `-e` 选项来指定主题

指定为 github 主题
```
mdout yourfile.md -e github
```
指定为数学公式拓展主题
```
mdout yourfile.md -e mathjax
```

指定主题后上面提到的输出选项依旧可用，可以配合 -t html 选项输出中间的 html 文件，这样可以调试主题效果，详细的说明将在自定义章节中提到

default和 mathjax 这两套主题的配色是一模一样的，区别在于 mathjax 是同时支持代码语法高亮和数学公式渲染的，而 default 只支持代码语法高亮

mathjax可以渲染类似这样的公式

$$\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.$$

我可以将 mathjax 设为默认主题并删除 default，但是我没有那么做，因为default 可以作为一个能满足代码语法高亮的最小模板 （当然你可能不需要代码语法高亮，这样的话 default 并不能算最小模板），基于 default 模板进行自定义主题将变得非常简单

至于自定义主题的教程，将在后面提到

此项仅在输出 pdf 时有效

mdout 预设了 8 种页面大小，如果有更多需求，可以在 issues 提出

A1 – A5
Legal
Letter
Tabloid

A4 为默认输出页面大小，你可以使用 -f 来指定输出页面的大小。同时做了防呆设计，如果你一不小心打成了大写、小写，甚至你手抽打成了大小写混合，都是可以正常识别的。可惜，防呆不防傻，你把字母都打错了就不能怪我了

指定输出 pdf 页面格式为 A4（闲着没事干敲着玩）
```
mdout yourfile.md -f a4
```
指定输出 pdf 页面格式为 Tabloid
```
mdout yourfile.md -f tabloid
```

mdout 只支持两种方向

纵向：portrait
横向：landscape

默认打印页面方向为纵向，你可以使用 -r 指令来指定页面方向格式

指定输出 pdf 页面格式为横向
```
mdout yourfile.md -r landscape
```

mdout 支持你自定义页面边距，以英寸为单位，默认为 0.4 英寸

0.4 英寸 ≈ 10cm

你可以使用 -m 指令来指定页面边距大小

指定打印边距为 0.2 英寸
```
mdout yourfile.md -m0.2
```
去除页面边距
```
mdout yourfile.md -m0
```

在配置文件安装目录下面

macOS : /Users/ 你的用户名 /binmdout
linux: /home/ 你的用户名 /binmdout
windows: /c/users/ 你的用户名 /binmdout

有一个 conf.json 文件

{"Out":"","Type":"pdf","Theme":"default","PageFormat":"a4","PageOrientation":"portrait","PageMargin":"0.4"}

包含了以上所有的可选设置，直接修改配置文件可以作为每次使用 mdout 的默认参数值

mdout 有着简单易用的主题系统，跟着下面的步骤来，你可以很轻松的添加自己的自定义效果

首先打开你的配置文件所在的文件夹

在你的配置包里面会有一个 conf.json 文件和 theme 主题文件夹，其中 conf.json 文件是用来更改默认参数的，theme存放了你的主题包。

进入 theme 主题包，你可以看到默认的三个主题包

default
mathjax
github

假设你现在需要自定义你的页面配色，大小，语法高亮等一切和 css 有关的内容，并且你想要为你的主题起名为mytheme

首先你需要完整复制 default 的所有内容，到 default 文件夹所在的目录并重命名为 mytheme，此时你的theme 文件夹里有四个文件夹：

default
mathjax
github
mytheme

然后你需要找到一个测试用例比如说这样一个 markdown 文件

# 测试标题

## 测试二级标题

### 测试三级标题

#### 测试四级标题

- 测试无序列表 1
- 测试无序列表 2

1. 测试有序列表 1
2. 测试有序列表 2

- 测试嵌套
    1. 测试嵌套第二次
        - 测试嵌套第三层


> 测试引用

测试表格

| 标题 1 | 标题 2 | 标题 3 |
| ----- | ---- | ---- |
| 文本 1 | 文本 2 | 文本 3 |
| 文本 4 | 文本 5 | 文本 6 |

** 这是加粗的文字 **  
* 这是倾斜的文字 *  
*** 这是斜体加粗的文字 ***  
~~ 这是加删除线的文字~~

![百度图片](https://ss0.bdstatic.com/5aV1bjqh_Q23odCf/static/superman/img/logo_top_86d58ae1.png)

[测试超链接](https://github.com/JabinGP/mdout)

` 测试代码段高亮 `

测试代码块高亮

    package main

    import ("fmt")

    func main() {fmt.Println("Hello Mdout")
    }

紧接着使用 mdout yourfile.md -e mytheme -t html 来获取这个 markdown 文件指定 mytheme 主题的 html 输出结果，用编辑器打开 html 文件，同时用 chrome 打开 html 文件，可以看到，页面已经自动引入了你刚刚创建的自定义主题包 css

<!-- 添加页面样式 -->
<link rel="stylesheet" href="/Users/jabin/binmdout/theme/mytheme/css/page.css"/>
<!-- 添加 hljs 样式 -->
<link rel="stylesheet" href="/Users/jabin/binmdout/theme/mytheme/css/hljs.css"/>

主题配色分为两个文件，一个是页面配色 css 文件，一个是代码高亮的 css 文件

如果你要修改页面配色，只需要一边开着浏览器，一遍打开刚刚主题包里面的
mytheme->css->page.css 修改，然后刷新浏览器查看结果

或者你想更改语法高亮的配色，由于 mdout 依赖于 hljs，你只需要去 hljs 官网下载你喜欢的主题包，然后替换 mytheme->css->hljs.css 里的内容就可以了

如果你完成了你的主题修改，你可以将刚刚生成的 html 删除，或者你想留做自己动手的纪念也是可以的

最后，你可以使用 mdout yourfile.md -e mytheme 来指定使用你的自定义主题啦，或者你可以在前面提到过的 conf.json 里面配置默认使用你的 mytheme 主题

如果觉得对你有帮助，点个 star 吧！

mdout我开源了一款Markdown转Pdf命令行工具一获取安装使用说明

mdout

mdout 有何特点

简单

可靠

易安装

可定制化

易拓展

获取和安装

适用于老鸟的安装方式

脚本安装

手动安装

windows

linux

macOS

使用说明

使用前提

进行系统初始化

最简单的示例

文件路径可以是相对路径

帮助文档

输入文件类型

输出文件类型

输出路径

指定主题

你可以使用 `-e` 选项来指定主题

打印页面设置

打印页面大小设置

打印页面方向设置

打印页面边距设置

自定义配置文件

自定义配色

mdout

mdout 有何特点

简单

可靠

易安装

可定制化

易拓展

获取和安装

适用于老鸟的安装方式

脚本安装

手动安装

windows

linux

macOS

使用说明

使用前提

进行系统初始化

最简单的示例

文件路径可以是相对路径

帮助文档

输入文件类型

输出文件类型

输出路径

指定主题

你可以使用 -e 选项来指定主题

打印页面设置

打印页面大小设置

打印页面方向设置

打印页面边距设置

自定义配置文件

自定义配色

你可以使用 `-e` 选项来指定主题