docs(guide): installation and configuration of Getting Started guide

ourai · Apr 19, 2023 · f52380b · f52380b
1 parent 27a579f
commit f52380b
Show file tree

Hide file tree

Showing 6 changed files with 114 additions and 14 deletions.
diff --git a/bin/build.js b/bin/build.js
@@ -48,7 +48,7 @@ function copyHexoFiles() {
  const hexoDistRoot = `${distRoot}/hexo`;
 
  ensureDirExists(hexoDistRoot, true);
- copyFileDeeply(hexoSrcRoot, hexoDistRoot);
+ copyFileDeeply(hexoSrcRoot, hexoDistRoot, ['source']);
  rm(`${hexoDistRoot}/*/_local`);
 
  copyThemeAssets(`${hexoDistRoot}/source`, true);

diff --git a/man/cookbook/guides/getting-started/readme.md b/man/cookbook/guides/getting-started/readme.md
@@ -1,11 +1,108 @@
-## 与静态网站生成器集成
+## 下载安装
 
-本主题可在一些主流的静态网站生成器中使用，如 Jekyll、Hexo 等。
+为满足多种使用场景，本主题提供了相应的方式——
 
-为了尽量统一用法和便于自动化处理，在封装适配时遵循如下约定：
+### 包管理器
 
-- 除了个别文件外，主题所提供的和强依赖的资源基本都放在 `ksio` 文件夹下；
-- 用于控制主题预置渲染逻辑的配置项都挂在静态网站生成器配置文件中的 `ksio` 下面（详见《[网站配置]({{ site.baseurl }}/apis/site-config/)》）；
-- 通过 [KnoSys](https://knosysio.github.io/){:target="_blank"}{:rel="external "} 生成的文件都在 `knosys` 或 `_knosys` 文件夹下。
+Jekyll 的主题暂不支持通过 [Gem](https://rubygems.org/){:target="_blank"}{:rel="external "} 的方式使用，且 Ruby 版本最好为 `2.3.0`。
 
-### Jekyll
+若 Hexo 的版本在 [`5.0.0`](https://hexo.io/news/2020/07/29/hexo-5-released/){:target="_blank"}{:rel="external "} 及以上，可在项目根文件夹下通过 `npm i hexo-theme-lime` 安装使用。
+
+### 压缩包
+
+访问源码仓库的 [GitHub Releases](https://github.com/ourai/lime/releases){:target="_blank"}{:rel="external "} 页面，在目标版本的「Assets」中下载与静态网站生成器相匹配的压缩包到本地：
+
+- `jekyll-theme-lime.zip`
+- `hexo-theme-lime.zip`
+
+解压后将文件夹与文件复制或挪动到自己项目的指定位置。
+
+## 运行网站
+
+在将主题文件都弄到自己项目中后，为了让网站能够成功运行并看到效果，需了解以下事宜——
+
+### 目录结构
+
+为保持在不同静态网站生成器中使用体验一致性，主题预置的静态资源存放在：
+
+```text
+[ASSET_ROOT]
+ ├── fonts
+ │ └── ...
+ ├── images
+ │ └── ...
+ ├── javascripts
+ │ └── ...
+ └── stylesheets
+ └── ...
+```
+
+`[ASSET_ROOT]` 在 Jekyll 和 Hexo 中分别是 `_assets` 与 `themes/lime/source`。即便如此，在实际使用时自定义文件的目录结构可以不按照这个来。
+
+无论是静态资源还是动态模板，主题所提供的和强依赖的基本都放在 `ksio` 或 `_ksio` 文件夹下。
+
+### 创建文件
+
+有几个静态资源文件是要手动创建的——
+
+#### 全局依赖
+
+创建 `[ASSET_ROOT]/stylesheets/_helper.scss`，内容为：
+
+```scss
+@import "ksio/helper";
+```
+
+创建 `[ASSET_ROOT]/stylesheets/global.scss`，内容为：
+
+```scss
+@import "ksio/all";
+```
+
+若是在 Jekyll 中使用，还要创建 `[ASSET_ROOT]/javascripts/global.js`，内容为：
+
+```js
+//= require ./ksio/vendors/jquery-1.11.3.min
+//= require ./ksio/bootstrap-sprockets.js
+```
+
+#### 页面依赖
+
+当要使用主题预置页面的样式时，需要为每个页面创建单独的样式文件并通过 `@import` 去导入：
+
+| 页面 | 布局模板 | 预置样式文件 |
+| --- | --- | --- |
+| 文章列表 | `ksio/page` 或 `page` | `[ASSET_ROOT]/stylesheets/ksio/pages/_posts.scss` |
+| 文章详情 | `ksio/post` 或 `post` | `[ASSET_ROOT]/stylesheets/ksio/pages/_post.scss` |
+| 文档详情 | `ksio/doc` | `[ASSET_ROOT]/stylesheets/ksio/pages/_doc.scss` |
+
+### 主题配置
+
+在 Hexo 中，可通过[指定方式](https://hexo.io/zh-cn/docs/configuration#%E4%BD%BF%E7%94%A8%E4%BB%A3%E6%9B%BF%E4%B8%BB%E9%A2%98%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6){:target="_blank"}{:rel="external "}为主题进行全局配置；而 Jekyll 并没有指定的配置方式，故主题的全局配置都挂在[配置文件](https://jekyllrb.com/docs/configuration/){:target="_blank"}{:rel="external "}中的 `ksio` 下面：
+
+```yaml
+ksio:
+ brand:
+ color: "#0871ab"
+ copyright:
+ owner:
+ text: 欧雷流
+ url: https://ourai.ws/
+```
+
+全部配置项详见《[网站配置]({{ site.baseurl }}/apis/site-config/)》。
+
+### 页面配置
+
+「页面配置」即定义在 Front Matter 中的变量。
+
+在 Jekyll 中可按匹配规则为页面配置[批量设置默认值](https://jekyllrb.com/docs/configuration/front-matter-defaults/){:target="_blank"}{:rel="external "}，虽 Hexo 本身不具备此机制，但本主题在一定程度上进行了模拟，需在[网站配置文件](https://hexo.io/zh-cn/docs/configuration){:target="_blank"}{:rel="external "}中添加：
+
+```yaml
+ksio:
+ defaults:
+ layout: # 用于布局模板，值为对象
+ page: # 用于页面，值为数组
+```
+
+全部配置项详见《[页面配置]({{ site.baseurl }}/apis/page-config/)》。
diff --git a/src/jekyll/_assets/stylesheets/local/pages/doc.scss b/src/jekyll/_assets/stylesheets/local/pages/doc.scss
@@ -1 +1,2 @@
+@import "../../ksio/syntax-highlighting";
 @import "../../ksio/pages/doc";
diff --git a/src/jekyll/_assets/stylesheets/local/pages/post.scss b/src/jekyll/_assets/stylesheets/local/pages/post.scss
@@ -1 +1,2 @@
+@import "../../ksio/syntax-highlighting";
 @import "../../ksio/pages/post";
diff --git a/src/jekyll/_config.yml b/src/jekyll/_config.yml
@@ -163,8 +163,6 @@ ksio:
  footer:
  partial: footer.html
  links:
- - text: OOSS
- url: https://oss.ourai.ws/
  - text: 关于
  url: /about/
  - text: 资助

diff --git a/src/jekyll/_pages/guides.md b/src/jekyll/_pages/guides.md
@@ -26,7 +26,7 @@ permalink: /guides/
 ### 静态网站生成器
 
 - Jekyll（非 gem-based）
-- Hexo（计划中）
+- Hexo
 
 ## 依赖
 
@@ -38,6 +38,7 @@ permalink: /guides/
  - [Markdown](https://www.markdownguide.org/){:target="_blank"}{:rel="external "}（[kramdown](https://kramdown.gettalong.org/){:target="_blank"}{:rel="external "}）
  - [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML){:target="_blank"}{:rel="external "}
  - [Liquid](https://shopify.dev/docs/api/liquid){:target="_blank"}{:rel="external "}
+ - [EJS](https://ejs.co/){:target="_blank"}{:rel="external "}
 - 界面样式
  - [Sass](https://sass-lang.com/){:target="_blank"}{:rel="external "}（SCSS）
  - [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS){:target="_blank"}{:rel="external "}
@@ -58,6 +59,10 @@ permalink: /guides/
 
 ## 使用
 
+本主题支持多种使用方式，详见《[快速上手]({{ site.baseurl }}/guides/getting-started/)》。
+
+### 主题署名
+
 虽说本主题源码开放并免费使用，但还是希望能够在使用时保留主题和提供者的名字与来源——
 
 在使用时，默认会在页面底部（即 `footer` 中）的版权声明右边显示主题和提供者的名字与来源相关信息：
@@ -67,7 +72,7 @@ permalink: /guides/
  <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) 改为自定义的页脚去覆盖。
+但这并非是强制的，可通过在[网站配置]({{ site.baseurl }}/apis/site-config/)文件中将 [`copyright.provider`]({{ site.baseurl }}/apis/site-config/#copyright) 设为 `false` 以关闭显示；或把 [`footer.partial`]({{ site.baseurl }}/apis/site-config/#footer) 改为自定义的页脚去覆盖。
 
 如果可以，请不要关闭默认页脚中主题和提供者的名字与来源的显示；如需完全使用自定义页脚文件，也请在页脚加上如下 HTML 代码：
 
@@ -76,5 +81,3 @@ permalink: /guides/
 {% endhighlight %}
 
 感谢理解与配合！🙏
-
-关于主题的使用方式详见《[快速上手]({{ site.baseurl }}/guides/getting-started/)》。