Add highlight extension

3.3. 代码高亮.md

@@ -0,0 +1,93 @@
+# 代码高亮
+
+## 使用 gitbook 默认高亮
+
+对于大多数被广泛使用的语言，无需做任何配置，在 markdown 中插入代码块就行。
+
+但是如果你要插入一种未被支持的语言，代码块就没有任何高亮，看起来比较丑。
+
+下面给出我的一种解决方案：
+
+## 使用 prism 插件
+
+禁用 ``gitbook`` 默认高亮并使用 ``prism`` 高亮插件：
+
+```json
+// book.json
+{
+    "plugins": [
+        "-highlight",
+        "prism"
+    ],
+    "pluginsConfig": {
+        "prism": {
+            // 设置个人比较喜欢的暗色调主题
+            // 可以去同目录下找更多的主题
+            "css": ["prismjs/themes/prism-tomorrom.css"]
+        }
+    }
+}
+```
+
+随后通过 ``gitbook install`` 安装插件。
+
+最后 ``gitbook build`` 就可以看到效果了。
+
+## 添加自己的语言支持
+
+在安装 ``prism`` 插件后，我们可以看一下 ``node_modules/prismjs/components`` 文件夹，里面包含了目前可用的所有语言支持。比如说有一个 ``prism-c.js`` ，那么就表明支持 ``C`` 语言。
+
+下面以我支持 ``riscv`` 汇编高亮的流程来举例说明一下：
+
+1. 写一个 ``prism-riscv.js`` 并复制到 ``components`` 文件夹下，可在[这里](https://github.com/wyfcyx/rCore_tutorial_doc/blob/master/prism-riscv.js)找到。
+   这里面只进行简单的词法分析，使用一个正则表达式 ``pattern`` 来匹配一种词，并使用别名 ``alias`` 来描述这种词的类型，其实也就是决定最后渲染出来这种词的颜色。
+
+   我这里大概就是寄存器一种颜色，指令一种颜色，伪指令一种颜色。对于汇编语言这也就够了。
+
+   然而 ``prism`` 还支持更高级一点的[语法分析](https://prismjs.com/extending.html#language-definitions)。
+
+2. 将你的语言注册到 ``node_modules/prismjs/components.json``。
+
+   打开看一下，就是在 ``languages`` 插入一个描述你的语言的贡献者和名字的键值对。
+
+   我的代码如下：
+
+```python
+# add_riscv_component.py
+
+import json
+
+json_path = 'node_modules/prismjs/components.json'
+
+data = json.load(open(json_path))
+data['languages']['riscv'] = {'title': 'RISC-V', 'owner': 'shinbokuow2'}
+with open(json_path, 'w') as f:
+f.write(json.dumps(data, sort_keys = True, indent = 4))
+```
+
+如果只是自己用的话这就够了，想要为 prism 社区做贡献的参考[这里](https://prismjs.com/extending.html#creating-a-new-language-definition)。
+
+在 ``gitbook build`` 之前做完上面两步，``build`` 之后你会发现 riscv 代码块被正确高亮了！
+
+## 行内代码
+
+gitbook 默认的行内代码和普通字体是一个颜色，我们希望它在灰色背景的同时字体变为红色，更加显眼。
+
+我的做法是在 ``gitbook build`` 之后直接暴力改生成的 ``css`` 。这个 ``css`` 放在 ``docs/gitbook/style.css``。（``build`` 之后的结果本来应该放在 ``_book`` 文件夹下，为了套用 Github Page 将其重命名为 ``docs``）
+
+```python
+# add_code_style.py
+
+s = open('docs/gitbook/style.css').read()
+code = 'markdown-section code{'
+color_red = 'color:#bf616a;'
+code_in_pre = 'markdown-section pre>code{'
+color_inherit = 'color:#ccc;'
+s = s.replace(code, code + color_red)
+s = s.replace(code_in_pre, code_in_pre + color_inherit)
+with open('docs/gitbook/style.css', 'w') as f:
+    f.write(s)
+```
+
+
+

4. 部署网页.md

@@ -36,6 +36,7 @@ cd ..
 rm -rf docs
 gitbook build
 mv _book docs
+python3 add_code_style.py
 cd docs
 rm update_book.sh
 rm .gitignore

README.md

@@ -1,6 +1,6 @@
 # build web doc
 
-用于构建含评论区（与 GitHub issue 关联）的 GitHun Page 的教程，文档已通过网页形式部署于：https://xy-plus.github.io/webdoc/
+用于构建含评论区（与 GitHub issue 关联）的 GitHub Page 的教程，文档已通过网页形式部署于：https://xy-plus.github.io/webdoc/
 
 ## 快速构建
 

SUMMARY.md

@@ -5,4 +5,5 @@
 - [3. 添加插件](3. 添加插件.md)
   - [3.1. 参考配置](3.1. 参考配置.md)
   - [3.2. 评论区](3.2. 评论区.md)
+  - [3.3. 代码高亮](3.3. 代码高亮.md)
 - [4. 部署网页](4. 部署网页.md)

add_code_style.py

@@ -0,0 +1,10 @@
+s = open('docs/gitbook/style.css').read()
+code = 'markdown-section code{'
+color_red = 'color:#bf616a;'
+code_in_pre = 'markdown-section pre>code{'
+color_inherit = 'color:#ccc;'
+s = s.replace(code, code + color_red)
+s = s.replace(code_in_pre, code_in_pre + color_inherit)
+with open('docs/gitbook/style.css', 'w') as f:
+    f.write(s)
+

book.json

@@ -6,15 +6,20 @@
     "github",
     "localized-footer",
     "ancre-navigation",
-    "-sharing"
+    "-sharing",
+	"-highlight",
+	"prism"
   ],
   "pluginsConfig": {
     "github": {
       "url": "https://github.com/xy-plus/webdoc"
     },
     "localized-footer": {
       "filename": "gitbook/comment.html"
-    }
+    },
+	"prism": {
+	  "css": ["prismjs/themes/prism-tomorrow.css"]
+	}
   },
   "styles": {
     "website": "gitbook/website.css"

docs/1. 编写文档.html

@@ -33,7 +33,7 @@
 
 
 
-                <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
+                <link rel="stylesheet" href="gitbook/gitbook-plugin-prism/prism-tomorrow.css">
 
 
 
@@ -174,6 +174,19 @@
 
 
 
+        </li>
+
+        <li class="chapter " data-level="1.4.3" data-path="3.3. 代码高亮.html">
+
+                <a href="3.3. 代码高亮.html">
+
+
+                    3.3. 代码高亮
+
+                </a>
+
+
+
         </li>
 
 
@@ -336,7 +349,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
     <script>
         var gitbook = gitbook || [];
         gitbook.push(function() {
-            gitbook.page.hasChanged({"page":{"title":"1. 编写文档","level":"1.2","depth":1,"next":{"title":"2. 本地浏览","level":"1.3","depth":1,"path":"2. 本地浏览.md","ref":"2. 本地浏览.md","articles":[]},"previous":{"title":"Introduction","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":["chapter-fold","code","search-pro","github","localized-footer","ancre-navigation","-sharing"],"pluginsConfig":{"chapter-fold":{},"github":{"url":"https://github.com/xy-plus/webdoc"},"search-pro":{},"search":{},"localized-footer":{"filename":"gitbook/comment.html","hline":"true"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"code":{"copyButtons":true},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"ancre-navigation":{"associatedWithSummary":true,"float":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"mode":"float","multipleH1":true,"pageTop":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"printLog":false,"showLevel":true},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"gitbook/website.css"}},"file":{"path":"1. 编写文档.md","mtime":"2019-10-09T10:19:37.106Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-10-29T07:41:31.237Z"},"basePath":".","book":{"language":""}});
+            gitbook.page.hasChanged({"page":{"title":"1. 编写文档","level":"1.2","depth":1,"next":{"title":"2. 本地浏览","level":"1.3","depth":1,"path":"2. 本地浏览.md","ref":"2. 本地浏览.md","articles":[]},"previous":{"title":"Introduction","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":["chapter-fold","code","search-pro","github","localized-footer","ancre-navigation","-sharing","-highlight","prism"],"pluginsConfig":{"chapter-fold":{},"prism":{"css":["prismjs/themes/prism-tomorrow.css"]},"github":{"url":"https://github.com/xy-plus/webdoc"},"search-pro":{},"search":{},"localized-footer":{"filename":"gitbook/comment.html","hline":"true"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"code":{"copyButtons":true},"fontsettings":{"theme":"white","family":"sans","size":2},"ancre-navigation":{"associatedWithSummary":true,"float":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"mode":"float","multipleH1":true,"pageTop":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"printLog":false,"showLevel":true},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"gitbook/website.css"}},"file":{"path":"1. 编写文档.md","mtime":"2019-12-06T15:54:29.937Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-12-06T17:25:00.849Z"},"basePath":".","book":{"language":""}});
         });
     </script>
 </div>

docs/2. 本地浏览.html

@@ -33,7 +33,7 @@
 
 
 
-                <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
+                <link rel="stylesheet" href="gitbook/gitbook-plugin-prism/prism-tomorrow.css">
 
 
 
@@ -174,6 +174,19 @@
 
 
 
+        </li>
+
+        <li class="chapter " data-level="1.4.3" data-path="3.3. 代码高亮.html">
+
+                <a href="3.3. 代码高亮.html">
+
+
+                    3.3. 代码高亮
+
+                </a>
+
+
+
         </li>
 
 
@@ -339,7 +352,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
     <script>
         var gitbook = gitbook || [];
         gitbook.push(function() {
-            gitbook.page.hasChanged({"page":{"title":"2. 本地浏览","level":"1.3","depth":1,"next":{"title":"3. 添加插件","level":"1.4","depth":1,"path":"3. 添加插件.md","ref":"3. 添加插件.md","articles":[{"title":"3.1. 参考配置","level":"1.4.1","depth":2,"path":"3.1. 参考配置.md","ref":"3.1. 参考配置.md","articles":[]},{"title":"3.2. 评论区","level":"1.4.2","depth":2,"path":"3.2. 评论区.md","ref":"3.2. 评论区.md","articles":[]}]},"previous":{"title":"1. 编写文档","level":"1.2","depth":1,"path":"1. 编写文档.md","ref":"1. 编写文档.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":["chapter-fold","code","search-pro","github","localized-footer","ancre-navigation","-sharing"],"pluginsConfig":{"chapter-fold":{},"github":{"url":"https://github.com/xy-plus/webdoc"},"search-pro":{},"search":{},"localized-footer":{"filename":"gitbook/comment.html","hline":"true"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"code":{"copyButtons":true},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"ancre-navigation":{"associatedWithSummary":true,"float":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"mode":"float","multipleH1":true,"pageTop":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"printLog":false,"showLevel":true},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"gitbook/website.css"}},"file":{"path":"2. 本地浏览.md","mtime":"2019-10-09T09:43:01.447Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-10-29T07:41:31.237Z"},"basePath":".","book":{"language":""}});
+            gitbook.page.hasChanged({"page":{"title":"2. 本地浏览","level":"1.3","depth":1,"next":{"title":"3. 添加插件","level":"1.4","depth":1,"path":"3. 添加插件.md","ref":"3. 添加插件.md","articles":[{"title":"3.1. 参考配置","level":"1.4.1","depth":2,"path":"3.1. 参考配置.md","ref":"3.1. 参考配置.md","articles":[]},{"title":"3.2. 评论区","level":"1.4.2","depth":2,"path":"3.2. 评论区.md","ref":"3.2. 评论区.md","articles":[]},{"title":"3.3. 代码高亮","level":"1.4.3","depth":2,"path":"3.3. 代码高亮.md","ref":"3.3. 代码高亮.md","articles":[]}]},"previous":{"title":"1. 编写文档","level":"1.2","depth":1,"path":"1. 编写文档.md","ref":"1. 编写文档.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":["chapter-fold","code","search-pro","github","localized-footer","ancre-navigation","-sharing","-highlight","prism"],"pluginsConfig":{"chapter-fold":{},"prism":{"css":["prismjs/themes/prism-tomorrow.css"]},"github":{"url":"https://github.com/xy-plus/webdoc"},"search-pro":{},"search":{},"localized-footer":{"filename":"gitbook/comment.html","hline":"true"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"code":{"copyButtons":true},"fontsettings":{"theme":"white","family":"sans","size":2},"ancre-navigation":{"associatedWithSummary":true,"float":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"mode":"float","multipleH1":true,"pageTop":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"printLog":false,"showLevel":true},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"gitbook/website.css"}},"file":{"path":"2. 本地浏览.md","mtime":"2019-12-06T15:54:29.937Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-12-06T17:25:00.849Z"},"basePath":".","book":{"language":""}});
         });
     </script>
 </div>

docs/3. 添加插件.html

@@ -33,7 +33,7 @@
 
 
 
-                <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
+                <link rel="stylesheet" href="gitbook/gitbook-plugin-prism/prism-tomorrow.css">
 
 
 
@@ -174,6 +174,19 @@
 
 
 
+        </li>
+
+        <li class="chapter " data-level="1.4.3" data-path="3.3. 代码高亮.html">
+
+                <a href="3.3. 代码高亮.html">
+
+
+                    3.3. 代码高亮
+
+                </a>
+
+
+
         </li>
 
 
@@ -336,7 +349,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
     <script>
         var gitbook = gitbook || [];
         gitbook.push(function() {
-            gitbook.page.hasChanged({"page":{"title":"3. 添加插件","level":"1.4","depth":1,"next":{"title":"3.1. 参考配置","level":"1.4.1","depth":2,"path":"3.1. 参考配置.md","ref":"3.1. 参考配置.md","articles":[]},"previous":{"title":"2. 本地浏览","level":"1.3","depth":1,"path":"2. 本地浏览.md","ref":"2. 本地浏览.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":["chapter-fold","code","search-pro","github","localized-footer","ancre-navigation","-sharing"],"pluginsConfig":{"chapter-fold":{},"github":{"url":"https://github.com/xy-plus/webdoc"},"search-pro":{},"search":{},"localized-footer":{"filename":"gitbook/comment.html","hline":"true"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"code":{"copyButtons":true},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"ancre-navigation":{"associatedWithSummary":true,"float":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"mode":"float","multipleH1":true,"pageTop":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"printLog":false,"showLevel":true},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"gitbook/website.css"}},"file":{"path":"3. 添加插件.md","mtime":"2019-10-09T10:30:50.269Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-10-29T07:41:31.237Z"},"basePath":".","book":{"language":""}});
+            gitbook.page.hasChanged({"page":{"title":"3. 添加插件","level":"1.4","depth":1,"next":{"title":"3.1. 参考配置","level":"1.4.1","depth":2,"path":"3.1. 参考配置.md","ref":"3.1. 参考配置.md","articles":[]},"previous":{"title":"2. 本地浏览","level":"1.3","depth":1,"path":"2. 本地浏览.md","ref":"2. 本地浏览.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":["chapter-fold","code","search-pro","github","localized-footer","ancre-navigation","-sharing","-highlight","prism"],"pluginsConfig":{"chapter-fold":{},"prism":{"css":["prismjs/themes/prism-tomorrow.css"]},"github":{"url":"https://github.com/xy-plus/webdoc"},"search-pro":{},"search":{},"localized-footer":{"filename":"gitbook/comment.html","hline":"true"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"code":{"copyButtons":true},"fontsettings":{"theme":"white","family":"sans","size":2},"ancre-navigation":{"associatedWithSummary":true,"float":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"mode":"float","multipleH1":true,"pageTop":{"level1Icon":"","level2Icon":"","level3Icon":"","showLevelIcon":false},"printLog":false,"showLevel":true},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"gitbook/website.css"}},"file":{"path":"3. 添加插件.md","mtime":"2019-12-06T15:54:29.937Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-12-06T17:25:00.849Z"},"basePath":".","book":{"language":""}});
         });
     </script>
 </div>