f.weber/jekyll-theme-chirpy
Template
1
0
Fork 0
mirror of https://github.com/cotes2020/jekyll-theme-chirpy.git synced 2025-12-18 05:41:31 +00:00
Code Issues Packages Releases Activity

Update docs for v2.5

Browse Source
This commit is contained in:
Cotes Chung
2020-08-03 02:25:40 +08:00
parent 1c3c22bb68
commit adff74b27b
4 changed files with 210 additions and 393 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
_posts/2019-08-08-write-a-new-post.md
View File

@@ -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
---

180
_posts/2019-08-09-getting-started.md
View File

@@ -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.
- **dark** - Always show dark mode.
- **light** - Always show light mode.
## Run Locally
### 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.