# 使用 Caddy Web服务器显示 Markdown 文件 | 大染志
建议阅读此篇文章前，先阅读本博客的前篇 Caddy上手文章 ——【快速上手更简单的 Web 服务器 —— Caddy】 本篇文章我们将利用 Caddy Web 服务器的Markdown 插件和它强大的网页模板功能，在直接托管，渲染显示Markdown文件。 现在得益于 Markdown 的简单易用，越来越多的文档都在使用使用 Markdown来编写。像我们常用的 Github、GitBook 等流

0%

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

Posted on 2017-10-12 Edited on 2025-10-25

建议阅读此篇文章前，先阅读本博客的前篇 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 进行展示。下面我将以为我本地的文件作为示例给大家展示效果和截图。

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

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
    25

    <!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 服务器，刷新页面。有没有觉得页面变得更加美观，漂亮了。

### 添加文档目录索引（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
    43

    <!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 文档了。

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

## 总结

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