---
title: "使用 Caddy Web服务器显示 Markdown 文件"
date: 2017-10-12 16:15:00
tags: [caddy, markdown]
---

建议阅读此篇文章前，先阅读本博客的前篇 Caddy上手文章 ——【[快速上手更简单的 Web 服务器 —— Caddy](http://toozhao.com/2017/09/19/caddy/)】

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

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

## 安装 Caddy

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

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

## 初步渲染 Markdown

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

```bash
0.0.0.0:8080 {
  markdown {
    ext .md .markdown
  }
}
```

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

![files](/files.png)

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

![raw](/raw.png)

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

### 美化 Markdown 文件

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

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

```html
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>`标签是为了，限制页面内容的宽度，和将内容居中显示。

```bash
0.0.0.0:8080 {
  markdown {
    ext .md .markdown
    template template.html  #后面的值即为模板文件的文件地址
  }
}
```

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

![css](/css.png)

### 添加文档目录索引（TOC）

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

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

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

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

```html
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](/final.png)

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

![monitor](/another.png)

## 总结

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