Skip to content

Commit

Permalink
Merge branch 'release/2.5'
Browse files Browse the repository at this point in the history
  • Loading branch information
@cotes2020
cotes2020 committed Aug 2, 2020
2 parents c0e7521 + 3e118de commit 6275196
Show file tree
Hide file tree
Showing 18 changed files with 482 additions and 464 deletions.
99 changes: 99 additions & 0 deletions .github/workflows/pages-deploy.yml.hook
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
name: 'Automatic build'
on:
push:
branches:
- master
paths-ignore:
- '.gitignore'
- 'README.md'
- 'LICENSE'

jobs:
build-n-test:
runs-on: ubuntu-latest

steps:
- uses: actions/setup-ruby@v1
with:
ruby-version: '2.6.x'

- name: Checkout
uses: actions/checkout@v2
with:
fetch-depth: 0

- name: Bundle Caching
id: bundle-cache
uses: actions/cache@v1
with:
path: vendor/bundle
key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
restore-keys: |
${{ runner.os }}-gems-

- name: Bundle config
run: |
bundle config path vendor/bundle

- name: Bundle Install
if: steps.bundle-cache.outputs.cache-hit != 'true'
run: |
bundle install

- name: Bundle Install locally
if: steps.bundle-cache.outputs.cache-hit == 'true'
run: |
bundle install --local

- name: Build Site
run: |
bash tools/build.sh -b ""

- name: Test Site
run: |
bash tools/test.sh

deploy:
needs: build-n-test
runs-on: ubuntu-latest

steps:
- uses: actions/setup-ruby@v1
with:
ruby-version: '2.6.x'

- name: Checkout
uses: actions/checkout@v2
with:
fetch-depth: 0

- name: Bundle Caching
id: bundle-cache
uses: actions/cache@v1
with:
path: vendor/bundle
key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
restore-keys: |
${{ runner.os }}-gems-

- name: Bundle config
run: |
bundle config path vendor/bundle

- name: Bundle Install
if: steps.bundle-cache.outputs.cache-hit != 'true'
run: |
bundle install

- name: Bundle Install locally
if: steps.bundle-cache.outputs.cache-hit == 'true'
run: |
bundle install --local

- name: Build site
run: |
bash tools/build.sh

- name: Deploy
run: |
bash tools/deploy.sh
195 changes: 65 additions & 130 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand All @@ -58,131 +73,84 @@ 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.

```console
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
```

And replace the `USER` above to your GitHub username.
### Initialization

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:
Go to the root directory of the project and start initialization:

```terminal
$ bundle install
```console
$ bash tools/init.sh
```

`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.


## Usage


### 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
├── docs
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml
```
> 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:

As mentioned above, some files or directories should be removed from your repo:
1. Remove some files or directories from your repository:
- `.travis.yml`
- everything under `.github/`
- files under `_posts/`
- folder `docs/`

```terminal
$ rm -rf .travis.yml .github _posts/*
```
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

### 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 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.

### Deployment

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.
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`.

### Deploying to GitHub Pages
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.

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`.
#### Deploy on GitHub Pages

#### Option 1: Built by 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.

By deploying the site in this way, you're allowed to push the source code directly to the remote.
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.

> **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).
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.

**1**. Rename the repository to:
3. Choose branch `gh-pages` as your GitHub Pages source.

|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| Any one except `<username>.github.io`, let's say `project`|
4. Visit your website at the address indicated by GitHub.

**2**. Commit the changes of the repo first, then run the publish script:
#### 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
```

> 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).
Expand All @@ -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.

**4**. Check it out:
Lastly, enable the pages service according to the instructions of the platform you choose.

|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
#### Deploy on Private Server


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

Expand All @@ -247,14 +182,14 @@ The old saying, "Two heads are better than one." Consequently, welcome to report

## Credits

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).
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).

: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.
: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.


## Support

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


## License
Expand Down
Loading

0 comments on commit 6275196

Please sign in to comment.