asandikci.com/web
1
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

Update the docs & reduce the image size.

Browse source
This commit is contained in:
Cotes Chung 2020-09-27 12:42:46 +08:00
parent a0f80debb1
commit 04ad7bf432
6 changed files with 53 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
README.md
View file

@ -40,10 +40,10 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
## Installation
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, rename the repository to `USERNAME.github.io` (where `USERNAME` is your GitHub username), and then open terminal and clone the fork to local by:
```terminal
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch
```
### Setting up the local envrionment
@ -58,15 +58,15 @@ $ bundle install
`bundle` will automatically install all the dependencies specified by `Gemfile`.
In order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/):
In order to generate some extra files (_categories_, _tags_ and _last modified list_), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/).
- Debian
- on Debian:
```console
$ sudo apt-get install coreutils
```
- macOS
- on macOS:
```console
$ brew install coreutils
@ -84,7 +84,7 @@ Go to the root directory of the project and start initialization:
$ bash tools/init.sh
```
> If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
> **Note**: If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
What it does is:
@ -121,51 +121,33 @@ Few days later, you may find that the file changes does not refresh in real time
### Deployment
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [*project site*](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [_project site_](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.
Assuming you have already gone through the [initialization](#initialization), you can now choose ONE of the following methods to deploy your website.
#### Deploy on GitHub Pages
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use GitHub Actions to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use **GitHub Actions** to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete, a new remote branch called `gh-pages` will appear, which is used to store the built site files.
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
3. Choose branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) for your GitHub Pages site.
4. Visit your website at the address indicated by GitHub.
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files.
2. Browse to your repository on GitHub and choose the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) throught _Settings_
→ _Options_ → _GitHub Pages_:
![gh-pages-sources](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/gh-pages-sources.png)
3. Visit your website at the address indicated by GitHub.
#### Deploy on Other Platforms
On platforms other than GitHub, e.g. GitLab, we cannot enjoy the convenience of **GitHub Actions**. However, we have a tool to make up for this shortcoming.
On platforms other than GitHub, we cannot enjoy the convenience of **GitHub Actions**. Therefore, we should build the site locally (or on some other 3rd-party CI platform) and then put the site files on the server.
Commit the changes of your repository first, then run the publish script:
```console
$ bash tools/publish.sh
```
> Please note that the *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, then push to `origin/master`. Its output is similar to the following log:
```terminal
[INFO] Success to update lastmod for 4 post(s).
[INFO] Succeed! 3 category-pages created.
[INFO] Succeed! 4 tag-pages created.
[INFO] Published successfully!
```
Lastly, enable the pages service according to the instructions of the platform you choose.
#### Deploy on Private Server
In the root of the source project, build your site by:
Go to the root of the source project, build your site by:
```console
$ bash tools/build.sh -d /path/to/site/
```
The generated site files will be placed in the root of `/path/to/site/`. Now you should upload those files to your web server, such as Nginx.
The generated site files will be placed in folder `/path/to/site/`. Now you should upload those files to your web server.
### Documentation

6
_posts/2019-08-08-write-a-new-post.md
View file

@ -74,7 +74,7 @@ tag: TAG_NAME # e.g. bee
---
```
With the increasing number of posts, the number of categories and tags will increase several times! If we still manually create these *category*/*tag* type files, it will obviously be a super time-consuming job, and it is very likely to miss some of them, i.e., when you click on the missing `category` or `tag` link from a post or somewhere, the browser will complain to you "404 Not Found". The good news is we got a lovely script tool `_scripts/sh/create_pages.sh` to finish the boring tasks. Basically we will use it via `run.sh`, `build.sh`, `deploy.sh` or `publish.sh` that placed in `tools/` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#deployment" | relative_url }}).
With the increasing number of posts, the number of categories and tags will increase several times! If we still manually create these *category*/*tag* type files, it will obviously be a super time-consuming job, and it is very likely to miss some of them, i.e., when you click on the missing `category` or `tag` link from a post or somewhere, the browser will complain to you "404 Not Found". The good news is we got a lovely script tool `_scripts/sh/create_pages.sh` to finish the boring tasks. Basically we will use it through `run.sh`, `build.sh` or `deploy.sh` that placed in `tools/` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#deployment" | relative_url }}).
## Last modified date
@ -134,7 +134,6 @@ image: /path/to/image-file
---
```
## Pinned Posts
You can pin one or more posts to the top of the home page, and the fixed posts are sorted in reverse order according to their release date. Enable by:
@ -145,7 +144,6 @@ pin: true
---
```
## Code Block
Markdown symbols <code class="highlighter-rouge">```</code> can easily create a code block as following examples.
@ -156,7 +154,7 @@ This is a common code snippet, without syntax highlight and line number.
## Specific Language
Using <code class="highlighter-rouge">```language</code> you will get code snippets with line Numbers and syntax highlight.
Using <code class="highlighter-rouge">```language</code> you will get code snippets with line numbers and syntax highlight.
> **Note**: The Jekyll style `{% raw %}{%{% endraw %} highlight LANGUAGE {% raw %}%}{% endraw %}` or `{% raw %}{%{% endraw %} highlight LANGUAGE linenos {% raw %}%}{% endraw %}` are not allowed to be used in this theme !

56
_posts/2019-08-09-getting-started.md
View file

@ -10,10 +10,10 @@ pin: true
## Installation
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, rename the repository to `USERNAME.github.io` (where `USERNAME` is your GitHub username), and then open terminal and clone the fork to local by:
```terminal
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch
```
### Setting up the local envrionment
@ -28,15 +28,15 @@ $ bundle install
`bundle` will automatically install all the dependencies specified by `Gemfile`.
In order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/):
In order to generate some extra files (_categories_, _tags_ and _last modified list_), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/).
- Debian
- on Debian:
```console
$ sudo apt-get install coreutils
```
- macOS
- on macOS:
```console
$ brew install coreutils
@ -54,7 +54,7 @@ Go to the root directory of the project and start initialization:
$ bash tools/init.sh
```
> If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
> **Note**: If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
What it does is:
@ -91,48 +91,30 @@ Few days later, you may find that the file changes does not refresh in real time
### Deployment
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [*project site*](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [_project site_](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.
Assuming you have already gone through the [initialization](#initialization), you can now choose ONE of the following methods to deploy your website.
#### Deploy on GitHub Pages
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use GitHub Actions to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use **GitHub Actions** to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete, a new remote branch called `gh-pages` will appear, which is used to store the built site files.
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
3. Choose branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) for your GitHub Pages site.
4. Visit your website at the address indicated by GitHub.
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files.
2. Browse to your repository on GitHub and choose the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) throught _Settings_
→ _Options_ → _GitHub Pages_:
![gh-pages-sources](/assets/img/sample/gh-pages-sources.png)
3. Visit your website at the address indicated by GitHub.
#### Deploy on Other Platforms
On platforms other than GitHub, e.g. GitLab, we cannot enjoy the convenience of **GitHub Actions**. However, we have a tool to make up for this shortcoming.
On platforms other than GitHub, we cannot enjoy the convenience of **GitHub Actions**. Therefore, we should build the site locally (or on some other 3rd-party CI platform) and then put the site files on the server.
Commit the changes of your repository first, then run the publish script:
```console
$ bash tools/publish.sh
```
> Please note that the *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, then push to `origin/master`. Its output is similar to the following log:
```terminal
[INFO] Success to update lastmod for 4 post(s).
[INFO] Succeed! 3 category-pages created.
[INFO] Succeed! 4 tag-pages created.
[INFO] Published successfully!
```
Lastly, enable the pages service according to the instructions of the platform you choose.
#### Deploy on Private Server
In the root of the source project, build your site by:
Go to the root of the source project, build your site by:
```console
$ bash tools/build.sh -d /path/to/site/
```
The generated site files will be placed in the root of `/path/to/site/`. Now you should upload those files to your web server, such as Nginx.
The generated site files will be placed in folder `/path/to/site/`. Now you should upload those files to your web server.

BIN
assets/img/sample/devices-mockup.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 230 KiB

After

Width:  |  Height:  |  Size: 52 KiB

BIN
assets/img/sample/gh-pages-sources.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

44
docs/README_zh-CN.md
View file

@ -43,10 +43,10 @@
## 安装
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork)，然后克隆到本地：
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork)，把仓库改名为 `USERNAME.github.io`（其中 `USERNAME` 是你的 GitHub 用户名）， 然后克隆到本地：
```terminal
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch
```
### 设置本地环境
@ -61,7 +61,7 @@ $ bundle install
`bundle` 会自动安装 `Gemfile` 内指定的依赖插件。
为了生成一些额外的文件（Post 的分类、标签以及更新时间列表），需要用到一些脚本工具。而它们需要安装依赖包 [yq](https://github.com/mikefarah/yq#install)。另外，如果你电脑的操作系统是 Debian 或者 macOS，还需安装 [GNU coreutils](https://www.gnu.org/software/coreutils/)：
为了生成一些额外的文件（Post 的 _分类_、_标签_ 以及 _更新时间列表_），需要用到一些脚本工具。而它们需要安装依赖包 [yq](https://github.com/mikefarah/yq#install)。另外，如果你电脑的操作系统是 Debian 或者 macOS，还需安装 [GNU coreutils](https://www.gnu.org/software/coreutils/)：
- Debian
@ -132,37 +132,19 @@ $ bash tools/run.sh
由于安全原因，GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用脚本工具去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
2. 除非你是使用 project 站点, 否则重命名你的仓库为 `<username>.github.io`。
3. 选择分支 `gh-pages` 作为 GitHub Pages 站点的[发布源](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).
4. 按照 GitHub 指示的地址去访问你的网站。
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
2. 回到 GitHub 上的仓库， 通过 _Settings_
→ _Options_ → _GitHub Pages_ 选择分支 `gh-pages` 作为[_发布源_](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site):
![gh-pages-sources](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/gh-pages-sources.png)
3. 按照 GitHub 指示的地址去访问你的网站。
#### 部署到其他 Pages 平台
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。不过先别慌，可以通过工具来弥补这个遗憾。
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。因此我们需要在本地构建站点（或者在其他第三方 CI 平台），然后推送站点文件到服务器上。
先把本地仓库的 upstream 改为新平台的仓库地址，推送一发。以后每次更新内容后，提交 commit ，然后运行:
```console
$ bash tools/publish.sh
```
>**注**: *最后更新* 列表根据文章的 git 修改记录生成，所以运行前先把 `_posts` 目录的修改提交。
它会自动生成文章的 *最后修改日期* 和 *分类 / 标签* 页面，并自动提交一个 commit 并推送到 `origin/master` 。输出日志类似如下：
```terminal
[INFO] Success to update lastmod for 4 post(s).
[INFO] Succeed! 3 category-pages created.
[INFO] Succeed! 4 tag-pages created.
[INFO] Published successfully!
```
最后，根据平台的说明文档为项目开启 Pages 服务。
#### 部署到私人服务器
在项目更目录，运行:
在项目根目录，运行:
```console
$ bash tools/build.sh -d /path/to/site/
@ -178,7 +160,7 @@ $ bash tools/build.sh -d /path/to/site/
三人行必有我师，欢迎提报告 bug, 帮助改进代码质量，或者提交新功能。具体操作规则请参考 [贡献指南](../.github/CONTRIBUTING.md)，谢谢 🙏。
## 感谢
## 鸣谢
这个主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息).