mirror of
https://github.com/wahyd4/wahyd4.github.com.git
synced 2026-08-09 21:36:22 +10:00
Hermes Bot
232ecd7c22
- 308 posts reverse-extracted from wahyd4.github.com (Hexo 6.3.0 + NexT 8.25) - Hexo project with NexT theme, reading-experience custom styles - publish-post.sh: write post -> hexo build -> PR (master untouched)
159 lines
6.4 KiB
Markdown
159 lines
6.4 KiB
Markdown
---
|
||
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 进行展示。下面我将以为我本地的文件作为示例给大家展示效果和截图。
|
||
|
||
|
||
|
||
如图所示为 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` 的网页文件，添加如下内容:
|
||
|
||
```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 服务器，刷新页面。有没有觉得页面变得更加美观，漂亮了。
|
||
|
||
|
||
|
||
### 添加文档目录索引（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 文档了。
|
||
|
||
|
||
|
||
我们还可以试着访问下另外目录下的 Markdown 文件，可以看到所有 Markdown 文件都带有 TOC 和美观的样式了。
|
||
|
||
|
||
|
||
## 总结
|
||
|
||
所以，如果你不想把 Markdown文档放到 Github 或者使用 GitBook 来托管，可以试试这种方法，快速搭建一个基于 Caddy 服务器的 Markdown 文档的网站。
|