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 the docs for discarded tools

Browse Source
This commit is contained in:
Cotes Chung
2020-11-19 21:32:50 +08:00
parent 8fa1f3b497
commit ea56a900a0
6 changed files with 52 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
README.md
View File

@@ -58,32 +58,16 @@ $ 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/).
- on Debian:
```console
$ sudo apt-get install coreutils
```
- on macOS:
```console
$ brew install coreutils
```
### Setting up Docker environment (optional)
If you're a loyal fan of [**Docker**](https://www.docker.com/) or just too lazy to install the packages mentioned in [_Setting up the local envrionment_](#setting-up-the-local-envrionment), please make sure you have **Docker Engine** installed and running, and then get Docker image `jekyll/jekyll` from Docker Hub by the following command:
```console
$ docker pull jekyll/jekyll:latest
$ docker pull jekyll/jekyll
```
## 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.
### Initialization
Go to the root directory of the project and start initialization:
@@ -120,26 +104,22 @@ Generally, go to `_config.yml` and configure the variables as needed. Some of th
You may want to preview the site contents before publishing, so just run it by:
```terminal
$ bash tools/run.sh
$ bundle exec jekyll s
```
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.
### Run on Docker
Run the site on Docker with the following command:
```terminal
$ docker run --rm -it \
$ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \
bash tools/run.sh --docker
jekyll serve
```
Please note that on Docker containers, you'll lose the real-time refresh feature.
### 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`.
@@ -148,7 +128,7 @@ Assuming you have already gone through the [initialization](#initialization), yo
#### 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 plugins 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 and successful, a new remote branch named `gh-pages` will appear to store the built site files.
@@ -164,18 +144,17 @@ On platforms other than GitHub, we cannot enjoy the convenience of **GitHub Acti
Go to the root of the source project, build your site by:
```console
$ bash tools/build.sh
$ JEKYLL_ENV=production bundle exec jekyll b
```
> **Note**: The output path can be specified with the option `-d`.
Or, build the site with Docker by:
```terminal
$ docker run --rm -it \
$ docker run -it --rm \
--env JEKYLL_ENV=production \
--volume="$PWD:/srv/jekyll" \
jekyll/jekyll \
bash tools/build.sh --docker
jekyll build
```
Unless you specified the output path, the generated site files will be placed in folder `_site` of the project's root directory. Now you should upload those files to your web server.