发现一件好东西：docsify ~ 将 markdown 文档链转成网站服务
本帖最后由 chunjiu 于 2022-11-11 16:53 编辑我一直用 markdown 写工作日志，也一直用 python 的 http.server 做 html 网页版的文件浏览、下载服务。
忽然发现 docsify 这个好东西 ~ 它真是个好东西：
提供转译，动态将 markdown 文档转换成 web 页面，并同时提供网页浏览服务（docsify-cli）。
这下不仅可以将我的日志直接做成私人的博客网站，而且不必劳烦去搞什么 httpd 服务器了。
它支持 markdown 里面的热链接，所以可以在 markdown 文档里面直接跳转。
只要将自己众多的 markdown 文档分层次梳理一下，就成了一个简单的日志网站，不需要掌握网页维护的众多繁琐知识。
使用插件可以支持 “美人鱼 - mermaid” 图形渲染，但在我的 Pi 上有点慢。
默认代码高亮的类型较少，需要自己添加脚本插件的链接。
资源需求和安装：
1、一个 linux 服务器，我用的是香橙派 zero 2（全志 H616，1GB RAM）；
2、插了一个 128GB 的凯侠 U 盘；
3、安装最新的 nodejs （v16+）；
4、用阿里源提供软件包（境外的慢到超时、无法安装，可能有些包被墙了）；
5、安装 docsify-cli 后初始化起始目录，并修改缺省的 README.md 文档作起始页面；
6、启动 docsify 服务，好了，可以看你的 markdown 网站了。
参考链接：
1. 官网，用来看介绍：https://docsify.js.org/#/
2. 安装最新的 nodejs： https://www.runoob.com/nodejs/nodejs-install-setup.html
3. 安装 docsify-cli：入坑 docsify，一款神奇的文档生成利器！
注意：阿里云的源今年换新了，旧地址已经作废，所以相关内容应该改成这样：
sudo npm install -g cnpm --registry=https://registry.npmmirror.com
# 然后安装
sudo cnpm i docsify-cli -g
4. 使用docsify 写开源文档+部署到云服务器
5. 官方插件和语法高亮部件介绍
6. 语法高亮可用的部件列表
PS:
参考 - 加快 js 加载的时间后，mermaid 渲染快多了！
PS 2：
最后不得已，还是把 js 文件全部搬回到本服务器上 ... 终于不卡了。 把所有文档写成md，然后用typora查看和编辑，最后统一在git上面管理，随时下载随时同步上去。简单明了啊。 本帖最后由 chunjiu 于 2022-11-11 12:01 编辑
kyq_linux 发表于 2022-11-11 11:58
把所有文档写成md，然后用typora查看和编辑，最后统一在git上面管理，随时下载随时同步上去。简单明了啊。 ...
(引用自2楼)
某些条件下不能使用云，而且以后的环境会越来越糟 ...
自己整服务器只是应对的策略之一。
PS：
抱歉哈，没说清楚。
我的日志不仅仅是技术方面的，还有给非技术人士看的内容 chunjiu 发表于 2022-11-11 11:59
某些条件下不能使用云，而且以后的环境会越来越糟 ...
自己整服务器只是应对的策略之一。 ...
(引用自3楼)
git云都没了，服务器的环境。。。 kyq_linux 发表于 2022-11-11 12:00
git云都没了，服务器的环境。。。
(引用自4楼)
只能靠自己架设了呀，各种 Pi 产品也真的很适时，便宜还蛮可靠。 本帖最后由 chunjiu 于 2022-11-11 13:53 编辑
我的日志也整理好了：
mermaid （“美人鱼”） 的渲染效果：
这种工具挺多的吧，习惯用mkdocs或者hugo yplin27 发表于 2022-11-11 16:15
这种工具挺多的吧，习惯用mkdocs或者hugo
(引用自7楼)
就目前来说，这个似乎是最简单的，捣鼓几下网站就搞好了。 谢谢分享，学习一下怎么使用 用notion写了好多些笔记，可以到处markdowna想做成网站分享，不知道这个可以支持不？ duxingkei 发表于 2022-11-11 22:53
用notion写了好多些笔记，可以到处markdowna想做成网站分享，不知道这个可以支持不？ ...
(引用自10楼)
只要是纯粹的 markdown 文本就没问题。
但如果有借 ``` 代码扩展的内容可能不支持，
例如，math 公式就暂时没支持。
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 yixin1851 发表于 2022-11-12 06:56
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 ...
(引用自12楼)
六楼的 pdf 就是 markdown 文档转来的。
好处是语法规则简单，内容层次清晰。
写日志的时候不影响思维过程，版面自动生成。
再次更新一个问题的解决方案：
内容摘要：
chunjiu 发表于 2022-11-12 07:14
六楼的 pdf 就是 markdown 文档转来的。
好处是语法规则简单，内容层次清晰。
(引用自13楼)
能否传几段你用MD写几句范文上来？ yixin1851 发表于 2022-11-12 11:10
能否传几段你用MD写几句范文上来？
(引用自15楼)
这个就是你楼上 pdf 文件中的 markdown 部分。
[]
## 超链接中的解析错误
由于 **markdown** 文本的链接语法总是被 `docsify-cli` 在路径的 “根” 后面插入 **“#”** ，所以下面的描述会被解析成：
```xml
# ".md" 文件中被错误解析的超链接
[平安夜歌 MP3](/.resource/00001.mp3)
# 错误的解析成：
#
# http://root/#/.resource/00001.mp3
```
此路径中的 **“#”** 会导致浏览器 **404** 错误，因为无法找到该文件。
**解决方案** 是在 `.md` 文档中直接使用 **`HTML`** 的超链接标签 **`<a href="..."> 超链接说明文本 </a>`** 来代替。请看下面的例子：
```xml
# 在 md 的文档中，改成下面的格式来超链接一个文件：
<a href="/.resource/总谱.pdf">总谱</a>
# 它会被正确的解析为：
#http://root/.resource/总谱.pdf
```
**注1：** 不用担心路径中的 unicode 字符和空格，它们会自动转成合格的 URL 语法。
**注2：** markdown 对自己的 `.md` 文件解析同样在路径中插入了 “#” 符号，但不会发生错误。
## 在文件系统中使用软连接 `ln -s xxx ./xxx`
在 `docsify-cli` 管理的目录里，允许对它之外的其它目录中文件进行软连接。
只要在操作系统中的 文件/目录 访问权限被允许，就不会对其读取操作造成阻碍。例如：
```
<a href="/.resource/总 谱.pdf" target="_blank">总谱（pdf）</a>
# 这儿的 '/.resource/总 谱.pdf' 是对一个其它目录下文件的软连接，例如：
#
# '总 谱.pdf' -> '../../Upload/Doc/分享类的资料（非系统化的文档）/新编赞美诗/71 -平安夜歌/71 平安夜-总谱.pdf'
```
## 附录 [《HTML超链接标签<a>》 ](http://m.biancheng.net/view/9387.html)
在 HTML 中，我们使用 `<a>` 标签来表示超链接。
超链接（Hyperlink）通常简称为链接（Link），是指从一个网页指向另一个目标的连接关系。
这个目标可以是另一个网页，也可以是当前网页中的其它位置，还可以是图片、文件、应用程序等。
链接的两端分别称为源锚点和目标锚点，通过点击源锚点即可以跳转到目标锚点。
超链接是网页中最常见的元素之一，整个互联网都是基于超链接而构建的。
网站由众多网页构成，超链接使得网页之间不再独立，它就像一根线，把网页连接在一起，形成一个网状结构。
互联网之所以能够称之为 “网”，就是因为有超链接的存在。
### `<a>` 标签的语法格式如下：
```xml
<a href="url"target="opentype">链接文本</a>
```
其中，**href** 属性用来指明要跳转到的 url，**target** 属性用来指明新页面的打开方式，链接文本需要写在 `<a>` 和 `</a>` 之间。
例如，链接到C语言中文网首页，并在浏览器新窗口中打开：
```xml
<a href="http://c.biancheng.net" target="_blank">C语言中文网</a>
```
它会链接到 HTML 教程的第一篇文章，并在当前窗口中打开：
```xml
<a href="http://c.biancheng.net/view/7410.html" target="_blank">网站到底是什么</a>
```
### href 属性
**href** 属性指定链接的目标，也就是要跳转到什么位置。href 可以有多种形式，例如：
- **href** 可以指向一个网页（.html、.php、.jsp、.asp 等格式），这也是最常见的形式，例如
`href="http://c.biancheng.net/view/1719.html"`
- **href** 可以指向图片（.jpg、.gif、.png 等格式）、音频（.mp3、.wav等格式）、视频（.mp4、.mkv格式）等媒体文件，例如
`href="/uploads/allimg/181221/134I32557-0.jpg"`
- **href** 可以指向压缩文件（.zip、.rar 等格式）、可执行程序（.exe）等，一些下载网站的链接就可以写成这种形式，例如
`href="./../uploads/data_package/ComputerFoundation.zip"`
- **href** 甚至还可以指向本机的文件，只是很少这样使用，例如
`href="D:/Program Files/360/360safe/360Safe.exe"`
所以 **href** 本质上就是指向一个文件，这个文件几乎可以是任意格式的。
如果浏览器支持这种格式，那么它就可以在浏览器上显示。比如常见的图片、音频、视频等，如果浏览器不支持这种格式，那么就提示用户下载。
另外，**href** 使用的路径可以是绝对路径，也可以是相对路径。
- 绝对路径往往以域名为起点，例如 `http://c.biancheng.net/view/1719.html`；
- 相对路径往往以当前文件或者当前域名为起点，例如`./../uploads/data_package/ComputerFoundation.zip`。
> 若对 URL 结构不了解的读者，请转到《绝对路径与相对路径》进行学习。
### target 属性
target 是可选属性，用来指明新页面的打开方式，默认情况下，新页面在当前浏览器窗口中打开。
但可以使用 **target** 属性来改变新页面的打开方式。常见的打开方式如下表所示：
| target | 属性值|
| ---- | ---- |
| 属性值 | 说明 |
| **_self** | 默认，在现有窗口中打开新页面，原窗口将被覆盖。 |
| **_blank** | 在新窗口中打开新页面，原窗口将被保留。 |
| **_parent** | 在当前框架的上一层打开新页面。 |
| **_top** | 在顶层框架中打开新页面。 |
绝大部分情况下，target 属性要么不写，保持默认的 _self，要么将它的值设置为 _blank，在新窗口中打开页面。例如：
```xml
<a href="http://c.biancheng.net/html/" target="_blank">HTML教程（新窗口打开）</a>
<a href="http://c.biancheng.net/css3/">CSS教程（当前窗口打开）</a>
```
### `<a>` 标签的默认样式
浏览器会为 **`<a>`** 标签设置一些默认样式。
- 鼠标样式
当鼠标移入链接区域时，会变成一只小手；当鼠标移出链接区域时，会变回箭头形状。
- 颜色及下划线
超链接被点击之前为蓝色，超链接被点击之后变成紫色。超链接默认带有下划线，下划线颜色和文本颜色保持一致。 本帖最后由 chunjiu 于 2022-11-12 12:46 编辑
yixin1851 发表于 2022-11-12 11:10
能否传几段你用MD写几句范文上来？
(引用自15楼)
这个是美人鱼的语法，它和 markdown 无关，只是在 md 文档中用扩展代码的形式交给 mermaid 引擎渲染的图形：
【参考 6 楼的图片】
```mermaid
flowchart TB
pps300a[]
pmcl[(<br/>PPS-300A<br/>项目管理处<br/>栏目)]
pmqa[(<br/>PPS-300A<br/>品质与工艺<br/>栏目)]
hwsp[(<br/>PPS-300A<br/>硬件子项目<br/>仓库)]
swsp[(<br/>PPS-300A<br/>软件子项目<br/>仓库)]
stsp[(<br/>PPS-300A<br/>结构子项目<br/>仓库)]
elsp[(<br/>PPS-300A<br/>电气子项目<br/>仓库)]
idsp[(<br/>PPS-300A<br/>工设子项目<br/>仓库)]
core[(<br/>PPS-300A<br/>核心资料中心<br/>仓库)]
coredocs>研发的非公开性<br/>资料存放在此处]
opendocs>项目的公开性资料<br/>与文档在此处查阅]
pps300a-->pmcl -.- opendocs
pps300a-->pmqa
pps300a-->core -.- coredocs
pps300a-->hwsp
pps300a-->swsp
pps300a-->stsp
pps300a-->elsp
pps300a-->idsp
```
```mermaid
stateDiagram-v2
state "从 Gitlab 服务器远程<br/>仓库中克隆所属子项目。" as gitlab
state "1、拉取远程的子项目内容来<br/>更新本地 Git 仓库。" as sp
state "2、日常对文档的编辑和更新，这是<br/>设计工作中需要的操作。" as edsp
state "3、当一个小阶段结束时，在提交之前先用 <br/>拉取操作 同步项目中其他成员编辑过的文档。" as pull
state "4、用 提交 和 提交日志 操作将自己编辑更<br/>新的文档内容存入本地 Git 仓库。" as submit
state "5、最后用 推送操作 将本地仓库中<br/>更新后的文档内容传输到 Gitlab <br/>服务器上的远程仓库中。" as push
state SubProject {
[*]-->sp
sp-->edsp
edsp-->pull
pull-->submit
submit-->push
push-->sp : 在第二天的工作开始<br/>前先来一次同步
}
gitlab-->SubProject
```
看来我对MD还是爱不起来 yixin1851 发表于 2022-11-12 19:55
看来我对MD还是爱不起来
(引用自18楼)
要能用上才能爱起来 {:lol:}
没啥帮助就自然不爱呀。 yixin1851 发表于 2022-11-12 06:56
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 ...
(引用自12楼)
可以简单地实现文档代码化，多人合作的文档，或者持续更新的文档用markdown可以很方便review与合并 yplin27 发表于 2022-11-13 00:01
可以简单地实现文档代码化，多人合作的文档，或者持续更新的文档用markdown可以很方便review与合并 ...
(引用自20楼)
我有些疑问，MD语法和正文混在一起，不会影响撰写者的思路吗？
万一哪天不记得语法了，岂不是很混乱？或者说把文字copy到非MD文档中，有语法的干扰岂不是很麻烦？ yixin1851 发表于 2022-11-12 06:56
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 ...
(引用自12楼)
你用typora所见就是所得，直接想写什么直接按快捷键就好，不需要理会语法；更关键得是可以导出其他各种格式文本，尤其是pdf，比其他开源类得md好多了 yixin1851 发表于 2022-11-14 22:49
我有些疑问，MD语法和正文混在一起，不会影响撰写者的思路吗？
万一哪天不记得语法了，岂不是很混乱？或 ...
(引用自21楼)
感觉不出来，常用就那几个标签，不行就用可视化工具 本帖最后由 chunjiu 于 2022-11-15 10:09 编辑
yixin1851 发表于 2022-11-14 22:49
我有些疑问，MD语法和正文混在一起，不会影响撰写者的思路吗？
万一哪天不记得语法了，岂不是很混乱？或 ...
(引用自21楼)
因为阅读者不是直接看 md 的原生文本啊……
你上 Github 之类的网站看一下，
所有的 md 格式已经被服务器渲染好了。
PS:
我上面例子内容比较复杂是因为之前团队成员跨域的比较多，
指导性的文件尽量先写的详细一点，免得大家产生歧义，
不然到了研发后期合并时，就不好收拾了。
所以一直到了现在，就养成了一种工作习惯。
本帖最后由 chunjiu 于 2022-11-27 08:12 编辑
在后续的测试中，发现 js 的加载时间比较影响页面的第一响应时间，所以准备将 js 库和字体库移到 ram 中。
昨天在查找 Linux 下的 RAM 虚拟盘工具时，发现 OrangePi 的 Ubuntu 版本已经内置了它，无需再装额外的软件。
系统使用 `/dev/shm` 作为对 RAM 盘（tmpfs）的引用，它的访问权限是 0777，意味着用户可以随意访问。
下面是针对此 RAM 盘的测试结果：
/dev/shm$ free
total used free sharedbuff/cache available
Mem: 983268 130668 428252 10208 424348 826772
Swap: 491632 0 491632
/dev/shm$ ls -al
total 0
drwxrwxrwt2 root root 40 Sep8 17:58 .
drwxr-xr-x 15 root root 3840 Nov 26 09:59 ..
/dev/shm$ sudo dd if=/dev/zero of=testfile bs=1M count=200
200+0 records in
200+0 records out
209715200 bytes (210 MB, 200 MiB) copied, 0.5562 s, 377 MB/s
/dev/shm$ ls -al
total 204800
drwxrwxrwt2 root root 60 Nov 27 07:39 .
drwxr-xr-x 15 root root 3840 Nov 26 09:59 ..
-rw-r--r--1 root root 209715200 Nov 27 07:39 testfile
/dev/shm$ free
total used free sharedbuff/cache available
Mem: 983268 130484 223332 215008 629452 622156
Swap: 491632 0 491632
经过测试，可以发现，此目录下的文件使用 RAM 中的 shared 空间，同时，访问速度是 377 MB/s，
而普通 U 盘经过测试只有 13 MB/s 左右，TF 卡也只有 18 MB/s 左右。
所以，将 docsify 网站的 js 和 字库挪到 `/dev/shm` 下应该可以大幅提升 docsify 的第一次页面加载速度。
但是它在每次关机和掉电后会丢失，所以需要做一个启动加载任务在系统每次启动时，从 U 盘复制到该目录下即可。
页:
[1]