diff --git a/.github/workflows/pages-deploy.yml.hook b/.github/workflows/pages-deploy.yml.hook new file mode 100644 index 0000000..6d3ac74 --- /dev/null +++ b/.github/workflows/pages-deploy.yml.hook @@ -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 diff --git a/README.md b/README.md index aef6ef0..52a2f90 100644 --- a/README.md +++ b/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:/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: `://`. - - * `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 ** 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 . +Then open a browser and visit to . -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 `.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 | `.github.io`| -|Project| Any one except `.github.io`, let's say `project`| +2. Unless you prefer to project sites, rename your repository to `.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://.github.io/`| -|Project| `https://.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 | `.github.io`| -|Project| Any one except `.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://.github.io/`| -|Project| `https://.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 @@ -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 :heart:Sponsor 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 :heart: Sponsor 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 diff --git a/_includes/disqus.html b/_includes/disqus.html index 2aa49d3..4b4b149 100644 --- a/_includes/disqus.html +++ b/_includes/disqus.html @@ -7,8 +7,10 @@ MIT License --> -
-

Comments powered by Disqus.

+
+

+ Comments powered by Disqus. +

diff --git a/_includes/related-posts.html b/_includes/related-posts.html index fa256f3..03c1828 100644 --- a/_includes/related-posts.html +++ b/_includes/related-posts.html @@ -84,7 +84,7 @@ {% if index_list.size > 0 %} -