From 89aa2b9370c0201ae2a66bc617bc160c2e53bff9 Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Sat, 16 Nov 2019 23:12:26 +0800 Subject: [PATCH] Update docs. --- README.md | 127 ++++++++++++++++++--- _posts/2019-08-09-getting-started.md | 8 +- _posts/2019-08-11-customize-the-favicon.md | 14 +-- 3 files changed, 122 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 9f40f6c..817827b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![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-red.svg)](https://996.icu) -![devices-mockup](assets/img/sample/devices-mockup.png) +![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png) A Jekyll theme with responsive web design that focuses on text presentation. Hope you like it! [Live Demo »](https://chirpy.cotes.info) @@ -21,35 +21,132 @@ A Jekyll theme with responsive web design that focuses on text presentation. Hop * Google Analytics * Pageviews (Advanced) -## Quick start +## Getting Startted -Complete the installation of the following environment dependencies: +### Preparation -- [Ruby](https://www.ruby-lang.org/en/downloads/) -- [RubyGem](https://rubygems.org/pages/download) -- [Bundler](https://bundler.io/) -- [Jekyll](https://jekyllrb.com/) -- [Python](https://www.python.org/downloads/) -- [ruamel.yaml](https://pypi.org/project/ruamel.yaml/) -- [fswatch](http://emcrisostomo.github.io/fswatch/getting.html) +Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In addition, to use the funny script tools, we also need to install [Python](https://www.python.org/downloads/)(version 3.5 or abover), [ruamel.yaml](https://pypi.org/project/ruamel.yaml/) and [fswatch](http://emcrisostomo.github.io/fswatch/getting.html). -Next, [**fork**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) this project and rename as `.github.io`, then clone the replicated repository locally. Go to the root directory and install the Jekyll plugins: +Next, [fork Chirpy](https://github.com/cotes2020/jekyll-theme-chirpy/fork) and then clone the replicated repository locally. -``` + +### Install Jekyll plugins + +Go to root directory of the repository and run the following: + +```terminal $ bundle install ``` -Boot your site locally: +`bundle` will install all the dependent Jekyll Plugins listed in file `Gemfile` automatically. + + +### File structure + +The main files and related brief introductions are listed below. + +```sh +jekyll-theme-chirpy/ +├── _data +├── _includes +├── _layouts +├── _posts # posts stay here +├── _scripts +├── assets +├── tabs +│   └── about.md # the ABOUT page +├── .gitignore +├── .travis.yml # remove it +├── 404.html +├── Gemfile +├── LICENSE +├── README.md +├── _config.yml # configuration file +├── build.sh # script tool +├── run.sh # script tool +├── init.sh # script tool +├── pv.sh +├── feed.xml +├── index.html +├── robots.txt +├── search.json +└── sitemap.xml +``` + + +### Configuration + +Customize the variables in file `_config.yml` as needed. + + +### Atom Feed + +The Atom feed url of your site will be: ``` +/feed.xml +``` + +The `SITE_URL` was defined by variable `url` in file `_config.yml`. + + +### Run locally + +You may want to preview the site before publishing, so just run the script tool: + +```terminal $ bash run.sh ``` +>**Note**: Because the *Recent Update* required the latest git-log date of posts, so make sure the changes of `_posts` have been committed before running this command. -Now, open your favorite brower and visit +Open a brower and visit + +### Deploying to GitHub Pages + +Before the deployment begins, ensure the `url` in `_config.yml` has been set to `https://.github.io`. + +#### Option 1: Built by GitHub Pages + +By deploying your site in this way, you can push the source code to GitHub repository directly. + +> **Note**: If you want to add any third-party Jekyll plugins or custom scripts to your project, please refer to [*Option 2: Build locally*](#option-2-build-locally). + +**1**. Rename your repository as `.github.io`. + +**2**. Commit the changes of your repository, then run the initialization script: + +```console +$ bash init.sh +``` + +It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts. + +**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repository `.github.io`. + +**4**. Visit `https://.github.io` and enjoy. + + +#### Option 2: Build locally + +For security reasons, GitHub Pages runs on `safe` mode, which means the third-party Jekyll plugins or custom scripts will not work. If you want to use any another third-party Jekyll plugins, **your have to build locally rather than on GitHub Pages**. + +**1**. On GitHub website, create a brand new repository with name `.github.io` and then clone it locally. + +**2**. Build your site by: + +```console +$ bash build.sh -d /path/to/.github.io/ +``` + +The build results will be stored in the root directory of `.github.io` and don't forget to push the changes of `.github.io` to branch `master` on GitHub. + +**3**. Go to GitHub website and enable GitHub Pages service for the new repository `.github.io`. + +**4**. Visit `https://.github.io` and enjoy. ## Documentation -For more details, please check the [tutorial](https://chirpy.cotes.info/posts/getting-started/). BTW, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki). +For more information, please see the [tutorial](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). ## License diff --git a/_posts/2019-08-09-getting-started.md b/_posts/2019-08-09-getting-started.md index 045a763..fca4ca5 100644 --- a/_posts/2019-08-09-getting-started.md +++ b/_posts/2019-08-09-getting-started.md @@ -1,5 +1,5 @@ --- -title: Getting Started +title: Getting started date: 2019-08-09 20:55:00 +0800 categories: [Blogging, Tutorial] tags: [getting started] @@ -7,7 +7,7 @@ tags: [getting started] ## Preparation -First of all, follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In addition, to use the funny script tools, we also need to install [Python](https://www.python.org/downloads/)(version 3.5 or abover), [ruamel.yaml](https://pypi.org/project/ruamel.yaml/) and [fswatch](http://emcrisostomo.github.io/fswatch/getting.html). +Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In addition, to use the funny script tools, we also need to install [Python](https://www.python.org/downloads/)(version 3.5 or abover), [ruamel.yaml](https://pypi.org/project/ruamel.yaml/) and [fswatch](http://emcrisostomo.github.io/fswatch/getting.html). Next, [fork Chirpy](https://github.com/cotes2020/jekyll-theme-chirpy/fork) and then clone the replicated repository locally. @@ -85,7 +85,7 @@ Open a brower and visit ## Deploying to GitHub Pages -Before the deployment begins, rename your project as `.github.io` and ensure the `url` in `_config.yml` has been set to `https://.github.io`. +Before the deployment begins, ensure the `url` in `_config.yml` has been set to `https://.github.io`. ### Option 1: Built by GitHub Pages @@ -112,7 +112,7 @@ It will automatically generates the *Latest Modified Date* and *Categories / Tag For security reasons, GitHub Pages runs on `safe` mode, which means the third-party Jekyll plugins or custom scripts will not work. If you want to use any another third-party Jekyll plugins, **your have to build locally rather than on GitHub Pages**. -**1**. On GitHub website, create a brand new repository with name `.github.io`, then clone it locally. +**1**. On GitHub website, create a brand new repository with name `.github.io` and then clone it locally. **2**. Build your site by: diff --git a/_posts/2019-08-11-customize-the-favicon.md b/_posts/2019-08-11-customize-the-favicon.md index 20e0143..3c364c5 100644 --- a/_posts/2019-08-11-customize-the-favicon.md +++ b/_posts/2019-08-11-customize-the-favicon.md @@ -6,23 +6,21 @@ tags: [favicon] toc: false --- -The image files of [Favicons](https://www.favicon-generator.org/about/) are placed in `assets/img/favicons`. You may need to replace them with your own. So let's see how to customize these Favicons. +In [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/), the image files of [Favicons](https://www.favicon-generator.org/about/) are placed in `assets/img/favicons/`. You may need to replace them with your own. So let's see how to customize these Favicons. Whit a square image (PNG, JPG or GIF) in hand, open the site [*Favicon & App Icon Generator*](https://www.favicon-generator.org/) and upload your original image. -![upload-image]({{ site.baseurl }}/assets/img/sample/upload-image.png) +![upload-image](/assets/img/sample/upload-image.png) Click button Create Favicon and wait a moment for the website to generate the icons of various sizes automatically. -![download-icons]({{ site.baseurl }}/assets/img/sample/download-icons.png) +![download-icons](/assets/img/sample/download-icons.png) -Download the generated package and extract, then remove the following two of them: +Download the generated package, unzip and delete the following two from the extracted files: - browserconfig.xml - manifest.json -Now, copy the rest (`.PNG` and `.ICO`) to cover the original files in folder `assets/img/favicons`. - -In the end, rebuild your site so that the icon becomes your custom edition. - +Now, copy the rest image files (`.PNG` and `.ICO`) to cover the original one in folder `assets/img/favicons/`. +At last, don't forget to rebuild your site so that the icon becomes your custom edition.