From 152a0588148785966765e5ee66c9ff95151eb87a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=BE=E3=81=A4=E3=81=BE=E3=81=A4?= Date: Sat, 18 Dec 2021 03:46:38 +0900 Subject: [PATCH] Update README.md --- README.md | 248 +----------------------------------------------------- 1 file changed, 1 insertion(+), 247 deletions(-) diff --git a/README.md b/README.md index 83bf90c3..9918a17f 100644 --- a/README.md +++ b/README.md @@ -1,247 +1 @@ -
- - EN / [中文](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/README.zh-CN.md) - -
- -
- - # Chirpy Jekyll Theme - - A minimal, responsive, and powerful Jekyll theme for presenting professional writing. - - [![Gem Version](https://img.shields.io/gem/v/jekyll-theme-chirpy?color=brightgreen)](https://rubygems.org/gems/jekyll-theme-chirpy) - [![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush) - [![Codacy Badge](https://app.codacy.com/project/badge/Grade/4e556876a3c54d5e8f2d2857c4f43894)](https://www.codacy.com/gh/cotes2020/jekyll-theme-chirpy/dashboard?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade) - [![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) - [![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu) - - [**Live Demo →**](https://chirpy.cotes.info) - - [![Devices Mockup](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images@0a003683c0c3ca549d12c309f9b3e03ea20981e5/commons/devices-mockup.png)](https://chirpy.cotes.info) - -
- -## Features - -- Localized Layout -- Configurable Theme Mode -- Pinned Posts -- Hierarchical Categories -- Last Modified Date for Posts -- Table of Contents -- Automatically Recommend Related Posts -- Syntax Highlighting -- Mathematical Expressions -- Mermaid Diagram & Flowchart -- Search -- Atom Feeds -- Disqus Comments -- Google Analytics -- GA Pageviews Reporting (Advanced) -- SEO & Performance Optimization - -## Prerequisites - -Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll`, and `Bundler`. - -## Installation - -### Creating a New Site - -There are two ways to create a new repository for this theme: - -- [**Using the Chirpy Starter**](#option-1-using-the-chirpy-starter) - Easy to upgrade, isolates irrelevant project files so you can focus on writing. -- [**Forking on GitHub**](#option-2-forking-on-github) - Convenient for custom development, but difficult to upgrade. Unless you are familiar with Jekyll and are determined to tweak or contribute to this project, this approach is not recommended. - -#### Option 1. Using the Chirpy Starter - -Create a new repository from the [**Chirpy Starter**][use-starter] and name it `.github.io`, where `GH_USERNAME` represents your GitHub username. - -#### Option 2. Forking on GitHub - -[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub and rename it to `.github.io`. Please note that the default branch code is in development. If you want the site to be stable, please switch to the [latest tag][latest-tag] and start writing. - -And then execute: - -```console -$ bash tools/init.sh -``` - -> **Note**: If you don't want to deploy your site on GitHub Pages, append option `--no-gh` at the end of the above command. - -The above command will: - -1. Removes some files or directories from your repository: - - - `.travis.yml` - - files under `_posts` - - folder `docs` - -2. If the option `--no-gh` is provided, the directory `.github` will be deleted. Otherwise, set up the GitHub Action workflow by removing the extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in the folder `.github`. - -3. Removes item `Gemfile.lock` from `.gitignore`. - -4. Creates a new commit to save the changes automatically. - -### Installing Dependencies - -Before running for the first time, go to the root directory of your site, and install dependencies as follows: - -```console -$ bundle -``` - -## Usage - -### Configuration - -Update the variables of `_config.yml` as needed. Some of them are typical options: - -- `url` -- `avatar` -- `timezone` -- `lang` - -### Customing Stylesheet - -If you need to customize the stylesheet, copy the theme's `assets/css/style.scss` to the same path on your Jekyll site, and then add the custom style at the end of the style file. - -Starting from [`v4.1.0`][chirpy-4.1.0], if you want to overwrite the SASS variables defined in `_sass/addon/variables.scss`, create a new file `_sass/variables-hook.scss` and assign new values to the target variable in it. - -### Running Local Server - -You may want to preview the site contents before publishing, so just run it by: - -```console -$ bundle exec jekyll s -``` - -Or run the site on Docker with the following command: - -```console -$ docker run -it --rm \ - --volume="$PWD:/srv/jekyll" \ - -p 4000:4000 jekyll/jekyll \ - jekyll serve -``` - -After a while, the local service will be published at __. - -### Deployment - -Before the deployment begins, check out 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 starts with a slash, e.g, `/project-name`. - -Now you can choose ONE of the following methods to deploy your Jekyll site. - -#### Deploy by Using Github Actions - -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 GitHub Pages service. - -Quickly check the files needed for GitHub Actions build: - -- Ensure your Jekyll site has the file `.github/workflows/pages-deploy.yml`. Otherwise, create a new one and fill in the contents of the [sample file][workflow], and the value of the `on.push.branches` should be the same as your repo's default branch name. - -- Ensure your Jekyll site has file `tools/deploy.sh`. Otherwise, copy it from here to your Jekyll site. - -- Furthermore, if you have committed `Gemfile.lock` to the repo, and your runtime system is not Linux, don't forget to update the platform list in the lock file: - - ```console - $ bundle lock --add-platform x86_64-linux - ``` - -After the above steps, rename your repository to `.github.io` on GitHub. - -Now publish your Jekyll site by: - -1. Push any commit to remote 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. - -2. Browse to your repository on GitHub. Select the tab _Settings_, then click _Pages_ in the left navigation bar, and then in the section **Source** of _GitHub Pages_, select the `/(root)` directory of branch `gh-pages` as the [publishing source][pages-src]. Remember to click Save before leaving. - - ![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images@0a003683c0c3ca549d12c309f9b3e03ea20981e5/posts/20190809/gh-pages-sources.png) - -3. Visit your website at the address indicated by GitHub. - -#### Manually Build and Deploy - -On self-hosted servers, you cannot enjoy the convenience of **GitHub Actions**. Therefore, you should build the site on your local machine and then upload the site files to the server. - -Go to the root of the source project, and build your site as follows: - -```console -$ JEKYLL_ENV=production bundle exec jekyll b -``` - -Or build the site on Docker: - -```console -$ docker run -it --rm \ - --env JEKYLL_ENV=production \ - --volume="$PWD:/srv/jekyll" \ - jekyll/jekyll \ - 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 the target server. - -### Upgrading - -It depends on how you use the theme: - -- If you are using the theme gem (there will be `gem "jekyll-theme-chirpy"` in the `Gemfile`), editing the `Gemfile` and update the version number of the theme gem, for example: - - ```diff - - gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1" - + gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0" - ``` - - And then execute the following command: - - ```console - $ bundle update jekyll-theme-chirpy - ``` - - As the version upgrades, the critical files (for details, see the [Startup Template][starter]) and configuration options will change. Please refer to the [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide) to keep your repo's files in sync with the latest version of the theme. - -- If you forked from the source project (there will be `gemspec` in the `Gemfile` of your site), then merge the [latest upstream tags][latest-tag] into your Jekyll site to complete the upgrade. -The merge is likely to conflict with your local modifications. Please be patient and careful to resolve these conflicts. - -## Documentation - -For more details and a better reading experience, please check out the [tutorials on the 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). Please note that the tutorials on the demo website or Wiki are based on the latest release, and the features of `master` branch are usually ahead of the documentation. - -## Contributing - -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 - -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). The avatar and favicon design come from [Clipart Max](https://www.clipartmax.com/middle/m2i8b1m2K9Z5m2K9_ant-clipart-childrens-ant-cute/). - -: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. - -Last but not least, thank [JetBrains][jb] for providing the open source license. - -## Sponsoring - -If you like this theme or find it helpful, please consider sponsoring me, because it will encourage and help me better maintain the project, I will be very grateful! - -[![Ko-fi](https://img.shields.io/badge/-Buy%20Me%20a%20Coffee-ff5f5f?logo=ko-fi&logoColor=white)](https://ko-fi.com/coteschung) -[![Wechat Pay](https://img.shields.io/badge/-Tip%20Me%20on%20WeChat-brightgreen?logo=wechat&logoColor=white)][cn-donation] -[![Alipay](https://img.shields.io/badge/-Tip%20Me%20on%20Alipay-blue?logo=alipay&logoColor=white)][cn-donation] - -## License - -This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License. - -[starter]: https://github.com/cotes2020/chirpy-starter -[use-starter]: https://github.com/cotes2020/chirpy-starter/generate -[workflow]: https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook -[chirpy-4.1.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v4.1.0 -[pages-src]: https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site -[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags - - - -[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy -[cn-donation]: https://cotes.gitee.io/alipay-wechat-donation/ +My personal blog.