web/README.md

262 lines
10 KiB
Markdown
Raw Normal View History

2020-04-05 14:01:34 +03:00
# Chirpy
2020-04-12 19:38:56 +03:00
🌏 English • [简体中文](docs/README_zh-CN.md)
2019-09-30 15:37:14 +03:00
2020-01-21 22:05:06 +03:00
[![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=event%3Apush)
2019-09-30 15:37:14 +03:00
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
2020-01-04 12:05:41 +03:00
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
2020-04-12 19:38:56 +03:00
A minimal, sidebar, responsive web design Jekyll theme, focusing on text presentation, aim to help you easily record and share your knowledge. [Live Demo »](https://chirpy.cotes.info)
2019-09-30 15:37:14 +03:00
2020-04-12 19:38:56 +03:00
[![Devices Mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)](https://chirpy.cotes.info)
## Table of Contents
* [Features](#features)
* [Installing](#installing)
* [Usage](#usage)
* [Contributing](#contributing)
* [Credits](#credits)
* [Support](#support)
* [License](#license)
## Features
2019-09-30 15:37:14 +03:00
2020-04-05 14:01:34 +03:00
* Configurable theme mode
* Two-level Categories
* Last modified date for posts
2019-09-30 15:37:14 +03:00
* Table of Contents
2020-04-05 14:01:34 +03:00
* Automatically recommend related posts
2019-09-30 15:37:14 +03:00
* Syntax highlighting
* Search
2019-12-31 20:24:54 +03:00
* Atom Feeds
* Disqus Comments
2019-09-30 15:37:14 +03:00
* Google Analytics
2020-04-05 14:01:34 +03:00
* GA Pageviews reporting (Advanced)
* SEO and Performance Optimization
2019-09-30 15:37:14 +03:00
2020-01-14 14:57:10 +03:00
## Installing
2019-09-30 15:37:14 +03:00
### Prerequisites
2019-09-30 15:37:14 +03:00
2020-04-12 19:38:56 +03:00
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (`Ruby `, `RubyGems` and `Bundler`).
2019-09-30 15:37:14 +03:00
2020-04-12 19:38:56 +03:00
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:
2019-11-16 18:12:26 +03:00
* Debian
2019-11-16 18:12:26 +03:00
```console
$ sudo apt-get install coreutils
```
* macOS
```console
$ brew install coreutils
```
2020-01-14 14:57:10 +03:00
### Jekyll Plugins
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
```console
2020-04-12 19:38:56 +03:00
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
```
2020-04-12 19:38:56 +03:00
and replace the `USER` above to your GitHub username.
2020-04-12 19:38:56 +03:00
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:
2019-11-16 18:12:26 +03:00
```terminal
2019-09-30 15:37:14 +03:00
$ bundle install
```
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
2019-11-16 18:12:26 +03:00
## Usage
2019-11-16 18:12:26 +03:00
### Directory Structure
2019-11-16 18:12:26 +03:00
The main files and related brief introductions are listed below.
```sh
jekyll-theme-chirpy/
├── _data
├── _includes
├── _layouts
├── _posts # posts stay here
├── _scripts
2020-01-23 11:54:26 +03:00
├── .travis.yml # remove it
├── .github # remove this, too
2019-11-16 18:12:26 +03:00
├── assets
├── tabs
│   └── about.md # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── LICENSE
├── README.md
├── _config.yml # configuration file
2020-01-01 20:21:43 +03:00
├── tools # script tools
├── docs
2019-11-16 18:12:26 +03:00
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml
```
2020-01-04 12:05:41 +03:00
As mentioned above, some files or directories should be removed from your repo:
- .travis.yml
- .github
2020-04-12 19:38:56 +03:00
### Configuration
2019-11-16 18:12:26 +03:00
2020-04-12 19:38:56 +03:00
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
2019-11-16 18:12:26 +03:00
2020-03-02 00:15:49 +03:00
* `url`
2020-03-30 02:34:39 +03:00
Set to your website url and there should be no slash symbol at the tail. Format: `<protocol>://<domain>`.
2020-03-02 00:15:49 +03:00
* `avatar`
2020-01-04 12:05:41 +03:00
2020-03-02 00:15:49 +03:00
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 samll as possible(may be *<https://tinypng.com/>* will help).
2019-11-16 18:12:26 +03:00
2020-03-02 00:15:49 +03:00
* `timezone`
2019-09-30 15:37:14 +03:00
2020-01-04 12:05:41 +03:00
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).
2019-11-16 18:12:26 +03:00
2020-03-02 00:15:49 +03:00
* `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.
2019-11-16 18:12:26 +03:00
2019-11-18 17:36:22 +03:00
### Run Locally
2019-11-16 18:12:26 +03:00
2020-04-12 19:38:56 +03:00
You may want to preview the site content before publishing, so just run the script tool:
2019-11-16 18:12:26 +03:00
```terminal
2020-01-01 20:21:43 +03:00
$ bash tools/run.sh
2019-09-30 15:37:14 +03:00
```
2019-11-16 18:12:26 +03:00
Open a modern brower and visit at <http://localhost:4000>.
2019-11-18 17:36:22 +03:00
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.
2019-11-18 17:36:22 +03:00
2019-11-16 18:12:26 +03:00
### Deploying to GitHub Pages
2020-04-05 14:01:34 +03:00
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`.
2019-11-16 18:12:26 +03:00
#### Option 1: Built by GitHub Pages
2020-01-04 12:05:41 +03:00
By deploying the site in this way, you're allowed to push the source code directly to the remote.
> **Note**: If you want to use any third-party Jekyll plugins that not in [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**1**. Rename the repository to:
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
2020-04-05 14:01:34 +03:00
|Project| Any one except `<username>.github.io`, let's say `project`|
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**2**. Commit the changes of the repo first, then run the initialization script:
2019-11-16 18:12:26 +03:00
```terminal
2020-01-01 20:21:43 +03:00
$ bash tools/init.sh
2019-11-16 18:12:26 +03:00
```
>**Note**: The *Recent Update* requires the posts' latest git-log date, so make sure the changes in `_posts` have been committed before running this command.
2020-03-02 00:15:49 +03:00
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit. 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.
[Automation] Updated the Categories, Tags, Lastmod for post(s).
11 files changed, 46 insertions(+), 3 deletions(-)
...
Updated the Categories, Tags, Lastmod for post(s).
```
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repo.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**4**. Check it out:
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
2019-11-16 18:12:26 +03:00
2019-11-18 17:36:22 +03:00
#### Option 2: Build Locally
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
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 another plugins that not in 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`|
2020-04-05 14:01:34 +03:00
|Project| Any one except `<username>.github.io`, let's say `project`|
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
and clone it.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**2**. In the root of the source project, build your site by:
2019-11-16 18:12:26 +03:00
```console
2020-01-04 12:05:41 +03:00
$ bash tools/build.sh -d /path/to/local/project/
2019-11-16 18:12:26 +03:00
```
2020-01-04 12:05:41 +03:00
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.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**4**. Visit at:
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
2020-04-05 14:01:34 +03:00
#### Finishing work
No matter which way you choose to deploy the website on GitHub, please enforce the `HTTPS` for it. See official docs: [Configuring a publishing source for your GitHub Pages site](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https).
2019-09-30 15:37:14 +03:00
### 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).
## Contributing
2020-04-05 14:01:34 +03:00
The old saying, "Two heads are better than one." Consequently, welcome to report bugs, improve code quality or submit a new feature. For more information, see [contributing guidelines](.github/CONTRIBUTING.md).
## Credits
2019-09-30 15:37:14 +03:00
This theme is mainly built with [Jekyll](https://jekyllrb.com/) ecosystem, [Bootstrap](https://getbootstrap.com/), [Font Awesome](https://fontawesome.com/) and some other wonderful tools(their copyright information can be found in the relevant files).
2019-11-05 17:14:02 +03:00
2020-02-21 19:37:24 +03:00
:tada:Thanks to all the volunteers who contributed to this project, their GitHub IDs are on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget those guys who submitted the issues or unmerged PR because they reported bugs, shared ideas or inspired me to write more readable documentation.
2020-01-04 12:05:41 +03:00
## Support
2020-01-04 12:05:41 +03:00
2020-03-30 02:34:39 +03:00
If you enjoy this theme or find it helpful, please consider becoming my sponsor, I'd really appreciate it! Click the button <kbd>:heart:Sponsor</kbd> at the top of the [Home Page](https://github.com/cotes2020/jekyll-theme-chirpy) and choose a link that suits you to donate; this will encourage and help me better maintain the project.
2019-09-30 15:37:14 +03:00
## License
This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.