建议阅读此篇文章前,先阅读本博客的前篇 Caddy上手文章 ——【快速上手更简单的 Web 服务器 —— Caddy】
本篇文章我们将利用 Caddy Web 服务器的Markdown 插件和它强大的网页模板功能,在直接托管,渲染显示Markdown文件。
现在得益于 Markdown 的简单易用,越来越多的文档都在使用使用 Markdown来编写。像我们常用的 Github、GitBook 等流行服务也都在使用 Markdown。那么为什么越来越多的相关技术文档和资料都是使用 Markdown 编写的呢?我觉得所有原因都归于『简单』二字。我们通过一些常用的符号标记,就可以写出格式整齐、漂亮的文档。而不用写繁琐的 HTML。而通过简单的工具转化,我们就可以将 Markdown 文档转成 HTML 的格式。
安装 Caddy
那现在就让我们来实现这个功能吧,首先你得在你的电脑或者服务器上安装 Caddy,如何安装?请查看之前的文章进行回顾或直接运行如下脚本:
初步渲染 Markdown
Markdown 作为 Caddy Web 服务器的标准指令,使得我们可以直接在 Caddyfile 配置文件中使用该指令,托管,渲染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
的网页文件,添加如下内容:
|
|
我们的 Markdown 文本内容会在 <div class="markdown-body">
中显示。github-markdown-css
库会对类名为 markdown-body
中的内容进行美化。.Doc.title
和 .Doc.body
则是网页模板中的动态内容,前者为文档的文件名,而后者为文档中的全部内容。与此同时,我们需要在 Caddyfile 配置文件中添加模板特性。
HTML 中而外的 <style>
标签是为了,限制页面内容的宽度,和将内容居中显示。
|
|
重启 Caddy 服务器,刷新页面。有没有觉得页面变得更加美观,漂亮了。
添加文档目录索引(TOC)
现在我们的 Markdown 文档已经可以很美观的进行展示了,但是我们还可以做得更好,让用户在第一屏就可以查看当前文档的目录索引,而且可以点击链接进行快速访问和跳转。 这就是我们常见的 TOC 功能。(Table of contents)
为了实现 TOC功能,我们需要引入两个 JS 库:
- jQuery, 由于 Caddy 在对 Markdown文档进行转化时,没有为h1,h2,h3 这样的标题添加 id属性,而我们的
<a>
链接跳转,正需要 id 属性。因此,我们需要手动为各级标题添加 id 属性。 - tocbot,该 JS 库可以自动生成 TOC 内容。
因此修改我们的网页模板成类似以下内容:
保存后,直接刷新页面。我们就可以看到带有 TOC 的 Markdown 文档了。
我们还可以试着访问下另外目录下的 Markdown 文件,可以看到所有 Markdown 文件都带有 TOC 和美观的样式了。
总结
所以,如果你不想把 Markdown文档放到 Github 或者使用 GitBook 来托管,可以试试这种方法,快速搭建一个基于 Caddy 服务器的 Markdown 文档的网站。