发现一件好东西：docsify ~ 将 markdown 文档链转成网站服务

chunjiu

我一直用 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，一款神奇的文档生成利器！

  注意：阿里云的源今年换新了，旧地址已经作废，所以相关内容应该改成这样：

1. sudo npm install -g cnpm --registry=https://registry.npmmirror.com
   
2. # 然后安装
   
3. sudo cnpm i docsify-cli -g

复制代码

4. 使用docsify 写开源文档+部署到云服务器

5. 官方插件和语法高亮部件介绍

6. 语法高亮可用的部件列表

PS:

参考 - 加快 js 加载的时间后，mermaid 渲染快多了！

PS 2：

最后不得已，还是把 js 文件全部搬回到本服务器上 ... 终于不卡了。

kyq_linux

把所有文档写成md，然后用typora查看和编辑，最后统一在git上面管理，随时下载随时同步上去。简单明了啊。

chunjiu

kyq_linux 发表于 2022-11-11 11:58
把所有文档写成md，然后用typora查看和编辑，最后统一在git上面管理，随时下载随时同步上去。简单明了啊。 ...
(引用自2楼)

某些条件下不能使用云，而且以后的环境会越来越糟 ...

自己整服务器只是应对的策略之一。

PS：

抱歉哈，没说清楚。

我的日志不仅仅是技术方面的，还有给非技术人士看的内容

kyq_linux

chunjiu 发表于 2022-11-11 11:59
某些条件下不能使用云，而且以后的环境会越来越糟 ...

自己整服务器只是应对的策略之一。 ...
(引用自3楼)

git云都没了，服务器的环境。。。

chunjiu

kyq_linux 发表于 2022-11-11 12:00
git云都没了，服务器的环境。。。
(引用自4楼)

只能靠自己架设了呀，各种 Pi 产品也真的很适时，便宜还蛮可靠。

chunjiu

我的日志也整理好了：





mermaid （“美人鱼”） 的渲染效果：

yplin27

这种工具挺多的吧，习惯用mkdocs或者hugo

chunjiu

yplin27 发表于 2022-11-11 16:15
这种工具挺多的吧，习惯用mkdocs或者hugo
(引用自7楼)

就目前来说，这个似乎是最简单的，捣鼓几下网站就搞好了。

我是一个大白菜

谢谢分享，学习一下怎么使用

duxingkei

用notion写了好多些笔记，可以到处markdowna想做成网站分享，不知道这个可以支持不？

chunjiu

duxingkei 发表于 2022-11-11 22:53
用notion写了好多些笔记，可以到处markdowna想做成网站分享，不知道这个可以支持不？ ...
(引用自10楼)

只要是纯粹的 markdown 文本就没问题。

但如果有借 ``` 代码扩展的内容可能不支持，

例如，math 公式就暂时没支持。

yixin1851

Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。

chunjiu

yixin1851 发表于 2022-11-12 06:56
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 ...
(引用自12楼)

六楼的 pdf 就是 markdown 文档转来的。

好处是语法规则简单，内容层次清晰。

写日志的时候不影响思维过程，版面自动生成。

chunjiu

再次更新一个问题的解决方案：



内容摘要：

yixin1851

chunjiu 发表于 2022-11-12 07:14
六楼的 pdf 就是 markdown 文档转来的。

好处是语法规则简单，内容层次清晰。
(引用自13楼)

能否传几段你用MD写几句范文上来？

chunjiu

yixin1851 发表于 2022-11-12 11:10
能否传几段你用MD写几句范文上来？
(引用自15楼)

这个就是你楼上 pdf 文件中的 markdown 部分。

1. [[_TOC_]]
   
2. 
   
3. ## 超链接中的解析错误
   
4. 
   
5. 由于 **markdown** 文本的链接语法总是被 `docsify-cli` 在路径的 “根” 后面插入 **“#”** ，所以下面的描述会被解析成：  
   
6. 
   
7. ```xml
   
8. # ".md" 文件中被错误解析的超链接
   
9. 
   
10. [平安夜歌 MP3](/.resource/00001.mp3)
    
11. 
    
12. # 错误的解析成：
    
13. #
    
14. # http://root/#/.resource/00001.mp3
    
15. ```
    
16. 
    
17. 此路径中的 **“#”** 会导致浏览器 **404** 错误，因为无法找到该文件。
    
18. 
    
19. **解决方案** 是在 `.md` 文档中直接使用 **`HTML`** 的超链接标签 **`<a href="..."> 超链接说明文本 </a>`** 来代替。请看下面的例子：
    
20. 
    
21. ```xml
    
22. # 在 md 的文档中，改成下面的格式来超链接一个文件：
    
23. 
    
24. <a href="/.resource/总谱.pdf">总谱</a>
    
25. 
    
26. # 它会被正确的解析为：
    
27. 
    
28. #  http://root/.resource/总谱.pdf
    
29. ```
    
30. 
    
31. **注1：** 不用担心路径中的 unicode 字符和空格，它们会自动转成合格的 URL 语法。
    
32.   
    
33. **注2：** markdown 对自己的 `.md` 文件解析同样在路径中插入了 “#” 符号，但不会发生错误。
    
34. 
    
35. ## 在文件系统中使用软连接 `ln -s xxx ./xxx`
    
36. 
    
37. 在 `docsify-cli` 管理的目录里，允许对它之外的其它目录中文件进行软连接。
    
38. 
    
39. 只要在操作系统中的 文件/目录 访问权限被允许，就不会对其读取操作造成阻碍。例如：
    
40. 
    
41. ```
    
42. <a href="/.resource/总 谱.pdf" target="_blank">总谱（pdf）</a>
    
43. 
    
44. # 这儿的 '/.resource/总 谱.pdf' 是对一个其它目录下文件的软连接，例如：
    
45. #
    
46. # '总 谱.pdf' -> '../../Upload/Doc/分享类的资料（非系统化的文档）/新编赞美诗/71 -  平安夜歌/71 平安夜-总谱.pdf'
    
47. ```
    
48. 
    
49. ## 附录 [《HTML超链接标签<a>》 ](http://m.biancheng.net/view/9387.html)
    
50. 
    
51. 在 HTML 中，我们使用 `<a>` 标签来表示超链接。
    
52. 
    
53. 超链接（Hyperlink）通常简称为链接（Link），是指从一个网页指向另一个目标的连接关系。
    
54. 
    
55. 这个目标可以是另一个网页，也可以是当前网页中的其它位置，还可以是图片、文件、应用程序等。
    
56. 
    
57. 链接的两端分别称为源锚点和目标锚点，通过点击源锚点即可以跳转到目标锚点。
    
58. 
    
59. 超链接是网页中最常见的元素之一，整个互联网都是基于超链接而构建的。
    
60. 
    
61. 网站由众多网页构成，超链接使得网页之间不再独立，它就像一根线，把网页连接在一起，形成一个网状结构。
    
62. 
    
63. 互联网之所以能够称之为 “网”，就是因为有超链接的存在。
    
64. 
    
65. ### `<a>` 标签的语法格式如下：
    
66. 
    
67. ```xml
    
68. <a href="url"  target="opentype">链接文本</a>
    
69. ```
    
70. 
    
71. 其中，**href** 属性用来指明要跳转到的 url，**target** 属性用来指明新页面的打开方式，链接文本需要写在 `<a>` 和 `</a>` 之间。
    
72. 
    
73. 例如，链接到C语言中文网首页，并在浏览器新窗口中打开：
    
74. 
    
75. ```xml
    
76. <a href="http://c.biancheng.net" target="_blank">C语言中文网</a>
    
77. ```
    
78. 
    
79. 它会链接到 HTML 教程的第一篇文章，并在当前窗口中打开：
    
80. 
    
81. ```xml
    
82. <a href="http://c.biancheng.net/view/7410.html" target="_blank">网站到底是什么</a>
    
83. ```
    
84. 
    
85. ### href 属性
    
86. 
    
87. **href** 属性指定链接的目标，也就是要跳转到什么位置。href 可以有多种形式，例如：
    
88. 
    
89. - **href** 可以指向一个网页（.html、.php、.jsp、.asp 等格式），这也是最常见的形式，例如  
    
90.   
    
91.   `href="http://c.biancheng.net/view/1719.html"`  
    
92. 
    
93. - **href** 可以指向图片（.jpg、.gif、.png 等格式）、音频（.mp3、.wav等格式）、视频（.mp4、.mkv格式）等媒体文件，例如  
    
94.   
    
95.   `href="/uploads/allimg/181221/134I32557-0.jpg"`
    
96. 
    
97. - **href** 可以指向压缩文件（.zip、.rar 等格式）、可执行程序（.exe）等，一些下载网站的链接就可以写成这种形式，例如
    
98.   
    
99.   `href="./../uploads/data_package/ComputerFoundation.zip"`
    
100. 
     
101. - **href** 甚至还可以指向本机的文件，只是很少这样使用，例如
     
102.    
     
103.   `href="D:/Program Files/360/360safe/360Safe.exe"`
     
104. 
     
105. 所以 **href** 本质上就是指向一个文件，这个文件几乎可以是任意格式的。
     
106. 
     
107. 如果浏览器支持这种格式，那么它就可以在浏览器上显示。比如常见的图片、音频、视频等，如果浏览器不支持这种格式，那么就提示用户下载。
     
108. 
     
109. 另外，**href** 使用的路径可以是绝对路径，也可以是相对路径。
     
110. 
     
111. - 绝对路径往往以域名为起点，例如 `http://c.biancheng.net/view/1719.html`；
     
112.   
     
113. - 相对路径往往以当前文件或者当前域名为起点，例如  `./../uploads/data_package/ComputerFoundation.zip`。
     
114. 
     
115. > 若对 URL 结构不了解的读者，请转到《绝对路径与相对路径》进行学习。
     
116. 
     
117. ### target 属性
     
118. 
     
119. target 是可选属性，用来指明新页面的打开方式，默认情况下，新页面在当前浏览器窗口中打开。
     
120. 
     
121. 但可以使用 **target** 属性来改变新页面的打开方式。常见的打开方式如下表所示：
     
122. 
     
123. | target | 属性值  |
     
124. | ---- | ---- |
     
125. | 属性值         | 说明 |  
     
126. | **_self** |        默认，在现有窗口中打开新页面，原窗口将被覆盖。 |  
     
127. | **_blank** |        在新窗口中打开新页面，原窗口将被保留。 |  
     
128. | **_parent** |        在当前框架的上一层打开新页面。 |  
     
129. | **_top** |        在顶层框架中打开新页面。 |  
     
130. 
     
131. 绝大部分情况下，target 属性要么不写，保持默认的 _self，要么将它的值设置为 _blank，在新窗口中打开页面。例如：  
     
132. 
     
133. ```xml
     
134. <a href="http://c.biancheng.net/html/" target="_blank">HTML教程（新窗口打开）</a>
     
135. <a href="http://c.biancheng.net/css3/">CSS教程（当前窗口打开）</a>
     
136. ```
     
137. 
     
138. ### `<a>` 标签的默认样式
     
139. 
     
140. 浏览器会为 **`<a>`** 标签设置一些默认样式。
     
141. 
     
142. - 鼠标样式
     
143.   
     
144.   当鼠标移入链接区域时，会变成一只小手；当鼠标移出链接区域时，会变回箭头形状。
     
145. 
     
146. - 颜色及下划线
     
147.   
     
148.   超链接被点击之前为蓝色，超链接被点击之后变成紫色。超链接默认带有下划线，下划线颜色和文本颜色保持一致。

复制代码

chunjiu

yixin1851 发表于 2022-11-12 11:10
能否传几段你用MD写几句范文上来？
(引用自15楼)

这个是美人鱼的语法，它和 markdown 无关，只是在 md 文档中用扩展代码的形式交给 mermaid 引擎渲染的图形：

【参考 6 楼的图片】

1. ```mermaid
   
2. flowchart TB
   
3.   pps300a[[Gitlab 服务器<br/> PPS-300A 项目组 <br/>远程仓库组]]
   
4.   pmcl[(<br/>PPS-300A<br/>项目管理处<br/>栏目)]
   
5.   pmqa[(<br/>PPS-300A<br/>品质与工艺<br/>栏目)]
   
6.   hwsp[(<br/>PPS-300A<br/>硬件子项目<br/>仓库)]
   
7.   swsp[(<br/>PPS-300A<br/>软件子项目<br/>仓库)]
   
8.   stsp[(<br/>PPS-300A<br/>结构子项目<br/>仓库)]
   
9.   elsp[(<br/>PPS-300A<br/>电气子项目<br/>仓库)]
   
10.   idsp[(<br/>PPS-300A<br/>工设子项目<br/>仓库)]
    
11.   core[(<br/>PPS-300A<br/>核心资料中心<br/>仓库)]  
    
12.   coredocs>研发的非公开性<br/>资料存放在此处]  
    
13.   opendocs>项目的公开性资料<br/>与文档在此处查阅]
    
14.   
    
15.   pps300a-->pmcl -.- opendocs
    
16.   pps300a-->pmqa
    
17.   pps300a-->core -.- coredocs
    
18.   pps300a-->hwsp
    
19.   pps300a-->swsp
    
20.   pps300a-->stsp
    
21.   pps300a-->elsp
    
22.   pps300a-->idsp
    
23. ```

复制代码

1. ```mermaid
   
2. stateDiagram-v2
   
3.   state "从 Gitlab 服务器远程<br/>仓库中克隆所属子项目。" as gitlab
   
4.   state "1、拉取远程的子项目内容来<br/>更新本地 Git 仓库。" as sp
   
5.   state "2、日常对文档的编辑和更新，这是<br/>设计工作中需要的操作。" as edsp
   
6.   state "3、当一个小阶段结束时，在提交之前先用 <br/>  拉取操作 同步项目中其他成员编辑过的文档。" as pull
   
7.   state "4、用 提交 和 提交日志 操作将自己编辑更<br/>新的文档内容存入本地 Git 仓库。" as submit
   
8.   state "5、最后用 推送操作 将本地仓库中<br/>更新后的文档内容传输到 Gitlab <br/>服务器上的远程仓库中。" as push
   
9. 
   
10.   state SubProject {
    
11.     [*]-->sp
    
12.     sp-->edsp
    
13.     edsp-->pull
    
14.     pull-->submit
    
15.     submit-->push
    
16.     push-->sp : 在第二天的工作开始<br/>前先来一次同步
    
17. }
    
18. gitlab-->SubProject
    
19.   
    
20. ```

复制代码

yixin1851

看来我对MD还是爱不起来

chunjiu

yixin1851 发表于 2022-11-12 19:55
看来我对MD还是爱不起来
(引用自18楼)

要能用上才能爱起来

没啥帮助就自然不爱呀。

yplin27

yixin1851 发表于 2022-11-12 06:56
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 ...
(引用自12楼)

可以简单地实现文档代码化，多人合作的文档，或者持续更新的文档用markdown可以很方便review与合并

yixin1851

yplin27 发表于 2022-11-13 00:01
可以简单地实现文档代码化，多人合作的文档，或者持续更新的文档用markdown可以很方便review与合并 ...
(引用自20楼)

我有些疑问，MD语法和正文混在一起，不会影响撰写者的思路吗？
万一哪天不记得语法了，岂不是很混乱？或者说把文字copy到非MD文档中，有语法的干扰岂不是很麻烦？

zstu2012

yixin1851 发表于 2022-11-12 06:56
Md文本的好处，我始终体会不到。每次还要敲md语法，总感觉麻烦，就放弃了Md。 ...
(引用自12楼)

你用typora所见就是所得，直接想写什么直接按快捷键就好，不需要理会语法；更关键得是可以导出其他各种格式文本，尤其是pdf，比其他开源类得md好多了

yplin27

yixin1851 发表于 2022-11-14 22:49
我有些疑问，MD语法和正文混在一起，不会影响撰写者的思路吗？
万一哪天不记得语法了，岂不是很混乱？或 ...
(引用自21楼)

感觉不出来，常用就那几个标签，不行就用可视化工具

chunjiu

yixin1851 发表于 2022-11-14 22:49
我有些疑问，MD语法和正文混在一起，不会影响撰写者的思路吗？
万一哪天不记得语法了，岂不是很混乱？或 ...
(引用自21楼)

因为阅读者不是直接看 md 的原生文本啊……

你上 Github 之类的网站看一下，

所有的 md 格式已经被服务器渲染好了。

PS:

我上面例子内容比较复杂是因为之前团队成员跨域的比较多，

指导性的文件尽量先写的详细一点，免得大家产生歧义，

不然到了研发后期合并时，就不好收拾了。

所以一直到了现在，就养成了一种工作习惯。

chunjiu

在后续的测试中，发现 js 的加载时间比较影响页面的第一响应时间，所以准备将 js 库和字体库移到 ram 中。


昨天在查找 Linux 下的 RAM 虚拟盘工具时，发现 OrangePi 的 Ubuntu 版本已经内置了它，无需再装额外的软件。

系统使用 `/dev/shm` 作为对 RAM 盘（tmpfs）的引用，它的访问权限是 0777，意味着用户可以随意访问。

下面是针对此 RAM 盘的测试结果：

1. /dev/shm$ free
   
2.               total        used        free      shared  buff/cache   available
   
3. Mem:         983268      130668      428252       10208      424348      826772
   
4. Swap:        491632           0      491632
   
5. 
   
6. /dev/shm$ ls -al
   
7. total 0
   
8. drwxrwxrwt  2 root root   40 Sep  8 17:58 .
   
9. drwxr-xr-x 15 root root 3840 Nov 26 09:59 ..
   
10. 
    
11. /dev/shm$ sudo dd if=/dev/zero of=testfile bs=1M count=200
    
12. 200+0 records in
    
13. 200+0 records out
    
14. 209715200 bytes (210 MB, 200 MiB) copied, 0.5562 s, 377 MB/s
    
15. 
    
16. /dev/shm$ ls -al
    
17. total 204800
    
18. drwxrwxrwt  2 root root        60 Nov 27 07:39 .
    
19. drwxr-xr-x 15 root root      3840 Nov 26 09:59 ..
    
20. -rw-r--r--  1 root root 209715200 Nov 27 07:39 testfile
    
21. 
    
22. /dev/shm$ free
    
23.               total        used        free      shared  buff/cache   available
    
24. Mem:         983268      130484      223332      215008      629452      622156
    
25. Swap:        491632           0      491632

复制代码

经过测试，可以发现，此目录下的文件使用 RAM 中的 shared 空间，同时，访问速度是 377 MB/s，

而普通 U 盘经过测试只有 13 MB/s 左右，TF 卡也只有 18 MB/s 左右。

所以，将 docsify 网站的 js 和 字库挪到 `/dev/shm` 下应该可以大幅提升 docsify 的第一次页面加载速度。

但是它在每次关机和掉电后会丢失，所以需要做一个启动加载任务在系统每次启动时，从 U 盘复制到该目录下即可。