# ph-Bookshelf 可配置节点

这里列出了所有的可配置节点，以及它们的具体功能。

<style>
	
	shelf {
		background-color: #c7adf1;
		border-radius: 0.5em;
		padding: 0.2em 0.5em;
		color: white;
	}
	shelf::before {
		content: 'shelf';
	}
	book {
		background-color: #3fb4c5;
		border-radius: 0.5em;
		padding: 0.2em 0.5em;
		color: white;
	}
	book::before {
		content: 'book';
	}
	page {
		background-color: #b3cc57;
		border-radius: 0.5em;
		padding: 0.2em 0.5em;
		color: white;
	}
	page::before {
		content: 'page';
	}
	t {
		background-color: #91c6ff;
		border-radius: 0.5em;
		padding: 0.2em 0.5em;
		font-family: var(--font-monospace), monospace;
		color: white;
	}
	
	type {
		font-size: 0.8em;
		color: #838383;
		padding: 0.2em 0.5em;
		padding-bottom: 0.4em;
		border-radius: 0.5em;
		background-color: #ebeff2;
		display: inline-flex;
		flex-direction: column;
		gap: 0.2em;
	}
	type::before {
		content: 'type';
		padding-inline-start: 0.5em;
	}
	scope {
		font-size: 0.8em;
		color: #838383;
		padding: 0.2em 0.5em;
		padding-bottom: 0.4em;
		border-radius: 0.5em;
		background-color: #ebeff2;
		display: inline-flex;
		flex-direction: column;
		gap: 0.2em;
	}
	scope::before {
		content: 'available on';
		padding-inline-start: 0.5em;
	}
	
</style>

### prism

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>boolean</t></type>

[Prism]: https://prismjs.com/

是否使用 [Prism] 进行代码块语法高亮。默认为 `true`。

ph-Bookshelf 使用的 Prism 版本默认具有所有的语言支持。因此你将不需要为不常用语言手动导入 Prism 语言扩展。简单地使用 HTML `<code lang=lang-css>` 或 ` ```css ` 即可。

> 对于 HTML 的内联代码块，Prism 也是支持对此进行高亮着色的。只不过，在 Markdown 当中没有对 ` `` ` 设置语言的方式。

这里有一份 [Prism 支持语言列表](../tools/code-highlight-prism-supported-languages)

### prism.theme

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>string</t></type>

要使用的 [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

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>string(array(';'))</t></type>

要使用的 [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

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>string(color.css)</t></type>

自定义代码块的背景颜色。可以接受任何 CSS 兼容的颜色值。

对于想要自定义代码块主题的用户会很有用。

### codeblock.fg-color

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>string(color.css)</t></type>

自定义代码块的默认文字颜色。可以接受任何 CSS 兼容的颜色值。

对于想要自定义代码块主题的用户会很有用。

### codeblock.tab-size

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>number(int)</t></type>

控制代码块内的 <kbd>TAB</kbd> 应该显示为多少个空格大小。如果未设置，那么其值将会由用户浏览器决定。

### regex.highlight

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>boolean</t></type>

控制是否使用 Sukazyo Workshop 自制的 [regex-colorize](https://github.com/suk-ws/regex-colorizer) 进行 RegEx 语法高亮。默认为 `true`。

查看 [RegEx 高亮着色](../tools/regex-highlight) 的文档以了解更多这个功能的使用方式。

### listing.marker.rainbow

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>boolean</t></type>

控制是否使用 Bread Card Markdown 的 Listing Rainbow 插件。默认为 `true`

| with Listing Rainbow | without Listing Rainbow |
|:---:|:---:|
| ![](./listing-rainbow-on.png) | ![](./listing-rainbow-off.png) |

### title.permalink.flash

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>boolean</t></type>

控制当跳转到页面中一个标题的时候，是否闪烁这个标题的悬浮链接按钮。默认为 `false`。

*预览 GIF 正在路上*

### web-title.rolling

<scope><on>
<shelf></shelf>
<book></book>
<page></page>
</on></scope>
<type><t>boolean</t></type>

控制是否使用滚动网页标题的特效。默认为 `false`。

*预览 GIF 正在路上*

### site.robots

<scope><on>
<shelf></shelf>
</on></scope>
<type><t>string</t></type>

控制网站的 `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` 中的 `<configurations>` 中的 `<site.robots>` 的原始内容。”
	
	因此，你可以使用 `<![CDATA[]]>` 直接在这里填入你想要设置的 robots.txt 内容。<small>虽然，出于整洁性考虑，我们仍然推荐使用 `data/robots.txt` 文件的方式而非这样的方式。</small>

<!--

### custom.less

*Currently Unavailable*

<scope><on>
<page></page>
</on></scope>
<type><t>array(string(uri))</t></type>

在当前文件内需要导入的 [less css](https://lesscss.org) 列表。

目前只能在 Markdown Front Matter 内定义，并不能在任何 xml 索引中定义。

目前这个功能仍然没有完成。

for example:
```md
---
configurations:
  custom.less:
    - "./my-tags-provider.less"
---
# Tags Example

<tag class='tag-a'></tag>
```