新的 configurations 说明。删除旧书。
This commit is contained in:
parent
d901f626d4
commit
5c9cf4d4ae
GPG Key ID:
C17CE40291207874
37
book.xml
37
book.xml
@ -1,10 +1,10 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<Book
|
||||
xmlns="https://book.sukazyo.cc"
|
||||
xmlns="https://book.sukazyo.cc/"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="
|
||||
https://book.sukazyo.cc
|
||||
https://book.sukazyo.cc/assets/xsd/book.xsd"
|
||||
https://book.sukazyo.cc/ ../../assets/xsd/book.xsd
|
||||
"
|
||||
|
||||
version="2.0"
|
||||
>
|
||||
@ -21,39 +21,16 @@
|
||||
|
||||
<Separator/>
|
||||
|
||||
<Title>Tutorial</Title>
|
||||
<Title>Getting Started</Title>
|
||||
<Page id="tutorial/get-started">开始使用</Page>
|
||||
<Page id="tutorial/web-server">Web 服务器配置</Page>
|
||||
|
||||
<Separator />
|
||||
|
||||
<!-- <Title>Setup</Title>
|
||||
<Page id="configurations/config-php">config.php</Page> -->
|
||||
|
||||
<Title>Configurations</Title>
|
||||
<Chapter root="tools/">
|
||||
<caption>页面选项</caption>
|
||||
<Page id="code-highlight"><![CDATA[<small>Prism </small>代码高亮]]></Page>
|
||||
<Page id="regex-highlight">RegEx 高亮着色</Page>
|
||||
</Chapter>
|
||||
<Chapter>
|
||||
<caption>站点配置选项</caption>
|
||||
<Page id="enhanced/robots-policy">robots.txt</Page>
|
||||
</Chapter>
|
||||
|
||||
<!-- <Separator /> -->
|
||||
|
||||
<!-- <Chapter root="olds/">
|
||||
<caption>旧书</caption>
|
||||
<Page id="main">ph-Bookshelf</Page>
|
||||
<Page id="install">安装使用</Page>
|
||||
<Chapter>
|
||||
<caption>Datas 书写</caption>
|
||||
<Page id="data-write/bookshelf">建立书架</Page>
|
||||
</Chapter>
|
||||
<Page id="custom">自定义网页样式</Page>
|
||||
<Page id="plans">开发计划</Page>
|
||||
</Chapter> -->
|
||||
<Page id="configurations/bookshelf">书架/站点索引文件</Page>
|
||||
<Page id="configurations/configurations">配置节点</Page>
|
||||
<Page id="configurations/shelf-frontend-custom">自定义 CSS/JS</Page>
|
||||
|
||||
</contents>
|
||||
|
||||
|
||||
159
configurations/bookshelf.md
Normal file
159
configurations/bookshelf.md
Normal file
@ -0,0 +1,159 @@
|
||||
# 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
|
||||
|
||||
*正在更新中*
|
||||
291
configurations/configurations.md
Normal file
291
configurations/configurations.md
Normal file
@ -0,0 +1,291 @@
|
||||
# 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 |
|
||||
|:---:|:---:|
|
||||
|  |  |
|
||||
|
||||
### 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>
|
||||
```
|
||||
BIN
configurations/listing-rainbow-off.png
Normal file
BIN
configurations/listing-rainbow-off.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 844 KiB |
BIN
configurations/listing-rainbow-on.png
Normal file
BIN
configurations/listing-rainbow-on.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 896 KiB |
11
configurations/shelf-frontend-custom.md
Normal file
11
configurations/shelf-frontend-custom.md
Normal file
@ -0,0 +1,11 @@
|
||||
# 使用自定义的 CSS/JS
|
||||
|
||||
目前，ph-Bookshelf 提供了一个简单的在站点中使用你自己的 CSS 和 JS 文件自定义 ph-Bookshelf 的方式。
|
||||
|
||||
你可以在 `/data` 目录下建立 `custom.css` 文件和 `custom.js` 文件来自定义你的站点。
|
||||
|
||||
`custom.css` 中的内容会在预定义的 css 文件之后，作为 `<head>` 标签的最后一个子元素，内联进`<style>`输出。
|
||||
|
||||
`custom.js` 会在页面尾在预定义 js 输出后，通过内联进`<script>`输出。
|
||||
|
||||
对于 Book 或是 Page，目前暂时还没有使用自定义 CSS 和 JS 的接口。尽管，你其实可以在 Markdown 文件里编写 `<style></style>` 和 `<script></script>` 标签。ph-Bookshelf 的 Markdown 的解析器并不会将这些标签*安全化*所以它们可以被正常使用。不过这也意味着你要注意自己在 Markdown 文本内的导入的内容的安全性。
|
||||
@ -1,44 +0,0 @@
|
||||
# robots.txt - 搜索引擎爬虫规则
|
||||
|
||||
[robots.txt]: https://en.wikipedia.org/wiki/Robots.txt
|
||||
|
||||
ph-Bookshelf 提供了 `site.robots` 配置节点，可以允许站点管理员配置网站 [`/robots.txt`][robots.txt] 内容从而控制哪些网页可以被爬虫访问。
|
||||
|
||||
这个值只支持在站点配置（`bookshelf.xml`）中设置。因此，你无法在某个页面或是某个书籍的配置区域单独设置它们的访问控制。
|
||||
|
||||
默认取值为 `allow`。
|
||||
|
||||
支持设置值为 `allow` | `deny` | `custom` | `file`，或其它任何值。
|
||||
|
||||
## allow
|
||||
|
||||
当设置为 **`allow`** 时，将设置 robots.txt 为以下内容，这将允许任何爬虫访问网站的任何页面。
|
||||
|
||||
> 如果站点没有设置 `site.robots` 的值，那么这也是默认输出
|
||||
|
||||
```robots-txt
|
||||
User-agent: *
|
||||
Allow: /
|
||||
```
|
||||
|
||||
## deny
|
||||
|
||||
当设置为 **`deny`** 时，将设置 robots.txt 为以下内容，这将允许任何爬虫访问网站的任何页面。
|
||||
|
||||
```robots-txt
|
||||
User-agent: *
|
||||
Allow: /
|
||||
```
|
||||
|
||||
## custom / file
|
||||
|
||||
当设置为 **`custom`** 或是 **`file`** 时，ph-Bookshelf 将会使用站点数据根目录中的 `robots.txt` 文件作为站点 robots.txt。
|
||||
|
||||
> 如果你的数据目录中没有这个文件，那么将会不产生任何内容。
|
||||
> <small>除非你的 PHP 的配置文件中 `display_error=On`：页面将输出 PHP 错误。</small>
|
||||
|
||||
## 其它任何值
|
||||
|
||||
当填入的值不为以上任何值时，**ph-Bookshelf** 将会把填入的值作为 robots.txt 的内容输出。
|
||||
|
||||
因此，你可以使用 `<![CDATA[]]>` 直接在这里填入你想要设置的 robots.txt 内容。<small>虽然我们仍然推荐使用 [`file`](#custom--file) 方式而非这样的方式。</small>
|
||||
@ -1,15 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<Book id="ph-bookshelf" name="ph-Bookshelf 使用说明"
|
||||
compatibility.article.title.oldversion="true"
|
||||
>
|
||||
<Page id="main" name="ph-Bookshelf" />
|
||||
<Page id="install" name="安装使用" />
|
||||
<Chapter name="Datas 书写">
|
||||
<Page id="data-write/bookshelf" name="建立书架" />
|
||||
</Chapter>
|
||||
<Page id="custom" name="自定义网页样式" />
|
||||
<Page id="plans" name="开发计划" />
|
||||
<Chapter name="高级选项">
|
||||
<Page id="enhanced/robots-policy" name="robots.txt" />
|
||||
</Chapter>
|
||||
</Book>
|
||||
@ -1,5 +0,0 @@
|
||||
你可以在 data 目录下建立 custom.css 文件和 custom.js 文件来自定义你的站点。
|
||||
|
||||
custom.css 中的内容会在预定义的 css 文件之后，作为 `<head>` 标签的最后一个子元素，内联进`<style>`输出。
|
||||
|
||||
custom.js 会在页面尾在预定义 js 输出后，通过内联进`<script>`输出。
|
||||
@ -1,42 +0,0 @@
|
||||
## 环境配置
|
||||
|
||||
ph-Bookshelf 是基于 php 的web程序，所以你需要一个支持 php 的web服务器
|
||||
|
||||
同时，ph-Bookshelf 使用了 php-xml 扩展，**若没有此扩展，会出现 `500` 错误**。
|
||||
这个扩展在 php7.0 及以下还可能叫做 php-dom 扩展。
|
||||
|
||||
同时，（目前而言）web服务器还需要支持 .htaccess 伪静态规则配置。
|
||||
如果你使用的是 Apache 或是基于 Apache 的服务器，只需要确保 .htacces 支持和 Mod_Rewrite 处于打开状态（一般都是打开的）；
|
||||
但如果你使用的是 Ngnix，IIS，亦或是其它不支持 .htaccess 的服务器，则需要根据下面的说明配置伪静态规则。
|
||||
|
||||
#### 伪静态配置
|
||||
|
||||
（待补）
|
||||
|
||||
## 下载 ph-Bookshelf
|
||||
|
||||
目前，唯一的官方获取 ph-Bookshelf 的方法是从 [GitHub 仓库][phb-repo]
|
||||
clone/下载 最新代码。
|
||||
|
||||
<!--
|
||||
|
||||
这里演示了使用服务器 ssh 安装 ph-Bookshelf 的方案
|
||||
|
||||
```
|
||||
$ cd /var/www/ # 进入你的服务器的网站根目录
|
||||
$ git clone --depth=1 git@github.com:Eyre-S/ph-Bookshelf # 从 GitHub 仓库获取最新代码
|
||||
$ mv ph-Bookshelf "<Name>" # 将 ph-Bookshelf 文件夹重命名为你想要的名字
|
||||
|
||||
```
|
||||
|
||||
-->
|
||||
|
||||
如果环境配置没有问题，那么现在这个站点就可以运行了...
|
||||
是的，运行结果还是 ERROR Not Found。
|
||||
|
||||
但现在你可以下载
|
||||
[预定义的 data 演示文件][demo-data]
|
||||
来提前查看效站点运行果了
|
||||
|
||||
[phb-repo]: https://github.com/suk-ws/ph-Bookshelf
|
||||
[demo-data]: https://srv.sukazyo.cc/resources/projects/ph-bookshelf/demo/data.zip
|
||||
12
olds/main.md
12
olds/main.md
@ -1,12 +0,0 @@
|
||||
这是一个基于 Gitbook 的简单的多 book 实现。
|
||||
|
||||
因为 web 相关的东西 Sukazyo 最熟悉的就是 php 了所以就用 php 写的。
|
||||
但是写出来的代码还是十分离谱的不易读的：各种调用交错在一起，前后端也交错在一起
|
||||
|
||||
而且也并不好用。
|
||||
|
||||
不过 Sukazyo 考虑到既然这么不好用，写一个使用说明大概就还挺必要的，反正也是随手的事情。
|
||||
|
||||
~~什么，你问示例站？这里不就是吗？~~
|
||||
|
||||
*这个项目还有[很多内容正在开发](/ph-bookshelf/plans)*
|
||||
@ -1,2 +0,0 @@
|
||||
待补充
|
||||
|
||||
@ -5,7 +5,7 @@ configurations:
|
||||
regex.highlight: 'true'
|
||||
---
|
||||
|
||||
# the ph-Bookshelf
|
||||
# <img src="/assets/ph-bookshelf.svg" alt='icon' class='em-height'> the ph-Bookshelf
|
||||
|
||||
|
||||
|
||||
|
||||
@ -2,10 +2,12 @@
|
||||
title: "ref: Prism - 支持的语言"
|
||||
---
|
||||
|
||||
[< Back](./code-highlight)
|
||||
<a href="javascript:history.go(-1)">< Back</a>
|
||||
|
||||
下面列出了包含它们的别名的，目前 Prism 支持的全部 297 个语言。通过定义 css 类型 language-xxxx（或 lang-xxxx）来使用 xxxx。
|
||||
|
||||
这个列表最后更新于 2023-03-28。更新的 Prism 版本或许已经支持了更多的语言。
|
||||
|
||||
> This is the list of all 297 languages currently supported by Prism, with their corresponding alias, to use in place of xxxx in the language-xxxx (or lang-xxxx) class:
|
||||
|
||||
<style>
|
||||
|
||||
@ -1,110 +0,0 @@
|
||||
---
|
||||
title: 代码高亮
|
||||
---
|
||||
|
||||
# <small>基于 Prism 的</small> 代码块高亮支持
|
||||
|
||||
[Prism]: https://prismjs.com/
|
||||
|
||||
ph-Bookshelf 默认基于 [Prism] 支持了代码块高亮，并开放了一些配置可以由你来调整一些代码块的显示样式。
|
||||
|
||||
## 使用 Prism 代码高亮
|
||||
|
||||
ph-Bookshelf 默认开启了 [Prism] 代码高亮支持，你可以将配置节点 `prism` 设置为 `false` 来关闭高亮支持。
|
||||
|
||||
在 Prism 已经开启的情况下，向代码块添加 css 类 `language-xxx` 或是 `lang-xxx` 即可为这个代码块进行高亮着色。
|
||||
|
||||
Prism 不会自动为所有代码块着色，所以不指定 `language-xxx` 即不会对代码块高亮。
|
||||
|
||||
你可以在页面 [ref: Prism - 支持的语言](./code-highlight-prism-supported-languages) 找到你可以使用的高亮语言列表。
|
||||
|
||||
## 配置高亮/代码块样式
|
||||
|
||||
// todo
|
||||
|
||||
## 添加 Prism 插件
|
||||
|
||||
ph-Bookshelf 还添加了可以方便的引入 Prism 的官方扩展插件的支持，你可以借此扩展代码高亮/代码块的使用方式。
|
||||
|
||||
只需要使用配置字段 `prism.plugins` 声明你需要的插件，每个语言名称之间通过 `;` 来分隔， ph-Bookshelf 即会自动加载这些插件。
|
||||
|
||||
ph-Bookshelf 可以合并不同位置的配置字段：所以在 *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 导入。
|
||||
|
||||
## Known issue - 已知问题
|
||||
|
||||
- prism `line-numbers` 插件会和 bread-card-markdown 的代码块样式表产生兼容性，导致行号无法正常显示。
|
||||
- 但是和它差不多的插件 `command-line` 是可以正常使用的。
|
||||
|
||||
---
|
||||
|
||||
## 你知道吗
|
||||
|
||||
ph-Bookshelf 本来是使用的 [highlight.js] 代码高亮库，在写这篇文档的时候，突然就更换为 [Prism] 库了。于是，你文档作者的 *50* 行 *1500* 多字**最终还没暖热乎就一点都没用上了**。
|
||||
|
||||
<small>至于那些带着冤魂的文档内容，它就在下面被注释掉的段落里。</small>
|
||||
|
||||
<!-- ---
|
||||
title: 代码块高亮
|
||||
--- -->
|
||||
|
||||
<!-- # <small>基于 highlight.js 的</small> 代码块高亮支持 -->
|
||||
|
||||
[highlight.js]: https://highlightjs.org/
|
||||
[使用介绍]: https://highlightjs.org/usage/
|
||||
<!-- [Markdown 属性语法]: https://todo -->
|
||||
|
||||
<!-- ph-Bookshelf 默认基于 [highlight.js] 支持了代码块高亮，并开放了一些配置可以由你来调整一些代码块的显示样式。
|
||||
|
||||
## 开关 highlight.js 高亮
|
||||
|
||||
ph-Bookshelf 默认开启了 [highlight.js] 高亮，你可以将配置节点 `highlightjs` 设置为 `false` 来关闭全局高亮。
|
||||
|
||||
*通过这种方式关闭 highlight.js 代码高亮将会让网页不再加载 highlight.js 的代码。除非你在文档内再次引入 hightlight.js 的代码，否则想要通过为代码块设置类型来单独打开它是不可能的。*
|
||||
|
||||
### 为单个代码块关闭高亮
|
||||
|
||||
[highlight.js] 默认支持了可以通过为代码块设置 CSS 类 `nohighlight` 来为这个代码块关闭高亮：
|
||||
|
||||
> **Ignoring a Code Block**
|
||||
>
|
||||
> To skip highlighting of a code block completely, use the nohighlight class:
|
||||
>
|
||||
> ```
|
||||
> <pre><code class="nohighlight">...</code></pre>
|
||||
> ```
|
||||
|
||||
在 ph-Bookshelf 的 Markdown 语法中，你可以简单的通过[Markdown 属性语法]的方式来关闭一个代码块的高亮。
|
||||
|
||||
<pre><code class="language-markdown">
|
||||
> 这个 nohighlight 属性将会直接添加到 <code> 标签当中（而不是更外层的 <pre> 标签）使其能够关闭代码块高亮
|
||||
{.nohighlight}
|
||||
```
|
||||
# some code..? here!
|
||||
```
|
||||
|
||||
> 出于一些原因，如果指定了语言，highlight.js 将会忽略掉 nohighlight 标签。所以这个代码块仍然会以 ini 语言被渲染高亮
|
||||
{.nohighlight}
|
||||
```ini
|
||||
# some code! here
|
||||
```</code></pre>
|
||||
|
||||
|
||||
## 配置高亮/代码块样式
|
||||
|
||||
|
||||
|
||||
## 添加更多的语言支持
|
||||
|
||||
ph-Bookshelf 默认引入的 highlight.js 仅引入了基础的高亮语法包：它基本上包括了大部分会使用到的语言<small>像是 *java*, *html*, *yaml*, *shell*, 甚至是 *scss* 等等</small>，但是有一些不太经常用到的语言例如 `apache-config` `ascii-doc` 等等，并未被包含在基础语法包当中。
|
||||
|
||||
对于需要使用到这些语言的情况，ph-Bookshelf 支持了一个 `highlightjs.languages` 配置节点，你可以在需要的地方使用这个配置节点添加你需要的语言包，ph-Bookshelf 将会在用户访问对应书籍/页面的时候加载这些语言的扩展插件使一些不在基础包中的语言也可以得到高亮支持。
|
||||
|
||||
`highlightjs.languages` 的值为一串你想要添加支持的语言，每个语言名称之间通过 `;` 来分隔。
|
||||
|
||||
ph-Bookshelf 可以合并不同位置添加的语言，所以在 *book.xml* 设置了 `haml; handlebars`，在页面内设置了 `mercury; sas` 后，最后在这个页面内，将会导入 `haml` `handlebars` `mercury` `sas` 四个语言。
|
||||
|
||||
内容a {.language-css}`.p { background-color: #123456; }` 内容b -->
|
||||
@ -4,6 +4,8 @@ configurations:
|
||||
regex.highlight: 'true'
|
||||
---
|
||||
|
||||
<a href="javascript:history.go(-1)">< Back</a>
|
||||
|
||||
[regex-colorizer]: https://github.com/suk-ws/regex-colorizer
|
||||
|
||||
ph-Bookshelf 通过 JavaScript 库<small>其实是自己写的脚本</small> [regex-colorizer] 支持了对正则表达式 RegEx 进行语法着色。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user