Compare commits
10 Commits
| Author | SHA1 | Date |
|---|---|---|
 A.C.Sukazyo Eyre
|
5c9cf4d4ae
|
|
|
A.C.Sukazyo Eyre
|
d901f626d4
|
|
|
A.C.Sukazyo Eyre
|
edc4fd1c9d
|
|
|
A.C.Sukazyo Eyre
|
3180fb75e9
|
|
|
A.C.Sukazyo Eyre
|
3e65a4c65e
|
|
|
A.C.Sukazyo Eyre
|
4d442fee37
|
|
|
A.C.Sukazyo Eyre
|
1e56cbb634
|
|
|
A.C.Sukazyo Eyre
|
7f73bc1c1a
|
|
|
A.C.Sukazyo Eyre
|
c374b0559a
|
|
|
A.C.Sukazyo Eyre
|
2736cb437e
|
39
book.xml
39
book.xml
|
|
@ -1,4 +1,37 @@
|
||||||
<Book id="ph-bookshelf" name="ph-Bookshelf Wiki">
|
<?xml version="1.0" encoding="UTF-8" ?>
|
||||||
<Page id="ph-bookshelf" name="the ph-Bookshelf" />
|
<Book
|
||||||
<Page id="web-server" name="Web 服务器配置" highlightjs.languages="apache"/>
|
xmlns="https://book.sukazyo.cc/"
|
||||||
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="
|
||||||
|
https://book.sukazyo.cc/ ../../assets/xsd/book.xsd
|
||||||
|
"
|
||||||
|
|
||||||
|
version="2.0"
|
||||||
|
>
|
||||||
|
|
||||||
|
<book_name>ph-Bookshelf Wiki</book_name>
|
||||||
|
|
||||||
|
<configurations>
|
||||||
|
<prism.plugins>autolinker</prism.plugins>
|
||||||
|
</configurations>
|
||||||
|
|
||||||
|
<contents>
|
||||||
|
|
||||||
|
<Page id="ph-bookshelf">the ph-Bookshelf</Page>
|
||||||
|
|
||||||
|
<Separator/>
|
||||||
|
|
||||||
|
<Title>Getting Started</Title>
|
||||||
|
<Page id="tutorial/get-started">开始使用</Page>
|
||||||
|
<Page id="tutorial/web-server">Web 服务器配置</Page>
|
||||||
|
|
||||||
|
<Separator />
|
||||||
|
|
||||||
|
<Title>Configurations</Title>
|
||||||
|
<Page id="configurations/bookshelf">书架/站点索引文件</Page>
|
||||||
|
<Page id="configurations/configurations">配置节点</Page>
|
||||||
|
<Page id="configurations/shelf-frontend-custom">自定义 CSS/JS</Page>
|
||||||
|
|
||||||
|
</contents>
|
||||||
|
|
||||||
</Book>
|
</Book>
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
*正在更新中*
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
# config.php
|
||||||
|
|
||||||
|
config.php 是一个用来为 ph-Bookshelf 设置 php 环境的脚本。
|
||||||
|
|
||||||
|
可以通过里面的字段来调整 ph-Bookshelf 的环境。
|
||||||
|
|
@ -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>
|
||||||
|
```
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 844 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 896 KiB |
|
|
@ -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 @@
|
||||||
待补充
|
|
||||||
|
|
||||||
|
|
@ -1,5 +1,71 @@
|
||||||
# ph-Bookshelf
|
---
|
||||||
|
title: "the ph-Bookshelf"
|
||||||
|
configurations:
|
||||||
|
prism: 'true'
|
||||||
|
regex.highlight: 'true'
|
||||||
|
---
|
||||||
|
|
||||||
|
# <img src="/assets/ph-bookshelf.svg" alt='icon' class='em-height'> the ph-Bookshelf
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<progress max=100 value=45>45%</progress>
|
<div align=center>
|
||||||
|
|
||||||
|
另一个可以搭建 *很多个* 电子书的网站系统
|
||||||
|
<small>除了好看点之外一无是处</small>
|
||||||
|
|
||||||
|
**Wiki** & **Demo**[^1] | [Repository]
|
||||||
|
|
||||||
|
[Repository]: https://github.com/suk-ws/ph-Bookshelf
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
[^1]: 你正在访问的这个网站就是 Demo（合理）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
一个可以在单一站点上放一大堆书目的电子书（文档？）托管项目——我们把它称之为书架。
|
||||||
|
|
||||||
|
每个书目就像是 GitBook 的一本书一样 —— 不过使用 `book.xml` 来定义书籍的目录；书架站点使用 `bookshelf.xml` 来管理书目和一些特色设置。
|
||||||
|
|
||||||
|
## 特色功能
|
||||||
|
|
||||||
|
- 可以在这一个站点上放置很多很多个文档：可以通过左上角的 Books 列出访问书目。
|
||||||
|
- [CommonMark] 规范的完全支持。
|
||||||
|
- 以及 GitHub 文档特色功能的支持！
|
||||||
|
- 可以很开心的写内联 HTML/CSS/JS！
|
||||||
|
- 基于 [`# Prism`{.lang-shell-session}][prism] 的[代码高亮]
|
||||||
|
- 甚至还能够[按需引入 Prism 插件][prism-plugin]
|
||||||
|
- 还有特色的 [`/([R-egE-x])\w+/`{.regex} 着色][regex]
|
||||||
|
- 有趣的特色功能像是 《<a id="rolling">滚来滚去的标题栏</a>》
|
||||||
|
- 有趣的特色功能像是 ← 彩虹色的列表头
|
||||||
|
- 彩
|
||||||
|
- 虹
|
||||||
|
- 色
|
||||||
|
- ！~
|
||||||
|
- 的
|
||||||
|
- 哦
|
||||||
|
- 前端设计使用 Bread Card Design[^2] 设计语言，简洁，好看，~~除了好看点之外一无是处~~
|
||||||
|
- 基于 MIT [开源][Repository]
|
||||||
|
- 使用 PHP <small>~~: 世界上最好的语言~~</small> 以及 PHP Composer 搭建
|
||||||
|
- ~~一大堆的 0day 漏洞！~~
|
||||||
|
- ~~只有上帝才能看得懂的代码~~
|
||||||
|
|
||||||
|
[^2]: Bread Card Design 是一个以淡色无阴影的简单卡片为特色的设计语言。目前，还没有设计语言主页。
|
||||||
|
|
||||||
|
[CommonMark]: https://commonmark.thephpleague.com/
|
||||||
|
[prism]: https://prismjs.com
|
||||||
|
[代码高亮]: ./tools/code-highlight
|
||||||
|
[prism-plugin]: http://book.localhost/ph-bookshelf/tools/code-highlight#%E6%B7%BB%E5%8A%A0-prism-%E6%8F%92%E4%BB%B6
|
||||||
|
[regex]: ./tools/regex-highlight
|
||||||
|
|
||||||
|
<script>
|
||||||
|
function roll_rolling () {
|
||||||
|
var title = document.getElementById("rolling").innerText;
|
||||||
|
const start = title[0];
|
||||||
|
title = title.substring(1);
|
||||||
|
title += start;
|
||||||
|
document.getElementById("rolling").innerText = title;
|
||||||
|
setTimeout(roll_rolling, 450);
|
||||||
|
} roll_rolling();
|
||||||
|
</script>
|
||||||
|
|
|
||||||
BIN
preview.png
BIN
preview.png
Binary file not shown.
|
Before Width: | Height: | Size: 133 KiB After Width: | Height: | Size: 429 KiB |
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1,60 @@
|
||||||
|
---
|
||||||
|
title: RegEx 高亮着色
|
||||||
|
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 进行语法着色。
|
||||||
|
|
||||||
|
能够达成像下面一样的着色效果：
|
||||||
|
|
||||||
|
{.regex}
|
||||||
|
```
|
||||||
|
^(?:https?://)?((?:(?:c\.)?vx|fx|www\.)?twitter\.com)/((\w{1,})/status/(\d+)(?:/photo/(\d+))?)/?(\?[\w&=-]+)?$
|
||||||
|
|
||||||
|
\92\1^\d{0,3,5}\n{9c}\b{0,2}(\b{,5}){3})\01{}\2{,}\001${0,}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 开启与使用功能
|
||||||
|
|
||||||
|
ph-Bookshelf 默认开启了通过 [regex-colorizer] 进行的 RegEx 高亮着色，你可以通过将 `regex.highlight` 设置为 `false` 来关闭它。
|
||||||
|
|
||||||
|
[regex-colorizer] 的默认配置将会自动着色所有包含 css 类 `regex` 的内联代码和代码块，只需要为内容为正则表达式的代码块声明 `regex` 类型即可使用：
|
||||||
|
|
||||||
|
{.lang-markdown}
|
||||||
|
像是 `^[0-9a-z]+这样子$`{.regex} 即可。
|
||||||
|
|
||||||
|
{.regex}
|
||||||
|
```
|
||||||
|
^或者对于代码块而言\.+$
|
||||||
|
```
|
||||||
|
|
||||||
|
<code class=regex>或者\.\.\. HTML 方式[\.\?]?</code>
|
||||||
|
|
||||||
|
> 像是 `^[0-9a-z]+这样子$`{.regex} 即可。
|
||||||
|
>
|
||||||
|
> {.regex}
|
||||||
|
> ```
|
||||||
|
> ^或者对于代码块而言\.+$
|
||||||
|
> ```
|
||||||
|
> <code class=regex>或者\.\.\. HTML 方式[\.\?]?</code>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prism 的代码高亮
|
||||||
|
|
||||||
|
其实 [Prism 的代码高亮](./code-highlight)也可以高亮着色 RegEx。尽管两者的高亮样式还挺不一样的。
|
||||||
|
|
||||||
|
以下是使用 Prism 的 `regex` 语言进行高亮的的 RegEx 效果：
|
||||||
|
|
||||||
|
```regex
|
||||||
|
^(?:https?://)?((?:(?:c\.)?vx|fx|www\.)?twitter\.com)/((\w{1,})/status/(\d+)(?:/photo/(\d+))?)/?(\?[\w&=-]+)?$
|
||||||
|
|
||||||
|
\92\1^\d{0,3,5}\n{9c}\b{0,2}(\b{,5}){3})\01{}\2{,}\001${0,}
|
||||||
|
```
|
||||||
|
|
||||||
|
两者其实并不冲突（一个使用了 css 类型 `regex`，而一个是 `lang-regex` / `language-regex`）。你可以选择一个你喜欢的使用。
|
||||||
|
|
@ -0,0 +1,200 @@
|
||||||
|
---
|
||||||
|
title: 开始使用
|
||||||
|
configurations:
|
||||||
|
prism.plugins: 'command-line; treeview'
|
||||||
|
---
|
||||||
|
---
|
||||||
|
|
||||||
|
跟随下面的指导，你将可以手动安装运行 ph-Bookshelf。
|
||||||
|
|
||||||
|
## 安装配置 Web 服务器以及 PHP 运行时
|
||||||
|
|
||||||
|
首先，在你的服务器上安装并配置好一台 Web 服务器。尽管任意的支持 URL 重写的 Web 服务器都可以使用，我们推荐 Apache2，它是 ph-Bookshelf 维护者进行和部署的首选环境。
|
||||||
|
|
||||||
|
安装完成后，参考 [Web Server 配置](./web-server)来进行一些额外设置。
|
||||||
|
|
||||||
|
然后，安装 PHP 运行环境并配置 Web 服务器以支持 PHP。
|
||||||
|
|
||||||
|
> ph-Bookshelf 使用的是几乎最新版本的 php 8.2。然而很多的主流服务器的默认仓库会安装的 php 版本都要更旧。所以安装的时候，注意 PHP 版本不要低于 8.2。
|
||||||
|
>
|
||||||
|
> <pre
|
||||||
|
> class="command-line"
|
||||||
|
> data-output="2-5"
|
||||||
|
> ><code class="lang-bash"
|
||||||
|
> >php -v
|
||||||
|
> PHP 8.2.4 (cli) (built: Mar 16 2023 14:37:38) (NTS)
|
||||||
|
> Copyright (c) The PHP Group
|
||||||
|
> Zend Engine v4.2.4, Copyright (c) Zend Technologies
|
||||||
|
> with Zend OPcache v8.2.4, Copyright (c), by Zend Technologies</code></pre>
|
||||||
|
|
||||||
|
## 配置网站代码
|
||||||
|
|
||||||
|
将 ph-Bookshelf 的[源代码][source]克隆到你的 Web 根目录，然后，使用 [composer] 来为 ph-Bookshelf 安装依赖：
|
||||||
|
|
||||||
|
[source]: https://github.com/suk-ws/ph-Bookshelf
|
||||||
|
[composer]: https://getcomposer.org/download/
|
||||||
|
|
||||||
|
<pre
|
||||||
|
class="command-line"
|
||||||
|
data-user="root"
|
||||||
|
data-output="2-8, 14-19, 21-52"
|
||||||
|
><code class="lang-bash"
|
||||||
|
>git clone https://github.com/suk-ws/ph-bookshelf.git ph-bookshelf
|
||||||
|
Cloning into 'ph-bookshelf'...
|
||||||
|
remote: Enumerating objects: 860, done.
|
||||||
|
remote: Counting objects: 100% (390/390), done.
|
||||||
|
remote: Compressing objects: 100% (234/234), done.
|
||||||
|
remote: Total 860 (delta 212), reused 314 (delta 144), pack-reused 470
|
||||||
|
Receiving objects: 100% (860/860), 822.58 KiB | 2.09 MiB/s, done.
|
||||||
|
Resolving deltas: 100% (461/461), done.
|
||||||
|
cd ph-bookshelf
|
||||||
|
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
|
||||||
|
php -r "if (hash_file('sha384', 'composer-setup.php') === '55ce33d7678c5a611085589f1f3ddf8b3c52d662cd01d4ba75c0ee0459970c2200a51f492d557530c71c15d8dba01eae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
|
||||||
|
php composer-setup.php
|
||||||
|
php -r "unlink('composer-setup.php');"
|
||||||
|
Installer verified
|
||||||
|
All settings correct for using Composer
|
||||||
|
Downloading...
|
||||||
|
|
||||||
|
Composer (version 2.5.5) successfully installed to: /home/sukazyo/composer.phar
|
||||||
|
Use it: php composer.phar
|
||||||
|
php composer.phar install
|
||||||
|
Installing dependencies from lock file (including require-dev)
|
||||||
|
Verifying lock file contents can be installed on current platform.
|
||||||
|
Package operations: 13 installs, 0 updates, 0 removals
|
||||||
|
- Downloading symfony/polyfill-mbstring (v1.27.0)
|
||||||
|
- Downloading gregwar/rst (v1.0.6)
|
||||||
|
- Downloading symfony/polyfill-php80 (v1.27.0)
|
||||||
|
- Downloading symfony/deprecation-contracts (v3.2.0)
|
||||||
|
- Downloading psr/event-dispatcher (1.0.0)
|
||||||
|
- Downloading nette/utils (v4.0.0-RC3)
|
||||||
|
- Downloading nette/schema (v1.2.3)
|
||||||
|
- Downloading dflydev/dot-access-data (v3.0.2)
|
||||||
|
- Downloading league/config (v1.2.0)
|
||||||
|
- Downloading league/commonmark (2.3.8)
|
||||||
|
- Downloading symfony/polyfill-ctype (v1.27.0)
|
||||||
|
- Downloading symfony/yaml (v6.2.5)
|
||||||
|
- Downloading xemlock/php-latex (dev-master d60bf4c)
|
||||||
|
- Installing symfony/polyfill-mbstring (v1.27.0): Extracting archive
|
||||||
|
- Installing gregwar/rst (v1.0.6): Extracting archive
|
||||||
|
- Installing symfony/polyfill-php80 (v1.27.0): Extracting archive
|
||||||
|
- Installing symfony/deprecation-contracts (v3.2.0): Extracting archive
|
||||||
|
- Installing psr/event-dispatcher (1.0.0): Extracting archive
|
||||||
|
- Installing nette/utils (v4.0.0-RC3): Extracting archive
|
||||||
|
- Installing nette/schema (v1.2.3): Extracting archive
|
||||||
|
- Installing dflydev/dot-access-data (v3.0.2): Extracting archive
|
||||||
|
- Installing league/config (v1.2.0): Extracting archive
|
||||||
|
- Installing league/commonmark (2.3.8): Extracting archive
|
||||||
|
- Installing symfony/polyfill-ctype (v1.27.0): Extracting archive
|
||||||
|
- Installing symfony/yaml (v6.2.5): Extracting archive
|
||||||
|
- Installing xemlock/php-latex (dev-master d60bf4c): Extracting archive
|
||||||
|
Generating autoload files
|
||||||
|
7 packages you are using are looking for funding.
|
||||||
|
Use the `composer fund` command to find out more!
|
||||||
|
</code></pre>
|
||||||
|
|
||||||
|
如果你遇到了以下的报错：
|
||||||
|
|
||||||
|
```text
|
||||||
|
Problem 1
|
||||||
|
- Root composer.json requires PHP extension ext-dom * but it is missing from your system. Install or enable PHP's dom extension.
|
||||||
|
Problem 2
|
||||||
|
- xemlock/php-latex is locked to version dev-master and an update of this package was not requested.
|
||||||
|
- xemlock/php-latex dev-master requires ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.
|
||||||
|
Problem 3
|
||||||
|
- xemlock/php-latex dev-master requires ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.
|
||||||
|
- xemlock/php-latex is locked to version dev-master and an update of this package was not requested.
|
||||||
|
|
||||||
|
To enable extensions, verify that they are enabled in your .ini files:
|
||||||
|
- /etc/php/8.2/cli/php.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/10-opcache.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/10-pdo.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-calendar.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-ctype.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-curl.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-exif.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-ffi.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-fileinfo.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-ftp.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-gettext.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-iconv.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-mbstring.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-phar.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-posix.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-readline.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-shmop.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-sockets.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-sysvmsg.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-sysvsem.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-sysvshm.ini
|
||||||
|
- /etc/php/8.2/cli/conf.d/20-tokenizer.ini
|
||||||
|
You can also run `php --ini` in a terminal to see which files are used by PHP in CLI mode.
|
||||||
|
Alternatively, you can run Composer with `--ignore-platform-req=ext-xml --ignore-platform-req=ext-dom` to temporarily ignore these required extensions.
|
||||||
|
```
|
||||||
|
|
||||||
|
尝试安装 php 插件 `xml` 来解决问题。
|
||||||
|
|
||||||
|
> 对于不同的 php 安装方式，安装插件的方式也会有不同。如果你和我一样都是在 Debian 上通过仓库安装的最新版 php，可以通过 apt 来安装 php 插件：`# apt install php-xml`{.lang-shell-session}。如果你是用的是其它的安装方式，尝试搜索 *php enable extension xml* 来解决这类问题。
|
||||||
|
|
||||||
|
## 配置网站安全设置
|
||||||
|
|
||||||
|
*我们正在努力在代码层面实现保护以避免任何形式的攻击*
|
||||||
|
|
||||||
|
ph-bookshelf 默认并不会对能够打开的文件路径做出限制。这意味着在生产服务器上，你最好通过 PHP 的 [`open_basedir`](https://www.php.net/manual/en/ini.core.php#ini.open-basedir) 设置网站所能够访问的路径，以避免路径构建攻击。
|
||||||
|
|
||||||
|
最简单的方式，就是通过在网站根目录放置 `.user.ini` 文件并在此处设置 `open_basedir` 属性：
|
||||||
|
|
||||||
|
```ini
|
||||||
|
open_basedir = /path/to/your/ph-bookshelf
|
||||||
|
```
|
||||||
|
|
||||||
|
当然，这个属性也可以在 Apache 服务配置器中设置，像以下这样：
|
||||||
|
```apacheconf
|
||||||
|
<VirtualHost _default_:443>
|
||||||
|
|
||||||
|
ServerName book.example.com
|
||||||
|
DocumentRoot /path/to/your/ph-bookshelf
|
||||||
|
|
||||||
|
# ...any others
|
||||||
|
|
||||||
|
php_admin_value open_basedir /path/to/your/ph-bookshelf
|
||||||
|
|
||||||
|
# ...any others
|
||||||
|
|
||||||
|
</VirtualHost>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 如果你使用了软链接
|
||||||
|
|
||||||
|
`open_basedir` 会解析文件的绝对链接然后进行访问控制，这意味着，如果你的网站，或者是你的 `/data` 目录是通过软连接挂载进来的，你需要在 `open_basedir` 里面添加上软链接的目标目录。
|
||||||
|
|
||||||
|
For example, 如果你的目录结构像是以下这样：
|
||||||
|
```treeview
|
||||||
|
/
|
||||||
|
|-- path/
|
||||||
|
| └── to/
|
||||||
|
| └── your/
|
||||||
|
| └── ph-bookshelf
|
||||||
|
| |-- .user.ini
|
||||||
|
| |-- .htaccess
|
||||||
|
| |-- index.php
|
||||||
|
| |-- data/ -> /data-drive/books
|
||||||
|
| └── ...
|
||||||
|
└── data-drive/
|
||||||
|
└── books/
|
||||||
|
└── bookshelf.xml
|
||||||
|
└── ...
|
||||||
|
```
|
||||||
|
|
||||||
|
那么你将需要这样设置 `open_basedir`
|
||||||
|
```ini
|
||||||
|
open_basedir = /path/to/your/ph-bookshelf:data-drive/books
|
||||||
|
```
|
||||||
|
|
||||||
|
## 完成搭建
|
||||||
|
|
||||||
|
配置完成上面这些之后，你就可以将 `/path/to/your/ph-bookshelf` 作为你的 Web 服务器根目录来建立一个站点，至此，你已经完成了 ph-Bookshelf 站点的搭建。
|
||||||
|
|
||||||
|
现在，在 `/path/to/your/ph-bookshelf/data` 目录下，你可以去配置你的 bookshelf.xml 和各种书籍了。
|
||||||
|
|
||||||
|
*data 模板正在 WIP 当中* <!-- todo -->
|
||||||
|
|
@ -0,0 +1,71 @@
|
||||||
|
---
|
||||||
|
configurations:
|
||||||
|
prism.plugins: 'command-line'
|
||||||
|
---
|
||||||
|
|
||||||
|
# Web Server
|
||||||
|
|
||||||
|
[Apache]: https://httpd.apache.org/
|
||||||
|
[.htaccess]: https://httpd.apache.org/docs/2.4/howto/htaccess.html
|
||||||
|
[mod_rewrite]: https://httpd.apache.org/docs/current/mod/mod_rewrite.html
|
||||||
|
|
||||||
|
ph-Bookshelf 原始版本是在 [Apache Web Server][Apache] 环境下开发的，并有用到 [Apache] 的 [.htaccess]。
|
||||||
|
|
||||||
|
你也可以在其它的环境下使用 **ph-Bookshelf**，只需要一些简单的路径重写设置。
|
||||||
|
|
||||||
|
## 对于你自己管理的的 Apache 服务器
|
||||||
|
|
||||||
|
要想在 [Apache] 中使用 **ph-Bookshelf**，你只需要确认一些简单的设置：
|
||||||
|
|
||||||
|
确认 [mod_rewrite] 已经打开。这一般可以通过以下简单的命令确认：
|
||||||
|
|
||||||
|
<pre
|
||||||
|
class="command-line"
|
||||||
|
data-user="root"
|
||||||
|
data-output="2-4, 6"
|
||||||
|
><code class="lang-bash"
|
||||||
|
>a2enmod rewrite
|
||||||
|
Enabling module rewrite.
|
||||||
|
To activate the new configuration, you need to run:
|
||||||
|
service apache2 restart
|
||||||
|
a2enmod rewrite
|
||||||
|
Module rewrite already enabled</code></pre>
|
||||||
|
|
||||||
|
> 如果你使用的是旧版 Apache<small>一般存在于会被叫做 httpd 的 apache</small>，module 配置或许会在服务器里，这时候，大概你的 Apache 的配置文件（通常为 `/etc/apache2/httpd.conf`{.lang-url} 或者 `/etc/httpd/httpd.conf`{.lang-url}），找到以下行并取消注释它：
|
||||||
|
>
|
||||||
|
> ```apacheconf
|
||||||
|
> # uncomment this line
|
||||||
|
> LoadModule rewrite_module libexec/apache2/mod_rewrite.so
|
||||||
|
> ```
|
||||||
|
|
||||||
|
然后，为你的 ph-Bookshelf 目录配置允许路径重写：
|
||||||
|
|
||||||
|
```apacheconf
|
||||||
|
<Directory /path/to/your/ph-bookshelf>
|
||||||
|
AllowOverride All
|
||||||
|
</Directory>
|
||||||
|
```
|
||||||
|
|
||||||
|
至此，你已经完成了 ph-Bookshelf 需要的所有配置。
|
||||||
|
|
||||||
|
你无需在 [Apache] 配置文件中配置路径重写规则，它已经存在在了 ph-Bookshelf 项目根目录下的 .htaccess 当中。
|
||||||
|
|
||||||
|
## 对于 Nginx 或其它各种各样的 Web 服务器
|
||||||
|
|
||||||
|
一般的 Web 服务器都支持 URL 重写，但它们可能有自己的配置方式。
|
||||||
|
|
||||||
|
你可以参考 ph-bookshelf 项目下的 `.htaccess` 文件，在你的 Web 服务器配置上面自己配置 URL 重写规则。
|
||||||
|
|
||||||
|
> 作为参考，这是 ph-bookshelf 在 Nginx 下的 URL 重写规则：
|
||||||
|
>
|
||||||
|
> ```nginx
|
||||||
|
> location / {
|
||||||
|
> rewrite ^(.*)$ /index.php?p=$0;
|
||||||
|
> }
|
||||||
|
> ```
|
||||||
|
>
|
||||||
|
> 在 nginx 中，将这一部分添加到你的 `server {}`{.lang-nginx} 块中就可以完成配置。
|
||||||
|
|
||||||
|
## 对于使用 php 网站托管服务的用户
|
||||||
|
|
||||||
|
如果你是使用 php 站点托管，请询问你的托管服务商是否支持 [Apache] [.htaccess] 的使用。
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
# Web Server
|
|
||||||
|
|
||||||
[Apache]: https://httpd.apache.org/
|
|
||||||
[.htaccess]: https://httpd.apache.org/docs/2.4/howto/htaccess.html
|
|
||||||
[mod_rewrite]: https://httpd.apache.org/docs/current/mod/mod_rewrite.html
|
|
||||||
|
|
||||||
ph-Bookshelf 原始版本是在 [Apache Web Server][Apache] 环境下开发的，并有用到 [Apache] 的 [.htaccess]。
|
|
||||||
|
|
||||||
你也可以在其它的环境下使用 **ph-Bookshelf**，只需要一些简单的路径重写设置。
|
|
||||||
|
|
||||||
## Apache
|
|
||||||
|
|
||||||
要想在 [Apache] 中使用 **ph-Bookshelf**，你只需要确认一些简单的设置：
|
|
||||||
|
|
||||||
确认 [mod_rewrite] 已经打开。这一般可以通过以下简单的命令确认：
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# a2enmod rewrite
|
|
||||||
```
|
|
||||||
|
|
||||||
> 如果你使用的是旧版 Apache<small>一般存在于会被叫做 httpd 的 apache</small>，module 配置或许会在服务器里，这时候，大概你的 Apache 的配置文件（通常为 /etc/apache2/httpd.conf 或者 /etc/httpd/httpd.conf），找到以下行并取消注释它：
|
|
||||||
>
|
|
||||||
> ```apache
|
|
||||||
> # uncomment this line
|
|
||||||
> LoadModule rewrite_module libexec/apache2/mod_rewrite.so
|
|
||||||
> ```
|
|
||||||
|
|
||||||
然后，为你的 ph-Bookshelf 目录配置允许路径重写：
|
|
||||||
|
|
||||||
```apache
|
|
||||||
<Directory /path/to/your/ph-Bookshelf>
|
|
||||||
AllowOverride All
|
|
||||||
</Directory>
|
|
||||||
```
|
|
||||||
|
|
||||||
至此，你已经完成了 ph-Bookshelf 需要的所有配置。
|
|
||||||
|
|
||||||
你无需在 [Apache] 配置文件中配置路径重写规则，它已经存在在了 ph-Bookshelf 项目根目录下的 .htaccess 当中。
|
|
||||||
|
|
||||||
> 如果你是使用 php 站点托管，请询问你的托管服务商是否支持 [Apache] [.htaccess] 的使用。
|
|
||||||
Loading…
Reference in New Issue