Bookshelf (书架/站点) 索引

ph-Bookshelf 使用 data/bookshelf.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 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> 对象里面，具体都有什么。

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 官方网站的图标）。

configurations

Configurations

configurations 元素是一个 Configurations 对象，其中可以设置所有可以在整个站点范围内设置的配置字段。

虽然这个元素在 Schema 上是必须存在的，但是，你可以简单的在元素内不设置任何的子元素以让它不产生任何作用。实际上，即使你不写 <configurations>，ph-Bookshelf 本身也不会有任何报错。

在 ph-Bookshelf 当中，有很多地方都和 configurations 一样，即使你没有那么的标准，ph-Bookshelf 大概率也是可以解析的。只不过，这样子写不一定具有稳定性，所以我们还是推荐你跟随 Schema 标准，编写 ph-Bookshelf 的索引/配置文件，大部分情况下，这应该也没麻烦多少。

如果真有什么需求是现在的配置文件标准无法解决的，最好的方法不是通过一些比较特殊的手段，而是向 ph-Bookshelf 发送 issue，以让这个项目标准地支持更多功能。

links

LinkIndex

links 元素定义了网站侧边栏中，在网站标题正下方的 Links 目录里的链接。其中，可以放置像是 Team Official Website，Become our Sponsor 之类的外围链接。

作为一个 LinkIndex 类型的元素，它里面将会含有以下几种类型的子元素。其中，Link 和 LinkCollection 可以作为其子元素出现。

Link string(html)

一个链接定义。

Link 内的内容将会被解析为 HTML 文字，作为这个 Link 的标题文字显示。需要注意的是，解析器只识别并解析纯文本内容，并不能直接将 HTML 标签作为 XML 标签嵌套。所以，如果你真的需要在里面嵌套 HTML 内容，一个比较好的办法是使用 <![CDATA[...]]> 标签，like: <Link href=""><![CDATA[<b>My Title</b>]]></Link>。

同时，它也需要如下的属性：

href string(url)
定义了这个链接的目标网址。
Collection LinkCollection

一些链接组成的折叠组。

Collection 作为 LinkCollection 类型的对象，它可以包含一些 Link 组成一个可折叠的组。它也可以包含另外一些自己组成嵌套的组。不过在此之前，它的第一个子元素必须是一个 caption 元素。

caption .first string(html)
一个 Collection 的名称，必须在 Collection 中存在且必须是的第一个子元素。类似于 Link 一样，它也可以包含 HTML 格式的纯文字。它会作为这个 Collection 的标题文字显示。

books

正在更新中

root_book

正在更新中