Update docs for v2.5
This commit is contained in:
Cotes Chung
parent
1c3c22bb68
commit
adff74b27b
4 changed files with 210 additions and 393 deletions
187
README.md
187
README.md
|
|
@ -13,7 +13,7 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
|
|||
## Table of Contents
|
||||
|
||||
* [Features](#features)
|
||||
* [Installing](#installing)
|
||||
* [Installation](#installation)
|
||||
* [Usage](#usage)
|
||||
* [Contributing](#contributing)
|
||||
* [Credits](#credits)
|
||||
|
|
@ -37,13 +37,28 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
|
|||
* GA Pageviews reporting (Advanced)
|
||||
* SEO and Performance Optimization
|
||||
|
||||
## Installing
|
||||
|
||||
### Prerequisites
|
||||
## Installation
|
||||
|
||||
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of basic environment (`Ruby`, `RubyGems` and `Bundler`).
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
|
||||
|
||||
To improve the writing experience, we need to use some script tools. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
|
||||
```terminal
|
||||
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
|
||||
```
|
||||
|
||||
### Setting up the local envrionment
|
||||
|
||||
If you would like to run or build the project on your local machine, please follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems` and `Bundler`.
|
||||
|
||||
Before running or building for the first time, please complete the installation of the Jekyll plugins. Go to the root directory of project and run:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
|
||||
`bundle` will automatically install all the dependencies specified by `Gemfile`.
|
||||
|
||||
What's more, in order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
|
||||
|
||||
* Debian
|
||||
|
||||
|
|
@ -58,123 +73,76 @@ To improve the writing experience, we need to use some script tools. If your mac
|
|||
```
|
||||
|
||||
|
||||
### Jekyll Plugins
|
||||
|
||||
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
|
||||
```
|
||||
|
||||
And replace the `USER` above to your GitHub username.
|
||||
|
||||
The first time you run or build the project on local machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
|
||||
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Running [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) requires some extra files, which cannot be generated by Jekyll native commands, so please strictly follow the methods mentioned below to run or deploy your website.
|
||||
|
||||
### Directory Structure
|
||||
### Initialization
|
||||
|
||||
The main files and related brief introductions are listed below:
|
||||
Go to the root directory of the project and start initialization:
|
||||
|
||||
```sh
|
||||
jekyll-theme-chirpy/
|
||||
├── _data
|
||||
├── _includes
|
||||
├── _layouts
|
||||
├── _posts # posts stay here
|
||||
├── _scripts
|
||||
├── .travis.yml # remove it
|
||||
├── .github # remove this, too
|
||||
├── assets
|
||||
├── tabs
|
||||
│ └── about.md # the ABOUT page
|
||||
├── .gitignore
|
||||
├── 404.html
|
||||
├── Gemfile
|
||||
├── LICENSE
|
||||
├── README.md
|
||||
├── _config.yml # configuration file
|
||||
├── tools # script tools
|
||||
├── docs
|
||||
├── feed.xml
|
||||
├── index.html
|
||||
├── robots.txt
|
||||
└── sitemap.xml
|
||||
```console
|
||||
$ 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.
|
||||
|
||||
As mentioned above, some files or directories should be removed from your repo:
|
||||
What it does is:
|
||||
|
||||
```terminal
|
||||
$ rm -rf .travis.yml .github _posts/*
|
||||
```
|
||||
1. Remove some files or directories from your repository:
|
||||
- `.travis.yml`
|
||||
- everything under `.github/`
|
||||
- files under `_posts/`
|
||||
- folder `docs/`
|
||||
|
||||
2. Unless the option `--no-gh` was enabled, setup the GitHub action workflow by renaming `pages-deploy.yml.hook` of directory `.github/workflows/` to `pages-deploy.yml`.
|
||||
|
||||
3. Automatically create a commit to save the changes.
|
||||
|
||||
### Configuration
|
||||
|
||||
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
|
||||
|
||||
* `url`
|
||||
|
||||
Set to your website url and there should be no slash symbol at the tail. Format: `<protocol>://<domain>`.
|
||||
|
||||
|
||||
* `avatar`
|
||||
|
||||
It defines the image file location of avatar. The sample image is `/assets/img/sample/avatar.jpg`, and should be replaced by your own one(a square image). Notice that a huge image file will increase the load time of your site, so keep your avatar image size as small as possible(may be *<https://tinypng.com/>* will help).
|
||||
|
||||
* `timezone`
|
||||
|
||||
To ensure that the posts' release date matches the city you live in, please modify the field `timezone` correctly. A list of all available values can be found on [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) or [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
||||
|
||||
* `theme_mode`
|
||||
|
||||
There are three options for the theme color scheme:
|
||||
|
||||
- **dual** - The default color scheme will follow the system settings, but if the system does not support dark mode, or the browser does not support `Media Queries Level 5`, the theme will be displayed as `light` mode by default. Anyway, the bottom left corner of the Sidebar will provide a button for users to switch color schemes.
|
||||
|
||||
- **dark** - Always show dark mode.
|
||||
- **light** - Always show light mode.
|
||||
|
||||
|
||||
### Run Locally
|
||||
|
||||
You may want to preview the site content before publishing, so just run the script tool:
|
||||
You may want to preview the site contents before publishing, so just run it by:
|
||||
|
||||
```terminal
|
||||
$ bash tools/run.sh
|
||||
```
|
||||
|
||||
Open a modern browser and visit at <http://localhost:4000>.
|
||||
Then open a browser and visit to <http://localhost:4000>.
|
||||
|
||||
Few days later, you may find that the file modification(e.g. edits to a post) does not refresh in real time by using `run.sh`. Don't worry, the advanced option `-r` (or `--realtime`) will solve this problem, but it requires [**fswatch**](http://emcrisostomo.github.io/fswatch/) to be installed on your machine. Type `-h` for more information.
|
||||
Few days later, you may find that the file changes does not refresh in real time by using `run.sh`. Don't worry, the advanced option `-r` (or `--realtime`) will solve this problem, but it requires [**fswatch**](http://emcrisostomo.github.io/fswatch/) to be installed on your machine.
|
||||
|
||||
### Deploying to GitHub Pages
|
||||
### Deployment
|
||||
|
||||
Before the deployment begins, checkout the file `_config.yml` and make sure that the `url` has been configured. What's more, if you prefer the [Project site on GitHub](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and also use the default domain `<username>.github.io`, 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`.
|
||||
|
||||
#### Option 1: Built by GitHub Pages
|
||||
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.
|
||||
|
||||
By deploying the site in this way, you're allowed to push the source code directly to the remote.
|
||||
#### Deploy on GitHub Pages
|
||||
|
||||
> **Note**: If you want to use any third-party Jekyll plugins that not on [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
|
||||
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**. Rename the repository to:
|
||||
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.
|
||||
|
||||
|Site Type | Repo's Name|
|
||||
|:---|:---|
|
||||
|User or Organization | `<username>.github.io`|
|
||||
|Project| Any one except `<username>.github.io`, let's say `project`|
|
||||
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
|
||||
|
||||
**2**. Commit the changes of the repo first, then run the publish script:
|
||||
3. Choose branch `gh-pages` as your GitHub Pages source.
|
||||
|
||||
4. 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.
|
||||
|
||||
Commit the changes of your repository first, then run the publish script:
|
||||
|
||||
```console
|
||||
$ bash tools/publish.sh
|
||||
|
|
@ -182,7 +150,7 @@ $ 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, and then push to `origin/master`. Its output is similar to the following log:
|
||||
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).
|
||||
|
|
@ -191,54 +159,21 @@ it will automatically generates the *Latest Modified Date* and *Categories / Tag
|
|||
[INFO] Published successfully!
|
||||
```
|
||||
|
||||
**3**. Go to GitHub website and enable GitHub Pages service for the repo.
|
||||
Lastly, enable the pages service according to the instructions of the platform you choose.
|
||||
|
||||
**4**. Check it out:
|
||||
#### Deploy on Private Server
|
||||
|
||||
|Site Type | Site URL |
|
||||
|:---|:---|
|
||||
|User or Organization | `https://<username>.github.io/`|
|
||||
|Project| `https://<username>.github.io/project/`|
|
||||
|
||||
|
||||
#### Option 2: Build Locally
|
||||
|
||||
For security reasons, GitHub Pages runs on `safe` mode, which means the third-party Jekyll plugins or custom scripts won't work. If you want to use any other plugin that not on the [whitelist](https://pages.github.com/versions/), **you have to generate the site locally rather than on GitHub Pages**.
|
||||
|
||||
**1**. Browse to GitHub website, create a brand new repo named:
|
||||
|
||||
|Site Type | Repo's Name|
|
||||
|:---|:---|
|
||||
|User or Organization | `<username>.github.io`|
|
||||
|Project| Any one except `<username>.github.io`, let's say `project`|
|
||||
|
||||
and clone it.
|
||||
|
||||
**2**. In the root of the source project, build your site by:
|
||||
In the root of the source project, build your site by:
|
||||
|
||||
```console
|
||||
$ bash tools/build.sh -d /path/to/local/project/
|
||||
$ bash tools/build.sh -d /path/to/site/
|
||||
```
|
||||
|
||||
The generated static files will be placed in the root of `/path/to/local/project`. Commit and push the changes to the `master` branch on GitHub.
|
||||
|
||||
**3**. Go to GitHub website and enable Pages service for the new repository.
|
||||
|
||||
**4**. Visit at:
|
||||
|
||||
|Site Type | Site URL |
|
||||
|:---|:---|
|
||||
|User or Organization | `https://<username>.github.io/`|
|
||||
|Project| `https://<username>.github.io/project/`|
|
||||
|
||||
#### Finishing work
|
||||
|
||||
No matter which way you choose to deploy the website on GitHub, please enforce the `HTTPS` for it. See official docs: [Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https).
|
||||
|
||||
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.
|
||||
|
||||
### Documentation
|
||||
|
||||
For more details and the better reading experience, please check out the [tutorial in demo site](https://chirpy.cotes.info/categories/tutorial/). In the meanwhile, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki).
|
||||
For more details and the better reading experience, please check out the [tutorials on demo site](https://chirpy.cotes.info/categories/tutorial/). In the meanwhile, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki).
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ tags: [writing]
|
|||
|
||||
## Naming and Path
|
||||
|
||||
Create a new file named with the format `YYYY-MM-DD-title.md` then put it into `_post` of the root directory.
|
||||
Create a new file named `YYYY-MM-DD-TITLE.EXTENSION` and put it in the `_post/` of the root directory. The `EXTENSION` must be one of `md` and `markdown`. From `v2.4.1`, you can create sub-directories under `_posts/` to categorize posts.
|
||||
|
||||
## Front Matter
|
||||
|
||||
|
|
@ -33,27 +33,28 @@ In order to accurately record the release date of a post, you should not only se
|
|||
|
||||
The `categories` of each post is designed to contain up to two elements, and the number of elements in `tags` can be zero to infinity.
|
||||
|
||||
The list of posts belonging to the same category/tag is recorded on a separate page. The number of such *category*/*tag* type pages is equal to the number of `categories`/`tags` for all posts, they must match perfectly.
|
||||
The list of posts belonging to the same _category_/_tag_ is recorded on a separate page. At the same time, the number of these _category_/_tag_ type pages is equal to the number of `categories` / `tags` elements for all posts, which means that the two number must be exactly the same.
|
||||
|
||||
For instance, let's say there is a post with front matter:
|
||||
|
||||
let's say there is a post with front matter:
|
||||
```yaml
|
||||
categories: [Animal, Insect]
|
||||
tags: bee
|
||||
```
|
||||
|
||||
then we should have two *category* type pages placed in folder `categories` of root and one *tag* type page placed in folder `tags` of root:
|
||||
Then we should have two _category_ type pages placed in folder `categories` of root and one _tag_ type page placed in folder `tags` of root:
|
||||
|
||||
```terminal
|
||||
jekyll-theme-chirpy
|
||||
```sh
|
||||
.
|
||||
├── categories
|
||||
│ ├── animal.html
|
||||
│ ├── animal.html # a category type page
|
||||
│ └── insect.html
|
||||
├── tags
|
||||
│ └── bee.html
|
||||
│ └── bee.html # a tag type page
|
||||
...
|
||||
```
|
||||
|
||||
and the content of a *category* type page is
|
||||
and the content of a _category_ type page is
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -63,7 +64,7 @@ category: CATEGORY_NAME # e.g. Insect
|
|||
---
|
||||
```
|
||||
|
||||
the content of a *tag* type page is
|
||||
the content of a _tag_ type page is
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -73,11 +74,11 @@ 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, it will complain to you '404'). The good news is that we got a lovely script tool `_scripts/sh/create_pages.sh` to finish the boring task. Basically we will use it via `tools/publish.sh` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#option-1-built-by-github-pages" | 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 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 }}).
|
||||
|
||||
## Last modified date
|
||||
|
||||
The last modified date of a post is obtained according to its latest git commit date, and all the modified date of the posts should be stored in `_data/updates.yml`. For example:
|
||||
The last modified date of a post is obtained according to the post's latest git commit date, and the modified date of all posts are designed to be stored in the file `_data/updates.yml`. Then contents of that file may be as follows:
|
||||
|
||||
```yaml
|
||||
-
|
||||
|
|
@ -87,13 +88,13 @@ The last modified date of a post is obtained according to its latest git commit
|
|||
...
|
||||
```
|
||||
|
||||
You can choose to create this file manually, but as you may notice, the better approach is to let it be automatically generated by a tool script. And `_scripts/sh/dump_lastmod.sh` was born for this! Similar to the another script `_scripts/sh/create_pages.sh` mentioned above, it is also be called from `tools/publish.sh`, so it doesn't have to be used separately.
|
||||
You can choose to create this file manually, But the better approach is to let it be automatically generated by a script tool, and `_scripts/sh/dump_lastmod.sh` was born for this! Similar to the other script (`create_pages.sh`) mentioned above, it is also be called from the other superior tools, so it doesn't have to be used separately.
|
||||
|
||||
When some posts have been modified since their published date and also the file `_data/updates.yml` was created correctly, a list with the label **Recent Updates** will be displayed in the right panel of the desktop view, which records the five most recently modified articles.
|
||||
When some posts have been modified since their published date and also the file `_data/updates.yml` was created correctly, a list with the label **Recent Updates** will be displayed in the right panel of the desktop view, which records the five most recently modified posts.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
By default, the **T**able **o**f **C**ontents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to `_config.yml` and set the variable `toc` to `false`. If you want to turn off TOC for specific post, add the following to post's [Front Matter](https://jekyllrb.com/docs/front-matter/):
|
||||
By default, the **T**able **o**f **C**ontents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to `_config.yml` and set the value of variable `toc` to `false`. If you want to turn off TOC for specific post, add the following to post's [Front Matter](https://jekyllrb.com/docs/front-matter/):
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
|
|||
|
|
@ -7,11 +7,28 @@ tags: [getting started]
|
|||
pin: true
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of basic environment (`Ruby`, `RubyGems` and `Bundler`).
|
||||
## Installation
|
||||
|
||||
To improve the writing experience, we need to use some script tools. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
|
||||
|
||||
```terminal
|
||||
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
|
||||
```
|
||||
|
||||
### Setting up the local envrionment
|
||||
|
||||
If you would like to run or build the project on your local machine, please follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems` and `Bundler`.
|
||||
|
||||
Before running or building for the first time, please complete the installation of the Jekyll plugins. Go to the root directory of project and run:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
|
||||
`bundle` will automatically install all the dependencies specified by `Gemfile`.
|
||||
|
||||
What's more, in order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
|
||||
|
||||
* Debian
|
||||
|
||||
|
|
@ -26,119 +43,76 @@ To improve the writing experience, we need to use some script tools. If your mac
|
|||
```
|
||||
|
||||
|
||||
## Jekyll Plugins
|
||||
## Usage
|
||||
|
||||
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
|
||||
Running [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) requires some extra files, which cannot be generated by Jekyll native commands, so please strictly follow the methods mentioned below to run or deploy your website.
|
||||
|
||||
### Initialization
|
||||
|
||||
Go to the root directory of the project and start initialization:
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
|
||||
$ bash tools/init.sh
|
||||
```
|
||||
|
||||
And replace the `USER` above to your GitHub username.
|
||||
> If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
|
||||
|
||||
The first time you run or build the project on local machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
|
||||
What it does is:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
1. Remove some files or directories from your repository:
|
||||
- `.travis.yml`
|
||||
- everything under `.github/`
|
||||
- files under `_posts/`
|
||||
- folder `docs/`
|
||||
|
||||
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
|
||||
2. Unless the option `--no-gh` was enabled, setup the GitHub action workflow by renaming `pages-deploy.yml.hook` of directory `.github/workflows/` to `pages-deploy.yml`.
|
||||
|
||||
3. Automatically create a commit to save the changes.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
The main files and related brief introductions are listed below:
|
||||
|
||||
```sh
|
||||
jekyll-theme-chirpy/
|
||||
├── _data
|
||||
├── _includes
|
||||
├── _layouts
|
||||
├── _posts # posts stay here
|
||||
├── _scripts
|
||||
├── .travis.yml # remove it
|
||||
├── .github # remove this, too
|
||||
├── assets
|
||||
├── tabs
|
||||
│ └── about.md # the ABOUT page
|
||||
├── .gitignore
|
||||
├── 404.html
|
||||
├── Gemfile
|
||||
├── LICENSE
|
||||
├── README.md
|
||||
├── _config.yml # configuration file
|
||||
├── tools # script tools
|
||||
├── feed.xml
|
||||
├── index.html
|
||||
├── robots.txt
|
||||
└── sitemap.xml
|
||||
```
|
||||
|
||||
|
||||
As mentioned above, some files or directories should be removed from your repo:
|
||||
|
||||
```terminal
|
||||
$ rm -rf .travis.yml .github _posts/*
|
||||
```
|
||||
|
||||
## Configuration
|
||||
### Configuration
|
||||
|
||||
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
|
||||
|
||||
* `url`
|
||||
|
||||
Set to your website url and there should be no slash symbol at the tail. Format: `<protocol>://<domain>`.
|
||||
|
||||
|
||||
* `avatar`
|
||||
|
||||
It defines the image file location of avatar. The sample image is `/assets/img/sample/avatar.jpg`, and should be replaced by your own one (a square image). Notice that a huge image file will increase the load time of your site, so keep your avatar image size as small as possible (may be *<https://tinypng.com/>* will help).
|
||||
|
||||
* `timezone`
|
||||
|
||||
To ensure that the posts' release date matches the city you live in, please modify the field `timezone` correctly. A list of all available values can be found on [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) or [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
||||
|
||||
* `theme_mode`
|
||||
|
||||
There are three options for the theme color scheme:
|
||||
|
||||
- **dual** - The default color scheme will follow the system settings, but if the system does not support dark mode, or the browser does not support `Media Queries Level 5`, the theme will be displayed as `light` mode by default. Anyway, the bottom left corner of the Sidebar will provide a button for users to switch color schemes.
|
||||
### Run Locally
|
||||
|
||||
- **dark** - Always show dark mode.
|
||||
- **light** - Always show light mode.
|
||||
|
||||
|
||||
## Run Locally
|
||||
|
||||
You may want to preview the site content before publishing, so just run the script tool:
|
||||
You may want to preview the site contents before publishing, so just run it by:
|
||||
|
||||
```terminal
|
||||
$ bash tools/run.sh
|
||||
```
|
||||
|
||||
Open a browser and visit <http://localhost:4000>.
|
||||
Then open a browser and visit to <http://localhost:4000>.
|
||||
|
||||
Few days later, you may find that the file changes does not refresh in real time by using `run.sh`. Don't worry, the advanced option `-r` (or `--realtime`) will solve this problem, but it requires [**fswatch**](http://emcrisostomo.github.io/fswatch/) to be installed on your machine.
|
||||
|
||||
## Deploying to GitHub Pages
|
||||
### Deployment
|
||||
|
||||
Before the deployment begins, checkout the file `_config.yml` and make sure that the `url` has been configured. What's more, if you prefer the [Project site on GitHub](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and also use the default domain `<username>.github.io`, 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.
|
||||
|
||||
### Option 1: Built by GitHub Pages
|
||||
#### Deploy on GitHub Pages
|
||||
|
||||
By deploying the site in this way, you're allowed to push the source code directly to the remote.
|
||||
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.
|
||||
|
||||
> **Note**: If you want to use any third-party Jekyll plugins that not on [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
|
||||
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.
|
||||
|
||||
**1**. Rename the repository to:
|
||||
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
|
||||
|
||||
|Site Type | Repo's Name|
|
||||
|:---|:---|
|
||||
|User or Organization | `<username>.github.io`|
|
||||
|Project| Any one except `<username>.github.io`, let's say `project`|
|
||||
3. Choose branch `gh-pages` as your GitHub Pages source.
|
||||
|
||||
**2**. Commit the changes of the repo first, then run the publish script:
|
||||
4. 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.
|
||||
|
||||
Commit the changes of your repository first, then run the publish script:
|
||||
|
||||
```console
|
||||
$ bash tools/publish.sh
|
||||
|
|
@ -146,7 +120,7 @@ $ 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, and then push to `origin/master`. Its output is similar to the following log:
|
||||
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).
|
||||
|
|
@ -155,46 +129,14 @@ it will automatically generates the *Latest Modified Date* and *Categories / Tag
|
|||
[INFO] Published successfully!
|
||||
```
|
||||
|
||||
**3**. Go to GitHub website and enable GitHub Pages service for the repo.
|
||||
Lastly, enable the pages service according to the instructions of the platform you choose.
|
||||
|
||||
**4**. Check it out:
|
||||
#### Deploy on Private Server
|
||||
|
||||
|Site Type | Site URL |
|
||||
|:---|:---|
|
||||
|User or Organization | `https://<username>.github.io/`|
|
||||
|Project| `https://<username>.github.io/project/`|
|
||||
|
||||
|
||||
### Option 2: Build Locally
|
||||
|
||||
For security reasons, GitHub Pages runs on `safe` mode, which means the third-party Jekyll plugins or custom scripts won't work. If you want to use any other plugin that not on the [whitelist](https://pages.github.com/versions/), **you have to generate the site locally rather than on GitHub Pages**.
|
||||
|
||||
**1**. Browse to GitHub website, create a brand new repo named:
|
||||
|
||||
|Site Type | Repo's Name|
|
||||
|:---|:---|
|
||||
|User or Organization | `<username>.github.io`|
|
||||
|Project| Any one except `<username>.github.io`, let's say `project`|
|
||||
|
||||
and clone it.
|
||||
|
||||
**2**. In the root of the source project, build your site by:
|
||||
In the root of the source project, build your site by:
|
||||
|
||||
```console
|
||||
$ bash tools/build.sh -d /path/to/local/project/
|
||||
$ bash tools/build.sh -d /path/to/site/
|
||||
```
|
||||
|
||||
The generated static files will be placed in the root of `/path/to/local/project`. Commit and push the changes to the `master` branch on GitHub.
|
||||
|
||||
**3**. Go to GitHub website and enable Pages service for the new repository.
|
||||
|
||||
**4**. Visit at:
|
||||
|
||||
|Site Type | Site URL |
|
||||
|:---|:---|
|
||||
|User or Organization | `https://<username>.github.io/`|
|
||||
|Project| `https://<username>.github.io/project/`|
|
||||
|
||||
### Finishing work
|
||||
|
||||
No matter which way you choose to deploy the website on GitHub, please enforce the `HTTPS` for it. See official docs: [Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https).
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -14,15 +14,15 @@
|
|||
|
||||
## 目录
|
||||
|
||||
* [功能预览](#功能预览)
|
||||
* [功能一览](#功能一览)
|
||||
* [安装](#安装)
|
||||
* [运行指南](#运行指南)
|
||||
* [使用](#使用)
|
||||
* [参与贡献](#参与贡献)
|
||||
* [感谢](#感谢)
|
||||
* [赞助](#赞助)
|
||||
* [许可证书](#许可证书)
|
||||
|
||||
## 功能预览
|
||||
## 功能一览
|
||||
|
||||
* 文章置顶
|
||||
* 可配置的全局主题颜色
|
||||
|
|
@ -43,11 +43,26 @@
|
|||
|
||||
## 安装
|
||||
|
||||
### 准备工作
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork)，然后克隆到本地：
|
||||
|
||||
按照 [Jekyll 官方文档](https://jekyllrb.com/docs/installation/) 完成基础环境的安装 (`Ruby`，`RubyGem`，`Bundler`)。
|
||||
```terminal
|
||||
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
|
||||
```
|
||||
|
||||
为了使用项目内免费提供的脚本工具增进写作体验，如果你的机器系统是 Debian 或者 macOS，则需要确保安装了 [GNU coreutils](https://www.gnu.org/software/coreutils/)。否则，通过以下方式获得：
|
||||
### 设置本地环境
|
||||
|
||||
如果你想在本地运行或构建, 参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/)安装 `Ruby`， `RubyGems` 和 `Bundler`。
|
||||
|
||||
|
||||
首次运行或构建时, 请先安装 Jekyll plugins。在项目根目录运行：
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
|
||||
`bundle` 会自动安装 `Gemfile` 内指定的依赖插件。
|
||||
|
||||
另外，为了生成一些额外的文件（ Post 的分类、标签以及更新时间列表），需要用到一些脚本工具。如果你电脑的操作系统是 Debian 或者 macOS，请确保已经安装了[GNU coreutils](https://www.gnu.org/software/coreutils/)，否则，通过以下方式完成安装：
|
||||
|
||||
* Debian
|
||||
|
||||
|
|
@ -61,91 +76,42 @@
|
|||
$ brew install coreutils
|
||||
```
|
||||
|
||||
接着，[fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 一份代码，然后克隆你 Fork 的仓库到本地机器上。
|
||||
|
||||
## 使用
|
||||
|
||||
运行 [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) 需要一些额外的文件, 它们不能通过 Jekyll 原生的命令生成，所以请严格依照下列说明去运行或部署此项目。
|
||||
|
||||
### 初始化
|
||||
|
||||
在项目根目录，开始初始化:
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
|
||||
$ bash tools/init.sh
|
||||
```
|
||||
|
||||
把上述的`USER` 替换为你的 GitHub username。
|
||||
> 如果你不打算部署到 GitHub Pages, 在上述命令后附加参数选项 `--no-gh`。
|
||||
|
||||
上述脚本完成了以下工作:
|
||||
|
||||
### 安装 Jekyll 插件
|
||||
1. 从你的仓库中删除了:
|
||||
- `.travis.yml`
|
||||
- `.github` 下的文件和目录
|
||||
- `_posts` 下的文件
|
||||
- `docs` 目录
|
||||
|
||||
本地首次运行或编译，请在项目根目录下运行:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
`bundle` 命令会自动安装 `Gemfile` 内声明的依赖插件.
|
||||
|
||||
|
||||
|
||||
## 运行指南
|
||||
|
||||
### 文件目录
|
||||
|
||||
下面是主要的文件目录：
|
||||
|
||||
```sh
|
||||
jekyll-theme-chirpy/
|
||||
├── _data
|
||||
├── _includes
|
||||
├── _layouts
|
||||
├── _posts # posts stay here
|
||||
├── _scripts
|
||||
├── .travis.yml # remove it
|
||||
├── .github # remove this, too
|
||||
├── assets
|
||||
├── tabs
|
||||
│ └── about.md # the ABOUT page
|
||||
├── .gitignore
|
||||
├── 404.html
|
||||
├── Gemfile
|
||||
├── LICENSE
|
||||
├── README.md
|
||||
├── _config.yml # configuration file
|
||||
├── tools # script tools
|
||||
├── docs
|
||||
├── feed.xml
|
||||
├── index.html
|
||||
├── robots.txt
|
||||
└── sitemap.xml
|
||||
```
|
||||
|
||||
|
||||
如备注所述，部分文件或目录需要被删除:
|
||||
|
||||
```terminal
|
||||
$ rm -rf .travis.yml .github _posts/*
|
||||
```
|
||||
2. 配置了 GitHub Actions：把 `.github/workflows/` 的文件 `pages-deploy.yml.hook` 重命名为 `pages-deploy.yml`。
|
||||
|
||||
3. 自动提交一个 Commit 以保存文件的更改。
|
||||
|
||||
### 配置文件
|
||||
|
||||
根据个人需要去修改 `_config.yml` 的变量，大部分都有注释介绍用法。
|
||||
根据个人需要去修改 `_config.yml` 的变量，大部分都有注释介绍用法。典型的几个选项是：
|
||||
|
||||
* `url`
|
||||
|
||||
定义网站 URL，注意结尾不带 `/`。格式： `<protocol>://<domain>`.
|
||||
|
||||
* `avatar`
|
||||
|
||||
定义头像，示例的文件放置在：`/assets/img/sample/avatar.jpg`. 把它换成你自己的头像，路径不限定，越小越好。(压缩图像体积可上这个网站：*<https://tinypng.com/>* ).
|
||||
|
||||
* `timezone`
|
||||
|
||||
定义时区 ，默认为 `亚洲/上海`，如果肉身翻墙要换城市可在此列表找到： [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) 或者 [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
||||
|
||||
* `theme_mode`
|
||||
|
||||
定义颜色方案，有三种可选：:
|
||||
|
||||
- **dual** - 自动跟随系统的 `深色`/`浅色` 设置，当系统或者浏览器不支持深色模式，则默认显示为浅色模式。无论如何，侧边栏左下角都会显示一个颜色切换按钮。
|
||||
- **dark** - 全程深色模式。
|
||||
- **light** - 全程浅色模式。
|
||||
|
||||
|
||||
### 本地运行
|
||||
|
||||
使用以下工具可轻松运行:
|
||||
|
|
@ -158,24 +124,30 @@ $ bash tools/run.sh
|
|||
|
||||
如果你想在本地服务运行后，把修改源文件的更改实时刷新，可使用选项 `-r` (或 `--realtime`)，不过要先安装依赖 [**fswatch**](http://emcrisostomo.github.io/fswatch/) 。
|
||||
|
||||
### 部署到 GitHub Pages
|
||||
|
||||
### 部署
|
||||
|
||||
部署开始前，把 `_config.yml` 的 `url` 改为 `https://<username>.github.io`(或者你的私有域名，如：`https://yourdomain.com`)。另外，如果你想使用 [Project 类型网站](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)，修改配置文件的 `baseurl` 为项目名称，以斜杠开头，如：`/project`。
|
||||
|
||||
#### 方法 1: 由 GitHub Pages 生成站点
|
||||
假设你已经完成了 [初始化](#初始化)，现在你可以选择下列其中一个方式去站点部署。
|
||||
|
||||
依照本方法，你可以直接把源码推送到远端仓库。
|
||||
#### 部署到 GitHub Pages
|
||||
|
||||
> **注**: 如果你想使用任何不在这个[列表](https://pages.github.com/versions/)上的插件，越过此方法，直接看 [*方法 2: 本地构建*](#方法-2-本地构建).
|
||||
由于安全原因，GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用脚本工具去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。
|
||||
|
||||
**1**. 仓库改名为:
|
||||
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
|
||||
|
||||
|站点类型 | 仓库名称|
|
||||
|:---|:---|
|
||||
|User or Organization | `<username>.github.io`|
|
||||
|Project| `<username>.github.io` 以外的名字，譬如 `project`|
|
||||
2. 除非你是使用 project 站点, 否则重命名你的仓库为 `<username>.github.io`。
|
||||
|
||||
**2**. 提交本地更改，然后运行:
|
||||
3. 选择分支 `gh-pages` 作为 GitHub Pages 的源.
|
||||
|
||||
4. 按照 GitHub 指示的地址去访问你的网站。
|
||||
|
||||
#### 部署到其他 Pages 平台
|
||||
|
||||
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。不过先别慌，可以通过工具来弥补这个遗憾。
|
||||
|
||||
先把本地仓库的 upstream 改为新平台的仓库地址，推送一发。以后每次更新内容后，提交 commit ，然后运行:
|
||||
|
||||
```console
|
||||
$ bash tools/publish.sh
|
||||
|
|
@ -192,50 +164,17 @@ $ bash tools/publish.sh
|
|||
[INFO] Published successfully!
|
||||
```
|
||||
|
||||
**3**. 到 GitHub 网页为该项目开启 Pages 服务。
|
||||
最后，根据平台的说明文档为项目开启 Pages 服务。
|
||||
|
||||
**4**. 网站将运行在：
|
||||
#### 部署到私人服务器
|
||||
|
||||
|站点类型 | 网站 URL |
|
||||
|:---|:---|
|
||||
|User or Organization | `https://<username>.github.io/`|
|
||||
|Project| `https://<username>.github.io/project/`|
|
||||
|
||||
|
||||
#### 方法 2: 本地构建
|
||||
|
||||
由于安全原因，GitHub Pages 不允许第三方插件运行，如果你想突破规则，就要本地构建站点内容。
|
||||
|
||||
**1**. 到 GitHub 网页，创建一个新的仓库，根据以下规则命名:
|
||||
|
||||
|站点类型 | 仓库名称|
|
||||
|:---|:---|
|
||||
|User or Organization | `<username>.github.io`|
|
||||
|Project| `<username>.github.io` 以外的名字， 例如 `project`|
|
||||
|
||||
然后 Clone 新仓库到本地。
|
||||
|
||||
**2**. 构建站点:
|
||||
在项目更目录，运行:
|
||||
|
||||
```console
|
||||
$ bash tools/build.sh -d /path/to/local/project/
|
||||
$ bash tools/build.sh -d /path/to/site/
|
||||
```
|
||||
> `project` 为新仓库名称。
|
||||
|
||||
生成的静态文件将会在 `/path/to/local/project`. 把新仓库的修改提交并推送到远端 `master` 分支.
|
||||
|
||||
**3**. 回到 GithHub 网页，为该仓库开启 Pages 服务。
|
||||
|
||||
**4**. 网站将运行在:
|
||||
|
||||
|站点类型 | 站点 URL |
|
||||
|:---|:---|
|
||||
|User or Organization | `https://<username>.github.io/`|
|
||||
|Project| `https://<username>.github.io/project/`|
|
||||
|
||||
#### 结束工作
|
||||
|
||||
无论你选择了哪种方式部署网站到 GitHub Pages, 请开启 `HTTPS` 功能。具体细节参考官方说明：[Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https)。
|
||||
生成的静态文件将会在 `/path/to/site/`， 把内部的文件上传到服务器即可。
|
||||
|
||||
### 文档
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue