# 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
*正在更新中*