160 lines
6.7 KiB
Markdown
160 lines
6.7 KiB
Markdown
|
# Bookshelf (书架/站点) 索引
|
|||
|
|
|
|||
|
|
ph-Bookshelf 使用 `data/bookshelf.xml` 作为整个站点的索引与配置文件，在这个配置文件里，你将需要配置网站信息，网站主要书籍的目录，也可以配置在整个网站作用域内生效的[个性化配置](./configurations)。
|
|||
|
|
|
|||
|
|
这个配置文件的基础结构如下
|
|||
|
|
|
|||
|
|
```xml
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<BookShelf
|
|||
|
|
xmlns="https://book.sukazyo.cc/"
|
|||
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|||
|
|
xsi:schemaLocation="
|
|||
|
|
https://book.sukazyo.cc/ ../assets/xsd/bookshelf.xsd
|
|||
|
|
"
|
|||
|
|
|
|||
|
|
version="2.0"
|
|||
|
|
>
|
|||
|
|
|
|||
|
|
<site_name>My Bookshelf</site_name>
|
|||
|
|
<site_icon>/icon.png</site_icon>
|
|||
|
|
<configurations>...</configurations>
|
|||
|
|
|
|||
|
|
<links>...</links>
|
|||
|
|
<books>...</books>
|
|||
|
|
|
|||
|
|
<root_book>...</root_book>
|
|||
|
|
|
|||
|
|
</BookShelf>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
其中，它使用了 `../assets/xsd/bookshelf.xsd` 作为 XML Schema。在最普通的 ph-bookshelf 运行配置下，这将链接到当前所安装的 bookshelf 的 XML Schema。你也可以选择使用 GitHub 上的特定版本的 XML Schema，或者 ph-bookshelf 官方实例的 XML Schema，像下面这样：
|
|||
|
|
|
|||
|
|
```xml
|
|||
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|||
|
|
<BookShelf
|
|||
|
|
xmlns="https://book.sukazyo.cc/"
|
|||
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|||
|
|
xsi:schemaLocation="
|
|||
|
|
https://book.sukazyo.cc/ https://raw.githubusercontent.com/suk-ws/ph-Bookshelf/master/assets/xsd/bookshelf.xsd
|
|||
|
|
"
|
|||
|
|
|
|||
|
|
version="2.0"
|
|||
|
|
>...</BookShelf>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
接下来，我们将会看一下 `<BookShelf>` 对象里面，具体都有什么。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
required {
|
|||
|
|
font-size: 0.8em;
|
|||
|
|
background-color: #c7adf1;
|
|||
|
|
border-radius: 0.5em;
|
|||
|
|
padding: 0.2em 0.5em;
|
|||
|
|
color: white;
|
|||
|
|
}
|
|||
|
|
required::before {
|
|||
|
|
content: 'required';
|
|||
|
|
}
|
|||
|
|
optional {
|
|||
|
|
font-size: 0.8em;
|
|||
|
|
background-color: #c7adf1;
|
|||
|
|
border-radius: 0.5em;
|
|||
|
|
padding: 0.2em 0.5em;
|
|||
|
|
color: white;
|
|||
|
|
}
|
|||
|
|
optional::before {
|
|||
|
|
content: 'optional';
|
|||
|
|
}
|
|||
|
|
type {
|
|||
|
|
font-size: 0.8em;
|
|||
|
|
background-color: #91c6ff;
|
|||
|
|
border-radius: 0.5em;
|
|||
|
|
padding: 0.2em 0.5em;
|
|||
|
|
font-family: var(--font-monospace), monospace;
|
|||
|
|
color: white;
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
## BookShelf 属性
|
|||
|
|
|
|||
|
|
### version
|
|||
|
|
|
|||
|
|
<required></required> <type>string</type>
|
|||
|
|
|
|||
|
|
**`version`** 表示了此书架使用的配置文件版本。
|
|||
|
|
|
|||
|
|
目前，最新的书架版本文件是 `2.0`，其相关的 ph-Bookshelf 版本在 `config-v2.0` 分支中还在开发当中。
|
|||
|
|
|
|||
|
|
我们目前推荐使用 `2.0` 版本由于 `1.0` 版本实在是太不完备到难以使用。不过，由于 `config-v2.0` 还在更新，这个文档和这个版本的配置格式也仍有可能不稳定。
|
|||
|
|
|
|||
|
|
## BookShelf 子对象
|
|||
|
|
|
|||
|
|
### site_name
|
|||
|
|
|
|||
|
|
<required></required> <type>string</type>
|
|||
|
|
|
|||
|
|
**`site_name`** 是整个书架/网站的名称。这个名称将会永远显示在网站侧边栏的标题区域，同时也将会是默认书籍的书籍标题。
|
|||
|
|
|
|||
|
|
要注意的是书架名并不会一直显示在网站标题上。网站标题是由 `<页面名称> - <书籍名称>` 组成的。如果一个页面没有页面名称（也即没有在书籍的索引上面），那么 `...` 将会代替页面名称的位置。
|
|||
|
|
|
|||
|
|
### site_icon
|
|||
|
|
|
|||
|
|
<optional></optional> <type>string(uri)</type>
|
|||
|
|
|
|||
|
|
**`site_icon`** 是网站的图标，将会显示在所有页面的标题栏图标位置。同时，它也会变为网站的 `favicon.ico` 的默认输出。
|
|||
|
|
|
|||
|
|
这个字段的值应该是一个图片 URI，根据不同的浏览器，对于各种格式的支持程度也会不同。对于最普遍的浏览器而言，`ico` `png` `svg` `jpg`<small>(虽然最好不要这么做)</small> `webp` 等格式都是支援的。最佳选择当然是使用一个 64x 或者 128x 左右的支援透明格式的方形图标图片（或者 svg 当然也是很好的，只要浏览器支持）。
|
|||
|
|
|
|||
|
|
这个字段是可选的。如果没有这个字段，那么，网站将会默认使用 ph-Bookshelf 的项目图标 <img src='/assets/ph-bookshelf.svg' class='em-height'> `/assets/ph-bookshelf.svg`（在目前，这也是 [ Workshop Documentation](https://book.sukazyo.cc) 官方网站的图标）。
|
|||
|
|
|
|||
|
|
### configurations
|
|||
|
|
|
|||
|
|
<required></required> <type>Configurations</type>
|
|||
|
|
|
|||
|
|
**`configurations`** 元素是一个 [`Configurations`](./configurations) 对象，其中可以设置所有可以在整个站点范围内设置的配置字段。
|
|||
|
|
|
|||
|
|
虽然这个元素在 Schema 上是必须存在的，但是，你可以简单的在元素内不设置任何的子元素以让它不产生任何作用。实际上，即使你不写 `<configurations>`，ph-Bookshelf 本身也不会有任何报错。
|
|||
|
|
|
|||
|
|
> 在 ph-Bookshelf 当中，有很多地方都和 `configurations` 一样，即使你没有那么的标准，ph-Bookshelf 大概率也是可以解析的。只不过，这样子写不一定具有稳定性，所以我们还是推荐你跟随 Schema 标准，编写 ph-Bookshelf 的索引/配置文件，大部分情况下，这应该也没麻烦多少。
|
|||
|
|
>
|
|||
|
|
> 如果真有什么需求是现在的配置文件标准无法解决的，最好的方法不是通过一些比较特殊的手段，而是[向 ph-Bookshelf 发送 issue](https://github.com/suk-ws/ph-Bookshelf/issues)，以让这个项目标准地支持更多功能。
|
|||
|
|
|
|||
|
|
### links
|
|||
|
|
|
|||
|
|
<required></required> <type>LinkIndex</type>
|
|||
|
|
|
|||
|
|
**links** 元素定义了网站侧边栏中，在网站标题正下方的 Links 目录里的链接。其中，可以放置像是 *Team Official Website*，*Become our Sponsor* 之类的外围链接。
|
|||
|
|
|
|||
|
|
作为一个 `LinkIndex` 类型的元素，它里面将会含有以下几种类型的子元素。其中，`Link` 和 `LinkCollection` 可以作为其子元素出现。
|
|||
|
|
|
|||
|
|
Link <type>string(html)</type>
|
|||
|
|
|
|||
|
|
: 一个链接定义。
|
|||
|
|
|
|||
|
|
`Link` 内的内容将会被解析为 HTML 文字，作为这个 `Link` 的标题文字显示。需要注意的是，解析器只识别并解析纯文本内容，并不能直接将 HTML 标签作为 XML 标签嵌套。所以，如果你真的需要在里面嵌套 HTML 内容，一个比较好的办法是使用 <code class=lang-xml>\<![CDATA[...]]></code> 标签，like: <code class=lang-xml>\<Link href="">\<![CDATA[\<b>My Title\</b>]]>\</Link></code>。
|
|||
|
|
|
|||
|
|
同时，它也需要如下的属性：
|
|||
|
|
|
|||
|
|
`href` <required></required> <type>string(url)</type>
|
|||
|
|
: 定义了这个链接的目标网址。
|
|||
|
|
|
|||
|
|
Collection <type>LinkCollection</type>
|
|||
|
|
|
|||
|
|
: 一些链接组成的折叠组。
|
|||
|
|
|
|||
|
|
`Collection` 作为 `LinkCollection` 类型的对象，它可以包含一些 `Link` 组成一个可折叠的组。它也可以包含另外一些自己组成嵌套的组。不过在此之前，它的第一个子元素必须是一个 `caption` 元素。
|
|||
|
|
|
|||
|
|
caption <required>.first</required> <type>string(html)</type>
|
|||
|
|
: 一个 `Collection` 的名称，必须在 `Collection` 中存在且必须是的第一个子元素。类似于 `Link` 一样，它也可以包含 HTML 格式的纯文字。它会作为这个 `Collection` 的标题文字显示。
|
|||
|
|
|
|||
|
|
### books
|
|||
|
|
|
|||
|
|
*正在更新中*
|
|||
|
|
|
|||
|
|
### root_book
|
|||
|
|
|
|||
|
|
*正在更新中*
|