Update docs.
This commit is contained in:
parent
bb60c9dcf8
commit
89aa2b9370
3 changed files with 122 additions and 27 deletions
127
README.md
127
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 `<username>.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:
|
||||
|
||||
```
|
||||
<SITE_URL>/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 <http://127.0.0.1:4000>
|
||||
Open a brower and visit <http://127.0.0.1:4000>
|
||||
|
||||
### Deploying to GitHub Pages
|
||||
|
||||
Before the deployment begins, ensure the `url` in `_config.yml` has been set to `https://<username>.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 `<username>.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 `<username>.github.io`.
|
||||
|
||||
**4**. Visit `https://<username>.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 `<username>.github.io` and then clone it locally.
|
||||
|
||||
**2**. Build your site by:
|
||||
|
||||
```console
|
||||
$ bash build.sh -d /path/to/<username>.github.io/
|
||||
```
|
||||
|
||||
The build results will be stored in the root directory of `<username>.github.io` and don't forget to push the changes of `<username>.github.io` to branch `master` on GitHub.
|
||||
|
||||
**3**. Go to GitHub website and enable GitHub Pages service for the new repository `<username>.github.io`.
|
||||
|
||||
**4**. Visit `https://<username>.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
|
||||
|
|
|
@ -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 <http://127.0.0.1:4000>
|
|||
|
||||
## Deploying to GitHub Pages
|
||||
|
||||
Before the deployment begins, rename your project as `<username>.github.io` and ensure the `url` in `_config.yml` has been set to `https://<username>.github.io`.
|
||||
Before the deployment begins, ensure the `url` in `_config.yml` has been set to `https://<username>.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 `<username>.github.io`, then clone it locally.
|
||||
**1**. On GitHub website, create a brand new repository with name `<username>.github.io` and then clone it locally.
|
||||
|
||||
**2**. Build your site by:
|
||||
|
||||
|
|
|
@ -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 <kbd>Create Favicon</kbd> 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.
|
||||
|
|
Loading…
Reference in a new issue