# 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

*正在更新中*