From 7f73bc1c1a79b86aa79c89365bab1f270f149b38 Mon Sep 17 00:00:00 2001
From: Eyre_S <sukazyo@outlook.com>
Date: Mon, 27 Mar 2023 19:16:12 +0800
Subject: [PATCH] add prism/code-highlight support

---
 book.xml                |  9 +++-
 tools/code-highlight.md | 91 +++++++++++++++++++++++++++++++++++++++++
 web-server.md           | 35 +++++++++++-----
 3 files changed, 123 insertions(+), 12 deletions(-)
 create mode 100644 tools/code-highlight.md

diff --git a/book.xml b/book.xml
index b33ac0e..95de33e 100644
--- a/book.xml
+++ b/book.xml
@@ -15,12 +15,19 @@
 		
 		<Page id="ph-bookshelf">the ph-Bookshelf</Page>
 		<Page id="web-server">Web 服务器配置</Page>
+		
+		<Separator />
+		
+		<Chapter root="tools/">
+			<caption>页面选项</caption>
+			<Page id="code-highlight">代码块高亮着色</Page>
+		</Chapter>
 		<Chapter>
 			<caption>高级选项</caption>
 			<Page id="enhanced/robots-policy">robots.txt</Page>
 		</Chapter>
 		
-		<Separator />
+		<!-- <Separator /> -->
 		
 		<!-- <Chapter root="olds/">
 			<caption>旧书</caption>
diff --git a/tools/code-highlight.md b/tools/code-highlight.md
new file mode 100644
index 0000000..cf23ad3
--- /dev/null
+++ b/tools/code-highlight.md
@@ -0,0 +1,91 @@
+---
+title: 代码块高亮
+---
+
+# <small>基于 Prism 的</small> 代码块高亮支持
+
+[Prism]: https://prismjs.com/
+
+ph-Bookshelf 默认基于 [Prism] 支持了代码块高亮，并开放了一些配置可以由你来调整一些代码块的显示样式。
+
+## 使用 Prism 代码高亮
+
+ph-Bookshelf 默认开启了 [Prism] 代码高亮支持，你可以将配置节点 `prism` 设置为 `false` 来关闭高亮支持。
+
+在 Prism 已经开启的情况下，向代码块添加 css 类 `language-xxx` 或是 `lang-xxx` 即可为这个代码块进行高亮着色。
+
+Prism 不会自动为所有代码块着色，所以不指定 `language-xxx` 即不会对代码块高亮。
+
+## 配置高亮/代码块样式
+
+// todo
+
+---
+
+## 你知道吗
+
+ph-Bookshelf 本来是使用的 [highlight.js] 代码高亮库，在写这篇文档的时候，突然就更换为 [Prism] 库了。于是，你文档作者的 *50* 行 *1500* 多字**最终还没暖热乎就一点都没用上了**。
+
+<small>至于那些带着冤魂的文档内容，它就在下面被注释掉的段落里。</small>
+
+<!-- ---
+title: 代码块高亮
+--- -->
+
+<!-- # <small>基于 highlight.js 的</small> 代码块高亮支持 -->
+
+[highlight.js]: https://highlightjs.org/
+[使用介绍]: https://highlightjs.org/usage/
+<!-- [Markdown 属性语法]: https://todo -->
+
+<!-- ph-Bookshelf 默认基于 [highlight.js] 支持了代码块高亮，并开放了一些配置可以由你来调整一些代码块的显示样式。
+
+## 开关 highlight.js 高亮
+
+ph-Bookshelf 默认开启了 [highlight.js] 高亮，你可以将配置节点 `highlightjs` 设置为 `false` 来关闭全局高亮。
+
+*通过这种方式关闭 highlight.js 代码高亮将会让网页不再加载 highlight.js 的代码。除非你在文档内再次引入 hightlight.js 的代码，否则想要通过为代码块设置类型来单独打开它是不可能的。*
+
+### 为单个代码块关闭高亮
+
+[highlight.js] 默认支持了可以通过为代码块设置 CSS 类 `nohighlight` 来为这个代码块关闭高亮：
+
+> **Ignoring a Code Block**
+> 
+> To skip highlighting of a code block completely, use the nohighlight class:
+>
+> ```
+> <pre><code class="nohighlight">...</code></pre>
+> ```
+
+在 ph-Bookshelf 的 Markdown 语法中，你可以简单的通过[Markdown 属性语法]的方式来关闭一个代码块的高亮。
+
+<pre><code class="language-markdown">
+> 这个 nohighlight 属性将会直接添加到 &lt;code> 标签当中（而不是更外层的 &lt;pre> 标签）使其能够关闭代码块高亮
+{.nohighlight}
+```
+# some code..? here!
+```
+
+> 出于一些原因，如果指定了语言，highlight.js 将会忽略掉 nohighlight 标签。所以这个代码块仍然会以 ini 语言被渲染高亮
+{.nohighlight}
+```ini
+# some code! here
+```</code></pre>
+
+
+## 配置高亮/代码块样式
+
+
+
+## 添加更多的语言支持
+
+ph-Bookshelf 默认引入的 highlight.js 仅引入了基础的高亮语法包：它基本上包括了大部分会使用到的语言<small>像是 *java*, *html*, *yaml*, *shell*, 甚至是 *scss* 等等</small>，但是有一些不太经常用到的语言例如 `apache-config` `ascii-doc` 等等，并未被包含在基础语法包当中。
+
+对于需要使用到这些语言的情况，ph-Bookshelf 支持了一个 `highlightjs.languages` 配置节点，你可以在需要的地方使用这个配置节点添加你需要的语言包，ph-Bookshelf 将会在用户访问对应书籍/页面的时候加载这些语言的扩展插件使一些不在基础包中的语言也可以得到高亮支持。
+
+`highlightjs.languages` 的值为一串你想要添加支持的语言，每个语言名称之间通过 `;` 来分隔。
+
+ph-Bookshelf 可以合并不同位置添加的语言，所以在 *book.xml* 设置了 `haml; handlebars`，在页面内设置了 `mercury; sas` 后，最后在这个页面内，将会导入 `haml` `handlebars` `mercury` `sas` 四个语言。
+
+内容a {.language-css}`.p { background-color: #123456; }` 内容b -->
diff --git a/web-server.md b/web-server.md
index f875ebe..dfcdcaa 100644
--- a/web-server.md
+++ b/web-server.md
@@ -1,8 +1,3 @@
----
-configurations:
-  highlightjs.languages: "apache"
----
-
 # Web Server
 
 [Apache]: https://httpd.apache.org/
@@ -13,26 +8,26 @@ ph-Bookshelf 原始版本是在 [Apache Web Server][Apache] 环境下开发的
 
 你也可以在其它的环境下使用 **ph-Bookshelf**，只需要一些简单的路径重写设置。
 
-## Apache
+## 对于你自己管理的的 Apache 服务器
 
 要想在 [Apache] 中使用 **ph-Bookshelf**，你只需要确认一些简单的设置：
 
 确认 [mod_rewrite] 已经打开。这一般可以通过以下简单的命令确认：
 
-```shell
+```shell-session
 # a2enmod rewrite
 ```
 
-> 如果你使用的是旧版 Apache<small>一般存在于会被叫做 httpd 的 apache</small>，module 配置或许会在服务器里，这时候，大概你的 Apache 的配置文件（通常为 /etc/apache2/httpd.conf 或者 /etc/httpd/httpd.conf），找到以下行并取消注释它：
+> 如果你使用的是旧版 Apache<small>一般存在于会被叫做 httpd 的 apache</small>，module 配置或许会在服务器里，这时候，大概你的 Apache 的配置文件（通常为 `/etc/apache2/httpd.conf`{.lang-url} 或者 `/etc/httpd/httpd.conf`{.lang-url}），找到以下行并取消注释它：
 >
-> ```apache
+> ```apacheconf
 > # uncomment this line
 > LoadModule rewrite_module libexec/apache2/mod_rewrite.so
 > ```
 
 然后，为你的 ph-Bookshelf 目录配置允许路径重写：
 
-```apache
+```apacheconf
 <Directory /path/to/your/ph-Bookshelf>
 	AllowOverride All
 </Directory>
@@ -42,4 +37,22 @@ ph-Bookshelf 原始版本是在 [Apache Web Server][Apache] 环境下开发的
 
 你无需在 [Apache] 配置文件中配置路径重写规则，它已经存在在了 ph-Bookshelf 项目根目录下的 .htaccess 当中。
 
-> 如果你是使用 php 站点托管，请询问你的托管服务商是否支持 [Apache] [.htaccess] 的使用。
+## 对于 Nginx 或其它各种各样的 Web 服务器
+
+一般的 Web 服务器都支持 URL 重写，但它们可能有自己的配置方式。
+
+你可以参考 ph-bookshelf 项目下的 `.htaccess` 文件，在你的 Web 服务器配置上面自己配置 URL 重写规则。
+
+> 作为参考，这是 ph-bookshelf 在 Nginx 下的 URL 重写规则：
+>
+> ```nginx
+> location / {
+>   rewrite ^(.*)$ /index.php?p=$0;
+> }
+> ```
+>
+> 在 nginx 中，将这一部分添加到你的 `server {}`{.lang-nginx} 块中就可以完成配置。
+
+## 对于使用 php 网站托管服务的用户
+
+如果你是使用 php 站点托管，请询问你的托管服务商是否支持 [Apache] [.htaccess] 的使用。