From f52380b97d45417979a5b6ac8c640dd8c178b9a6 Mon Sep 17 00:00:00 2001 From: Ourai Lin Date: Wed, 19 Apr 2023 18:26:50 +0800 Subject: [PATCH] docs(guide): installation and configuration of Getting Started guide --- bin/build.js | 2 +- man/cookbook/guides/getting-started/readme.md | 111 ++++++++++++++++-- .../_assets/stylesheets/local/pages/doc.scss | 1 + .../_assets/stylesheets/local/pages/post.scss | 1 + src/jekyll/_config.yml | 2 - src/jekyll/_pages/guides.md | 11 +- 6 files changed, 114 insertions(+), 14 deletions(-) diff --git a/bin/build.js b/bin/build.js index a2986c9..4394f62 100644 --- 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 index b707cff..47099b8 100644 --- 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 nofollow"} 生成的文件都在 `knosys` 或 `_knosys` 文件夹下。 +Jekyll 的主题暂不支持通过 [Gem](https://rubygems.org/){:target="_blank"}{:rel="external nofollow"} 的方式使用，且 Ruby 版本最好为 `2.3.0`。 -### Jekyll +若 Hexo 的版本在 [`5.0.0`](https://hexo.io/news/2020/07/29/hexo-5-released/){:target="_blank"}{:rel="external nofollow"} 及以上，可在项目根文件夹下通过 `npm i hexo-theme-lime` 安装使用。 + +### 压缩包 + +访问源码仓库的 [GitHub Releases](https://github.com/ourai/lime/releases){:target="_blank"}{:rel="external nofollow"} 页面，在目标版本的「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 nofollow"}为主题进行全局配置；而 Jekyll 并没有指定的配置方式，故主题的全局配置都挂在[配置文件](https://jekyllrb.com/docs/configuration/){:target="_blank"}{:rel="external nofollow"}中的 `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 nofollow"}，虽 Hexo 本身不具备此机制，但本主题在一定程度上进行了模拟，需在[网站配置文件](https://hexo.io/zh-cn/docs/configuration){:target="_blank"}{:rel="external nofollow"}中添加： + +```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 index 4049107..e045107 100644 --- 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 index 2507d13..28d41e2 100644 --- 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 index 0242a92..f60db3d 100644 --- 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 index 2d4cf79..c3b8f2a 100644 --- 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 nofollow"}（[kramdown](https://kramdown.gettalong.org/){:target="_blank"}{:rel="external nofollow"}） - [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML){:target="_blank"}{:rel="external nofollow"} - [Liquid](https://shopify.dev/docs/api/liquid){:target="_blank"}{:rel="external nofollow"} + - [EJS](https://ejs.co/){:target="_blank"}{:rel="external nofollow"} - 界面样式 - [Sass](https://sass-lang.com/){:target="_blank"}{:rel="external nofollow"}（SCSS） - [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS){:target="_blank"}{:rel="external nofollow"} @@ -58,6 +59,10 @@ permalink: /guides/ ## 使用 +本主题支持多种使用方式，详见《[快速上手]({{ site.baseurl }}/guides/getting-started/)》。 + +### 主题署名 + 虽说本主题源码开放并免费使用，但还是希望能够在使用时保留主题和提供者的名字与来源—— 在使用时，默认会在页面底部（即 `footer` 中）的版权声明右边显示主题和提供者的名字与来源相关信息： @@ -67,7 +72,7 @@ permalink: /guides/
主题提供者声明
-但这并非强制显示，可通过在[网站配置]({{ 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/)》。