From 5c9cf4d4ae301090efa5fe77bdd5265c9586db96 Mon Sep 17 00:00:00 2001 From: Eyre_S Date: Tue, 16 Jan 2024 18:16:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E7=9A=84=20configurations=20=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E3=80=82=E5=88=A0=E9=99=A4=E6=97=A7=E4=B9=A6=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- book.xml | 37 +-- configurations/bookshelf.md | 159 ++++++++++ configurations/configurations.md | 291 ++++++++++++++++++ configurations/listing-rainbow-off.png | Bin 0 -> 864047 bytes configurations/listing-rainbow-on.png | Bin 0 -> 917735 bytes configurations/shelf-frontend-custom.md | 11 + enhanced/robots-policy.md | 44 --- olds/book.xml | 15 - olds/custom.md | 5 - olds/install.md | 42 --- olds/main.md | 12 - olds/plans.md | 2 - ph-bookshelf.md | 2 +- ...ode-highlight-prism-supported-languages.md | 4 +- tools/code-highlight.md | 110 ------- tools/regex-highlight.md | 2 + 16 files changed, 474 insertions(+), 262 deletions(-) create mode 100644 configurations/bookshelf.md create mode 100644 configurations/configurations.md create mode 100644 configurations/listing-rainbow-off.png create mode 100644 configurations/listing-rainbow-on.png create mode 100644 configurations/shelf-frontend-custom.md delete mode 100644 enhanced/robots-policy.md delete mode 100644 olds/book.xml delete mode 100644 olds/custom.md delete mode 100644 olds/install.md delete mode 100644 olds/main.md delete mode 100644 olds/plans.md delete mode 100644 tools/code-highlight.md diff --git a/book.xml b/book.xml index 4803955..77396c6 100644 --- a/book.xml +++ b/book.xml @@ -1,10 +1,10 @@ @@ -21,39 +21,16 @@ - Tutorial + Getting Started 开始使用 Web 服务器配置 - - Configurations - - 页面选项 - Prism 代码高亮]]> - RegEx 高亮着色 - - - 站点配置选项 - robots.txt - - - - - + 书架/站点索引文件 + 配置节点 + 自定义 CSS/JS diff --git a/configurations/bookshelf.md b/configurations/bookshelf.md new file mode 100644 index 0000000..f131270 --- /dev/null +++ b/configurations/bookshelf.md @@ -0,0 +1,159 @@ +# Bookshelf (书架/站点) 索引 + +ph-Bookshelf 使用 `data/bookshelf.xml` 作为整个站点的索引与配置文件，在这个配置文件里，你将需要配置网站信息，网站主要书籍的目录，也可以配置在整个网站作用域内生效的[个性化配置](./configurations)。 + +这个配置文件的基础结构如下 + +```xml + + + + My Bookshelf + /icon.png + ... + + ... + ... + + ... + + +``` + +其中，它使用了 `../assets/xsd/bookshelf.xsd` 作为 XML Schema。在最普通的 ph-bookshelf 运行配置下，这将链接到当前所安装的 bookshelf 的 XML Schema。你也可以选择使用 GitHub 上的特定版本的 XML Schema，或者 ph-bookshelf 官方实例的 XML Schema，像下面这样： + +```xml + +... +``` + +接下来，我们将会看一下 `` 对象里面，具体都有什么。 + +--- + + + +## BookShelf 属性 + +### version + + string + +**`version`** 表示了此书架使用的配置文件版本。 + +目前，最新的书架版本文件是 `2.0`，其相关的 ph-Bookshelf 版本在 `config-v2.0` 分支中还在开发当中。 + +我们目前推荐使用 `2.0` 版本由于 `1.0` 版本实在是太不完备到难以使用。不过，由于 `config-v2.0` 还在更新，这个文档和这个版本的配置格式也仍有可能不稳定。 + +## BookShelf 子对象 + +### site_name + + string + +**`site_name`** 是整个书架/网站的名称。这个名称将会永远显示在网站侧边栏的标题区域，同时也将会是默认书籍的书籍标题。 + +要注意的是书架名并不会一直显示在网站标题上。网站标题是由 `<页面名称> - <书籍名称>` 组成的。如果一个页面没有页面名称（也即没有在书籍的索引上面），那么 `...` 将会代替页面名称的位置。 + +### site_icon + + string(uri) + +**`site_icon`** 是网站的图标，将会显示在所有页面的标题栏图标位置。同时，它也会变为网站的 `favicon.ico` 的默认输出。 + +这个字段的值应该是一个图片 URI，根据不同的浏览器，对于各种格式的支持程度也会不同。对于最普遍的浏览器而言，`ico` `png` `svg` `jpg`(虽然最好不要这么做) `webp` 等格式都是支援的。最佳选择当然是使用一个 64x 或者 128x 左右的支援透明格式的方形图标图片（或者 svg 当然也是很好的，只要浏览器支持）。 + +这个字段是可选的。如果没有这个字段，那么，网站将会默认使用 ph-Bookshelf 的项目图标 `/assets/ph-bookshelf.svg`（在目前，这也是 [ Workshop Documentation](https://book.sukazyo.cc) 官方网站的图标）。 + +### configurations + + Configurations + +**`configurations`** 元素是一个 [`Configurations`](./configurations) 对象，其中可以设置所有可以在整个站点范围内设置的配置字段。 + +虽然这个元素在 Schema 上是必须存在的，但是，你可以简单的在元素内不设置任何的子元素以让它不产生任何作用。实际上，即使你不写 ``，ph-Bookshelf 本身也不会有任何报错。 + +> 在 ph-Bookshelf 当中，有很多地方都和 `configurations` 一样，即使你没有那么的标准，ph-Bookshelf 大概率也是可以解析的。只不过，这样子写不一定具有稳定性，所以我们还是推荐你跟随 Schema 标准，编写 ph-Bookshelf 的索引/配置文件，大部分情况下，这应该也没麻烦多少。 +> +> 如果真有什么需求是现在的配置文件标准无法解决的，最好的方法不是通过一些比较特殊的手段，而是[向 ph-Bookshelf 发送 issue](https://github.com/suk-ws/ph-Bookshelf/issues)，以让这个项目标准地支持更多功能。 + +### links + + LinkIndex + +**links** 元素定义了网站侧边栏中，在网站标题正下方的 Links 目录里的链接。其中，可以放置像是 *Team Official Website*，*Become our Sponsor* 之类的外围链接。 + +作为一个 `LinkIndex` 类型的元素，它里面将会含有以下几种类型的子元素。其中，`Link` 和 `LinkCollection` 可以作为其子元素出现。 + +Link string(html) + +: 一个链接定义。 + + `Link` 内的内容将会被解析为 HTML 文字，作为这个 `Link` 的标题文字显示。需要注意的是，解析器只识别并解析纯文本内容，并不能直接将 HTML 标签作为 XML 标签嵌套。所以，如果你真的需要在里面嵌套 HTML 内容，一个比较好的办法是使用 \ 标签，like: \\My Title\]]>\。 + + 同时，它也需要如下的属性： + + `href` string(url) + : 定义了这个链接的目标网址。 + +Collection LinkCollection + +: 一些链接组成的折叠组。 + + `Collection` 作为 `LinkCollection` 类型的对象，它可以包含一些 `Link` 组成一个可折叠的组。它也可以包含另外一些自己组成嵌套的组。不过在此之前，它的第一个子元素必须是一个 `caption` 元素。 + + caption .first string(html) + : 一个 `Collection` 的名称，必须在 `Collection` 中存在且必须是的第一个子元素。类似于 `Link` 一样，它也可以包含 HTML 格式的纯文字。它会作为这个 `Collection` 的标题文字显示。 + +### books + +*正在更新中* + +### root_book + +*正在更新中* diff --git a/configurations/configurations.md b/configurations/configurations.md new file mode 100644 index 0000000..b321382 --- /dev/null +++ b/configurations/configurations.md @@ -0,0 +1,291 @@ +# ph-Bookshelf 可配置节点 + +这里列出了所有的可配置节点，以及它们的具体功能。 + + + +### prism + + + + + + +boolean + +[Prism]: https://prismjs.com/ + +是否使用 [Prism] 进行代码块语法高亮。默认为 `true`。 + +ph-Bookshelf 使用的 Prism 版本默认具有所有的语言支持。因此你将不需要为不常用语言手动导入 Prism 语言扩展。简单地使用 HTML `` 或 ` ```css ` 即可。 + +> 对于 HTML 的内联代码块，Prism 也是支持对此进行高亮着色的。只不过，在 Markdown 当中没有对 ` `` ` 设置语言的方式。 + +这里有一份 [Prism 支持语言列表](../tools/code-highlight-prism-supported-languages) + +### prism.theme + + + + + + +string + +要使用的 [Prism] 高亮主题。查看 [Prism Themes](https://www.jsdelivr.com/package/npm/prism-themes) 寻找可用的主题。 + +默认为 `prism-material-light`。如果 `prism` 未开启。则这个配置不会产生任何作用。 + +对于普通的没有高亮配置的字符，尤其是代码块本身的背景颜色，Prism 主题并不会覆盖默认的 Bread Card Markdown 的代码块颜色设置。所以，如果你要更改你的主题，你或许同时也需要更改 [`codeblock.bg-color`](#codeblockbg-color) 和 [`codeblock.fg-color`](#codeblockfg-color) 设置以让未高亮的文字和代码块背景颜色符合主题设置的颜色。 + +### prism.plugins + + + + + + +string(array(';')) + +要使用的 [Prism] [插件](https://prismjs.com/#plugins)列表。每一个插件 id 通过 `;` 分隔。 + +和其它的配置不同的是，不同作用域内的插件列表会被合并而不是默认的覆盖行为。所以在 `book.xml` 设置了 `line-numbers; autolinker`，在页面内设置了 `command-line` 后，最终，访问这个页面将会导入 `line-numbers` `autolinker` `command-line` 三个插件。 + +> 通过 `prism.plugins` 导入的插件最终将会向页面导入 `https://cdn.jsdelivr.net/npm/prismjs@v1.x/plugins/{$plugin}/prism-{$plugin}.min.js`{.lang-url} 和 `https://cdn.jsdelivr.net/npm/prismjs@v1.x/plugins/{$plugin}/prism-{$plugin}.min.css`{.lang-url} 两个文件。这在导入 Prism 官方插件的一般情况下都可以使用。 +> +> 目前还没有支持从自定义 url 导入。 + +默认没有插件。如果 `prism` 未开启。则这个配置可能不会产生任何作用——也可能会造成错误，取决于 Prism。 + +> 同时，这里写出了一些使用 Prism 插件的已知问题： +> +> - prism `line-numbers` 插件会和 bread-card-markdown 的代码块样式表产生兼容性，导致行号无法正常显示。 +> - 但是和它差不多的插件 `command-line` 是可以正常使用的。 + +插件的 id 可以在 [plugins 目录](https://www.jsdelivr.com/package/npm/prismjs?tab=files&path=plugins)内找到。 + +### codeblock.bg-color + + + + + + +string(color.css) + +自定义代码块的背景颜色。可以接受任何 CSS 兼容的颜色值。 + +对于想要自定义代码块主题的用户会很有用。 + +### codeblock.fg-color + + + + + + +string(color.css) + +自定义代码块的默认文字颜色。可以接受任何 CSS 兼容的颜色值。 + +对于想要自定义代码块主题的用户会很有用。 + +### codeblock.tab-size + + + + + + +number(int) + +控制代码块内的 TAB 应该显示为多少个空格大小。如果未设置，那么其值将会由用户浏览器决定。 + +### regex.highlight + + + + + + +boolean + +控制是否使用 Sukazyo Workshop 自制的 [regex-colorize](https://github.com/suk-ws/regex-colorizer) 进行 RegEx 语法高亮。默认为 `true`。 + +查看 [RegEx 高亮着色](../tools/regex-highlight) 的文档以了解更多这个功能的使用方式。 + +### listing.marker.rainbow + + + + + + +boolean + +控制是否使用 Bread Card Markdown 的 Listing Rainbow 插件。默认为 `true` + +| with Listing Rainbow | without Listing Rainbow | +|:---:|:---:| +| ![](./listing-rainbow-on.png) | ![](./listing-rainbow-off.png) | + +### title.permalink.flash + + + + + + +boolean + +控制当跳转到页面中一个标题的时候，是否闪烁这个标题的悬浮链接按钮。默认为 `false`。 + +*预览 GIF 正在路上* + +### web-title.rolling + + + + + + +boolean + +控制是否使用滚动网页标题的特效。默认为 `false`。 + +*预览 GIF 正在路上* + +### site.robots + + + + +string + +控制网站的 `robots.txt` 应该返回何种内容。接受以下几种选项。 + +allow + +: 允许所有种类的爬虫访问本网站。 + + 具体的内容存放在 ph-Bookshelf 的 [`/assets/robots.allow`](/assets/robots.allow) 当中。 + +deny + +: 拒绝所有种类的爬虫访问本网站。 + + 具体的内容存放在 ph-Bookshelf 的 [`/assets/robots.deny`](/assets/robots.deny) 当中。 + +file +custom + +: 如果设置为这个模式，那么网站 `/robots.txt` 的内容将会是 `/data` 目录下的 `robots.txt` 的内容。 + + 如果你的数据目录中没有这个文件，那么将会不产生任何内容。 + + > 除非你的 PHP 的配置文件中设置了 `display_error=On`：在这种情况下，页面将输出 PHP 错误。 + +其它任何值 + +: 当设置的值不属于上面的任何一个预定义值时，将会输出设置值的原始内容。这也是不设置任何值时的默认行为——也就是如果不设置任何值， `robots.txt` 只会是一个完全空白的文档。 + + > 从技术角度来说，这意味着“使用 `bookshelf.xml` 中的 `` 中的 `` 的原始内容。” + + 因此，你可以使用 `` 直接在这里填入你想要设置的 robots.txt 内容。虽然，出于整洁性考虑，我们仍然推荐使用 `data/robots.txt` 文件的方式而非这样的方式。 + + - -如果环境配置没有问题，那么现在这个站点就可以运行了... -是的，运行结果还是 ERROR Not Found。 - -但现在你可以下载 -[预定义的 data 演示文件][demo-data] -来提前查看效站点运行果了 - -[phb-repo]: https://github.com/suk-ws/ph-Bookshelf -[demo-data]: https://srv.sukazyo.cc/resources/projects/ph-bookshelf/demo/data.zip diff --git a/olds/main.md b/olds/main.md deleted file mode 100644 index 436900f..0000000 --- a/olds/main.md +++ /dev/null @@ -1,12 +0,0 @@ -这是一个基于 Gitbook 的简单的多 book 实现。 - -因为 web 相关的东西 Sukazyo 最熟悉的就是 php 了所以就用 php 写的。 -但是写出来的代码还是十分离谱的不易读的：各种调用交错在一起，前后端也交错在一起 - -而且也并不好用。 - -不过 Sukazyo 考虑到既然这么不好用，写一个使用说明大概就还挺必要的，反正也是随手的事情。 - -~~什么，你问示例站？这里不就是吗？~~ - -*这个项目还有[很多内容正在开发](/ph-bookshelf/plans)* diff --git a/olds/plans.md b/olds/plans.md deleted file mode 100644 index 349be25..0000000 --- a/olds/plans.md +++ /dev/null @@ -1,2 +0,0 @@ -待补充 - diff --git a/ph-bookshelf.md b/ph-bookshelf.md index a1f05a1..b30a8d0 100644 --- a/ph-bookshelf.md +++ b/ph-bookshelf.md @@ -5,7 +5,7 @@ configurations: regex.highlight: 'true' --- -# the ph-Bookshelf +# icon the ph-Bookshelf ![preview](./preview.png) diff --git a/tools/code-highlight-prism-supported-languages.md b/tools/code-highlight-prism-supported-languages.md index f52a2fb..9ea6a3f 100644 --- a/tools/code-highlight-prism-supported-languages.md +++ b/tools/code-highlight-prism-supported-languages.md @@ -2,10 +2,12 @@ title: "ref: Prism - 支持的语言" --- -[< Back](./code-highlight) +< Back 下面列出了包含它们的别名的，目前 Prism 支持的全部 297 个语言。通过定义 css 类型 language-xxxx（或 lang-xxxx）来使用 xxxx。 +这个列表最后更新于 2023-03-28。更新的 Prism 版本或许已经支持了更多的语言。 + > This is the list of all 297 languages currently supported by Prism, with their corresponding alias, to use in place of xxxx in the language-xxxx (or lang-xxxx) class: