使用 Caddy Web服务器显示 Markdown 文件

发表于 | 更新于:

建议阅读此篇文章前，先阅读本博客的前篇 Caddy上手文章 ——【快速上手更简单的 Web 服务器 —— Caddy】

本篇文章我们将利用 Caddy Web 服务器的Markdown 插件和它强大的网页模板功能，在直接托管，渲染显示Markdown文件。

现在得益于 Markdown 的简单易用，越来越多的文档都在使用使用 Markdown来编写。像我们常用的 Github、GitBook 等流行服务也都在使用 Markdown。那么为什么越来越多的相关技术文档和资料都是使用 Markdown 编写的呢？我觉得所有原因都归于『简单』二字。我们通过一些常用的符号标记，就可以写出格式整齐、漂亮的文档。而不用写繁琐的 HTML。而通过简单的工具转化，我们就可以将 Markdown 文档转成 HTML 的格式。

安装 Caddy

那现在就让我们来实现这个功能吧，首先你得在你的电脑或者服务器上安装 Caddy，如何安装？请查看之前的文章进行回顾或直接运行如下脚本：

1
curl https://getcaddy.com | bash -s personal

初步渲染 Markdown

Markdown 作为 Caddy Web 服务器的标准指令，使得我们可以直接在 Caddyfile 配置文件中使用该指令，托管，渲染Markdown 文件。

1
2
3
4
5
6
0.0.0.0:8080 {
  markdown {
    ext .md .markdown
  }
}

这里的配置是说：在我们希望托管 Markdown 文件的服务器地址块中，让服务器对当前目录启用渲染 Markdown 文件的功能，即当我们访问 Markdown 文件时，Caddy 自动将其转化为 HTML 进行展示。下面我将以为我本地的文件作为示例给大家展示效果和截图。

files

如图所示为 Caddyfile 所在目录。可以看到这里有若干子目录，和子目录下面的.md 文件。现在让我们运行 caddy。 在浏览器中访问 http://localhost:8080/0.general/0.general.md文件。可以看到效果如下：

raw

Caddy 成功的将 Markdown文件以网页的形式进行展示，并且正确显示此了相应的格式和层次结构。但是这里有个美中不足之处，Caddy 渲染出的效果，不够美观。简单一点说，没有 CSS 修饰。

美化 Markdown 文件

那我们如何将Markdown 文件更加美观的展示呢？由于 Caddy 本身是使用 Golang 进行开发的，因此 Caddy 也将 Go 强大的模板功能提供给了用户。这里我们可以利用 Caddy 模板功能来美化 Markdown 文件。我们将在模板网页中加入特定 CSS 来美化页面。CSS 库来自： https://github.com/sindresorhus/github-markdown-css

在 Caddyfile 目录下创建一个叫 template.html 的网页文件，添加如下内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!DOCTYPE html>
<html>
<head>
  <title>{{.Doc.title}}</title>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/2.8.0/github-markdown.css">
  <style>
    .markdown-body {
      box-sizing: border-box;
      min-width: 200px;
      max-width: 980px;
      margin: 0 auto;
      padding: 45px;
    }
  </style>
</head>
<body>
  <div class="markdown-body">
    {{.Doc.body}}
  </div>
</body>
</html>

我们的 Markdown 文本内容会在 <div class="markdown-body"> 中显示。github-markdown-css 库会对类名为 markdown-body 中的内容进行美化。
.Doc.title 和 .Doc.body 则是网页模板中的动态内容，前者为文档的文件名，而后者为文档中的全部内容。与此同时，我们需要在 Caddyfile 配置文件中添加模板特性。
HTML 中而外的 <style>标签是为了，限制页面内容的宽度，和将内容居中显示。

1
2
3
4
5
6
0.0.0.0:8080 {
  markdown {
    ext .md .markdown
    template template.html  #后面的值即为模板文件的文件地址
  }
}

重启 Caddy 服务器，刷新页面。有没有觉得页面变得更加美观，漂亮了。

css

添加文档目录索引（TOC）

现在我们的 Markdown 文档已经可以很美观的进行展示了，但是我们还可以做得更好，让用户在第一屏就可以查看当前文档的目录索引，而且可以点击链接进行快速访问和跳转。 这就是我们常见的 TOC 功能。（Table of contents）

为了实现 TOC功能，我们需要引入两个 JS 库：

  • jQuery， 由于 Caddy 在对 Markdown文档进行转化时，没有为h1,h2,h3 这样的标题添加 id属性，而我们的<a>链接跳转，正需要 id 属性。因此，我们需要手动为各级标题添加 id 属性。
  • tocbot，该 JS 库可以自动生成 TOC 内容。

因此修改我们的网页模板成类似以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
<!DOCTYPE html>
<html>
<head>
  <title>{{.Doc.title}}</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/tocbot/3.0.4/tocbot.min.js"></script>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/2.8.0/github-markdown.css">
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/3.0.4/tocbot.css" />
  <style>
    .markdown-body {
      box-sizing: border-box;
      min-width: 200px;
      max-width: 980px;
      margin: 0 auto;
      padding: 45px;
    }
  </style>
  <script>
    $(document).ready(function () {
      //为各级标题自动生成id属性
      $("h1,h2,h3").each(function () {
        var hyphenated = $(this).text().replace(/\s/g, '-');
        $(this).attr('id', hyphenated);
      });
      // 初始化 toc 内容
      tocbot.init({
        tocSelector: '.toc', // 放置 toc 内容的容器
        contentSelector: '.markdown-body', // markdown 文档内容所在
        headingSelector: 'h1, h2, h3', // 需要索引的标题级别
        positionFixedSelector: ".toc" //将 toc 内容块位置固定。
      });
    });
  </script>
</head>
<body>
  <div class="toc">
  </div>
  <div class="markdown-body">
    {{.Doc.body}}
  </div>
</body>
</html>

保存后，直接刷新页面。我们就可以看到带有 TOC 的 Markdown 文档了。

toc

我们还可以试着访问下另外目录下的 Markdown 文件，可以看到所有 Markdown 文件都带有 TOC 和美观的样式了。

monitor

总结

所以，如果你不想把 Markdown文档放到 Github 或者使用 GitBook 来托管，可以试试这种方法，快速搭建一个基于 Caddy 服务器的 Markdown 文档的网站。