Skip to content

Commit

Permalink
docs: write site config
Browse files Browse the repository at this point in the history
  • Loading branch information
@ourai
ourai committed Mar 25, 2023
1 parent e70fa77 commit c8c26d5
Show file tree
Hide file tree
Showing 10 changed files with 135 additions and 74 deletions.
1 change: 1 addition & 0 deletions man/cookbook/apis/page-config/entity.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: 页面配置
10 changes: 10 additions & 0 deletions man/cookbook/apis/page-config/readme.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
页面配置即定义在 Front Matter 中的变量，除了会用到静态网站生成器预定义与约定俗成的变量之外，本主题也自定义了一些——

## SEO

影响生成 SEO 相关信息的变量：

| 变量名 | 值类型/可选值 | 说明 |
| --- | --- | --- | --- |
| `ksio_seo_title` | `string` | 显示在 `<title>` 中的页面标题，不指定则使用 `title` |
| `ksio_seo_role` | `'writer' | 'developer'` | 根据角色生成特定的页面描述 |
170 changes: 104 additions & 66 deletions man/cookbook/apis/site-config/readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,124 +1,162 @@
在 `_config.yml` 文件中声明的用于控制主题预置渲染逻辑的配置项，它们都挂在 `ksio` 下面，通过 `site.ksio` 访问——
在网站配置文件中声明的用于控制主题预置渲染逻辑的配置项，整体是个多层嵌套的对象，在本文档中的表现形式为：

配置项「值类型」有 `Link` 字样的，代表 `Link` 是一个描述链接信息的对象，用 TypeScript 的类型表现为：
1. 一级属性会作为二级标题，然后紧接着是对其的简单说明；
2. 二级属性列在表格中，若需要更为详细的解释，则会另起三级标题；
3. 三级及以下层级的属性会以 TypeScript 的类型定义的方式呈现。

{% highlight typescript %}
当配置项「值类型」有 `Link` 字样的，代表 `Link` 是一个描述链接信息的对象：

```typescript
interface Link {
text: string;
url?: string;
children?: Link[];
}
{% endhighlight %}

可用配置项有：

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `master` | `object` | - | 站长信息，[详见下方](#master) |
| `meta` | `object` | - | 网站信息，[详见下方](#meta) |
| `brand` | `object` | - | 品牌相关配置，主要控制页头左上角的链接与文本，[详见下方](#brand) |
| `copyright` | `object` | - | 网站版权声明，[详见下方](#copyright) |
| `header` | `object` | - | 页面头部，[详见下方](#header) |
| `footer` | `object` | - | 页面底部，[详见下方](#footer) |
| `social` | `object` | - | 社交相关功能的开关与配置，[详见下方](#social) |
| `seo` | `object` | - | SEO 相关配置，[详见下方](#seo) |
| `statistic` | `object` | - | 数据统计相关配置，[详见下方](#statistic) |
```

## `master`

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | `site.author.name` | 站长名称 |

## `meta`

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | - | 网站发布后的访问链接 |
为方便查找，以下内容按字母顺序排列——

## `brand`

品牌相关配置，主要控制页头左上角的链接与文本。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | `site.title` | 当前网站品牌所要显示的文本，不指定则显示网站标题 |
| `color` | `string` | - | 品牌主题色，[详见下方](#color) |
| `icon` | `string` | `'ksio/favicon.ico'` | 品牌图标，[详见下方](#icon) |
| `parent` | `Link` | - | 当前网站的父品牌，指定后会在当前网站品牌的左边显示 |
| `text` | `string` | 网站标题 | 当前网站品牌所要显示的文本，不指定则显示网站标题 |

### `color`

设置之后，会在 `<head>` 标签内生成 [`<meta name="theme-color" content="指定主题色">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color){:target="_blank"}{:rel="external "}。

### `icon`

除了会通过 `<link rel="icon" href="指定图标">` 显示在网页浏览器标签中以外，还会用于 SEO 等其他信息中。

## `copyright`

网站版权声明。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `fragments` | `string` | - | 显示在版权声明右侧的额外信息，[详见下方](#fragments) |
| `owner` | `Link` | - | 版权所有人，默认使用网站标题与地址 |
| `period` | `object` | - | 有效期间，[详见下方](#period) |
| `period` | `CopyrightPeriod` | - | 有效期间，[详见下方](#period) |
| `provider` | `boolean` | `true` | 是否显示主题与提供者声明 |

### `period`
### `fragments`

值是可以包含 HTML 的字符串，最好每段内容都包含在 `<p>` 标签中，相邻的 `<p>` 标签之间会显示一个垂直的分隔符。

结构、默认值与说明如下：
若 `provider` 没设为 `false`，整个内容会显示在主题与提供者声明右侧。

{% highlight js %}
{
start: 当前年份, // 起始时间，一般只有年份
### `period`

```typescript
interface CopyrightPeriod {
start?: Date | string | number; // 起始时间，一般只有年份，默认使用网站构建时间
}
{% endhighlight %}
```

## `footer`

页面底部。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `links` | `Link[]` | - | 页面底部链接 |
| `partial` | `string` | `'ksio/footer.html'` | 预置布局模板中页脚部分，可指定自定义的替换主题预置的 |

## `header`

页面头部。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `partial` | `string` | `'ksio/header.html'` | 预置布局模板中页头部分，可指定自定义的替换主题预置的 |
| `navbar` | `HeaderNavBar` | - | 页头导航栏，[详见下方](#navbar) |
| `navs` | `Link[]` | - | 页面头部导航 |
| `navbar` | `object` | - | 页头导航栏，[详见下方](#navbar) |
| `partial` | `string` | `'ksio/header.html'` | 预置布局模板中页头部分，可指定自定义的替换主题预置的 |

### `navbar`

结构、默认值与说明如下：

{% highlight js %}
{
placement: 'left', // 导航菜单显示位置
```typescript
interface HeaderNavBar {
placement?: 'left' | 'right'; // 导航菜单显示位置，默认为 `'left'`
}
{% endhighlight %}

## `footer`
```

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `partial` | `string` | `'ksio/footer.html'` | 预置布局模板中页脚部分，可指定自定义的替换主题预置的 |
| `links` | `Link[]` | - | 页面底部链接 |
## `master`

## `social`
站长信息。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `feed` | `object` | - | feed 订阅功能，[详见下方](#feed) |
| `share` | `boolean` | `false` | 是否启用将页面分享到其他 SNS 的按钮 |
| `comment` | `object` | - | 评论功能，[详见下方](#comment) |
| `name` | `string` | - | 站长名称，[详见下方](#name) |

### `feed`
### `name`

结构、默认值与说明如下：
在使用 Jekyll 时，一般会在网站配置文件中定义一个 `author`，因此在 Jekyll 中使用本主题时若没指定 `name` 则会使用 `site.author.name`。

{% highlight js %}
{
rss: false, // 是否生成 RSS feed
atom: false, // 是否生成 Atom feed
}
{% endhighlight %}
## `meta`

### `comment`
网站信息。

待补充。
| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | - | 网站发布后的访问链接 |

## `seo`

SEO 相关配置。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `suffix` | `boolean` | `true` | 是否在 `<title>` 中将站名作为后缀拼接 |

## `social`

社交相关功能的开关与配置。

| 属性名 | 值类型/可选值 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `comment` | `SocialComment` | - | 评论功能，[详见下方](#comment) |
| `feed` | `SocialFeed` | - | feed 订阅功能，[详见下方](#feed) |
| `share` | `boolean` | `true` | 是否启用将页面分享到其他 SNS 的按钮 |

### `comment`

```typescript
interface SocialComment {
// Disqus
disqus?: {
shortname: string; // Disqus 上注册的网站名
// 以下几个配置项是在无法加载 Disqus 的情况下的代理，
// 默认为 DisqusJS（详见 https://disqusjs.skk.moe/）
proxy?: {
endpoint: string; // 用于 DisqusJS 的 `api` 配置项
key: string; // 用于 DisqusJS 的 `apikey` 配置项
};
username?: string; // 用于 DisqusJS 的 `admin` 配置项
label?: string; // 用于 DisqusJS 的 `adminLabel` 配置项
};
// 多说
duoshuo?: {
shortname?: string;
};
}
```

### `feed`

```typescript
interface SocialFeed {
rss?: boolean; // 是否生成 RSS feed，默认为 `false`，会用到 `meta.url`
atom?: boolean; // 是否生成 Atom feed，默认为 `false`
}
```

## `statistic`

待补充。
数据统计相关配置，待补充。
Binary file added src/jekyll/_assets/images/local/pages/theme-provider.jpg
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 0 additions & 2 deletions src/jekyll/_config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,5 +169,3 @@ ksio:
url: /about/
- text: 资助
url: /about/#donation
social:
share: true
1 change: 1 addition & 0 deletions src/jekyll/_data/local/repos.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,5 @@ cookbook:
collection: apis
items:
- site-config
- page-config
- html-reuse
2 changes: 1 addition & 1 deletion src/jekyll/_includes/ksio/meta/seo.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@

{% assign role_type = page.ksio_seo_role %}
{% assign master_name = ksio_master.name | default: site.author.name %}
{% if role_type == "author" %}
{% if role_type == "writer" %}
{% assign posts = site.posts %}
{% assign first_post_year = posts.last.date | date: "%Y" %}
{% assign last_post_year = posts.first.date | date: "%Y" %}
Expand Down
6 changes: 3 additions & 3 deletions src/jekyll/_includes/ksio/widgets/disqus.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@
identifier: '{{ page.url }}',
url: 'https://' + location.host + '{{ page.url }}',
title: '{{ page.title }}',
api: '{{ comment_config.api.endpoint }}',
apikey: '{{ comment_config.api.key }}',
api: '{{ comment_config.proxy.endpoint }}',
apikey: '{{ comment_config.proxy.key }}',
admin: '{{ comment_config.username }}',
adminLabel: '{{ comment_config.label | default: "鹳狸猿" }}'
adminLabel: '{{ comment_config.label | default: "管理员" }}'
});
</script>
{% else %}
Expand Down
2 changes: 1 addition & 1 deletion src/jekyll/_includes/ksio/widgets/share.html
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{% if site.ksio.social.share == true %}
{% if site.ksio.social.share != false %}
<div class="Widget Widget--share">
<div class="Widget-body">
<p>分享到<i class="fa fa-share-alt"></i></p>
Expand Down
15 changes: 14 additions & 1 deletion src/jekyll/_pages/guides.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,23 @@ permalink: /guides/

## 使用

虽说本主题源码开源并免费使用，但还是希望能够在使用时保留主题和作者的名字与来源；如果可以，请在网站底部（即 `footer` 中）加上如下 HTML 代码：
虽说本主题源码开放并免费使用，但还是希望能够在使用时保留主题和提供者的名字与来源——

在使用时，默认会在页面底部（即 `footer` 中）的版权声明右边显示主题和提供者的名字与来源相关信息：

<figure>
<img src="{{ 'local/pages/theme-provider' | asset_path }}" alt="主题提供者声明">
<figcaption>主题提供者声明</figcaption>
</figure>

但这并非强制显示，可通过在[网站配置]({{ site.baseurl }}/apis/site-config/)文件中将 [`ksio.copyright.provider`]({{ site.baseurl }}/apis/site-config/#copyright) 设为 `false` 以关闭显示；或把 [`ksio.footer.partial`]({{ site.baseurl }}/apis/site-config/#footer) 改为自定义的页脚去覆盖。

如果可以，请不要关闭默认页脚中主题和提供者的名字与来源的显示；如需完全使用自定义页脚文件，也请在页脚加上如下 HTML 代码：

{% highlight html %}
本站主题 <a href="{{ site.ksio.meta.url }}/" target="_blank" rel="external ">Lime</a> 由 <a href="https://linxoid.com/ourai/" target="_blank" rel="external ">欧雷</a> 提供
{% endhighlight %}

感谢理解与配合！🙏

关于主题的使用方式详见《[快速上手]({{ site.baseurl }}/guides/getting-started/)》。

0 comments on commit c8c26d5

Please sign in to comment.