乐趣区

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

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

mdout

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

mdout 有何特点

简单

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

  1. 点击下载

    • windows:mdout_windows_x86-64.zip
下载后使用 zip 工具解压缩,解压后会得到一个 mdout.exe 可执行文件
  1. 放置软件

    mdout.exe 可执行文件放置平时放软件的地方,比如 D:\mdout 这个文件夹里面,此时你的 mdout.exe 的全路径应该是D:\mdout\mdout.exe

  2. 设置环境变量

    如果不设置环境变量也可以使用,但是缺点是你需要使用 cmd,powershell 或者 gitbash 手动进入 D:\mdout 才能使用 mdout 命令

    确定路径

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

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

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

    在弹出来的窗口选择新建

    填入D:\mdout,然后一定要连续点完三个确定

  3. 检验

    打开 cmd,或者 powershell,或者你有 gitbash 都 ok(推荐使用命令行的 windows 用户都装一个 gitbash),输入mdout,看到如下输出就是成功了

linux

  1. 下载 linux 版本

    点击下载

    • linux:mdout.linux.x86-64.tar.gz
下载完成后解压 tar.gz 包,解压后会得到一个 mdout 可执行文件
  1. 将软件放入可执行文件库

    打开终端,定位到刚刚下载的文件所在路径

    cd 你的文件所在文件夹

    然后将可执行文件直接移动到 /usr/local/bin,linux 环境下需要 sudo 权限

    sudo mv ./mdout /usr/local/bin

    输入密码就可以了

  2. 检验是否成功

    输入mdout --version,看到版本号输出就是成功了

macOS

  1. 下载 macOS 版本

    点击下载

    • macOS:mdout.macOS.x86-64.tar.gz
下载后使用工具解压 tar.gz 包,解压后会得到一个 mdout 可执行文件
  1. 将软件移动到可执行文件库

    打开终端,定位到刚刚下载的文件所在路径

    cd 你的 mdout 可执行文件所在文件夹

    然后将可执行文件直接移动到 /usr/local/bin

    mv ./mdout /usr/local/bin
  2. 检验是否成功移动

    输入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 文件,这样可以调试主题效果,详细的说明将在自定义章节中提到

defaultmathjax 这两套主题的配色是一模一样的,区别在于 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 吧!

退出移动版