Skip to content

Commit

Permalink
Updated Docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@cotes2020
cotes2020 committed Jan 13, 2020
1 parent 65de16d commit 8d30507
Show file tree
Hide file tree
Showing 8 changed files with 355 additions and 62 deletions.
2 changes: 1 addition & 1 deletion .github/FUNDING.yml
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
custom: ['https://www.buymeacoffee.com/6wOkxTo', 'https://cotes.gitee.io/alipay-wechat-donation']
custom: ['https://www.buymeacoffee.com/coteschung', 'https://cotes.gitee.io/alipay-wechat-donation']
108 changes: 79 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,21 @@

[![Build Status](https://travis-ci.com/cotes2020/jekyll-theme-chirpy.svg?branch=master)](https://travis-ci.com/cotes2020/jekyll-theme-chirpy)
[![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)
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)

English | [中文](README_zh-CN.md)

![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)

A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design and focuses on text presentation. Hope you like it! [Live Demo »](https://chirpy.cotes.info)
A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design and focuses on text exhibition. It will help you easily record, manage and share your knowledge and experience. Hope you like it! [**Live Demo** »](https://chirpy.cotes.info)


## Features

* Auto Dark Mode
* Posts' Last Modified Date
* Table of Contents
* Recommand Related Post Automatically
* Disqus Comments
* Syntax highlighting
* Two Level Categories
Expand All @@ -23,18 +28,18 @@ A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design
* SEO Tag
* Performance Optimization

## Getting Started
## Quick Start

### Preparation

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) and [ruamel.yaml](https://pypi.org/project/ruamel.yaml/).

Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your replicated repository locally.
Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your forked repo locally.


### Install Jekyll Plugins

Go to root directory of the repository and run the following:
Go to the root of repo and run:

```terminal
$ bundle install
Expand All @@ -56,7 +61,7 @@ jekyll-theme-chirpy/
├── _scripts
│ └── travis # CI stuff, remove it
├── .travis.yml # remove this, too
├── .github # remove
├── .github # remove it
├── assets
├── tabs
│   └── about.md # the ABOUT page
Expand All @@ -74,20 +79,34 @@ jekyll-theme-chirpy/
```


As mentioned above, some files or directories should be removed from your repo:

- .travis.yml
- .github
- _scripts/travis


### Configuration

Customize the variables in file `_config.yml` as needed.

* Avatar

The sample avatar is `/assets/img/sample/avatar.jpg`. It should be replaced by your own one. Notice that a huge image file will increase the load time of your site, so keep your avatar size as samll as possible(may be *<https://tinypng.com/>* will help).

### Atom Feed
* TimeZone

The Atom feed url of your site will be:
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).

```
<SITE_URL>/feed.xml
```
* 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`.
The `SITE_URL` was defined by variable `url` of `_config.yml`.
### Run Locally
Expand All @@ -104,53 +123,84 @@ Open a brower and visit <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.


### Deploying to GitHub Pages

Before the deployment begins, ensure the `url` in `_config.yml` has been set to `https://<username>.github.io`.
Before the deployment begins, ensure the `url` in file `_config.yml` has been set to `https://<username>.github.io`(or the custom domain, if you have. e.g. `https://yourdomain.com`).

#### Option 1: Built by GitHub Pages

By deploying your site in this way, you can push the source code to GitHub repository directly.
By deploying the site in this way, you're allowed to push the source code directly to the remote.

> **Note**: If you want to use any third-party Jekyll plugins that not in [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
> **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 the repository to:

**1**. Rename your repository as `<username>.github.io`.
|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| any one except `<username>.github.io`, let's say `project`|

**2**. Commit the changes of your repository, then run the initialization script:
**2**. Commit the changes of the repo first, then run the initialization script:

```console
$ bash tools/init.sh
```

It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
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`.
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repo.

**4**. Visit `https://<username>.github.io` and enjoy.
**4**. Check it out:

|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.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 will not work. If you want to use any another third-party Jekyll plugins, **your have to build locally rather than on GitHub Pages**.
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 another plugins that not in 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 | `<username>.github.io`|
|Project| any one except `<username>.github.io`, let's say `project`|

**1**. On GitHub website, create a brand new repository with name `<username>.github.io` and then clone it locally.
and clone it.

**2**. Build your site by:
**2**. In the root of the source project, build your site by:

```console
$ bash tools/build.sh -d /path/to/<username>.github.io/
$ bash tools/build.sh -d /path/to/local/project/
```

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.
If you prefer to the Project site, change `baseurl` of file `_config.yml` to your project name, starting with a slash. e.g. `/project`. Or, simply add argument `-b /project` behide the command above.

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.

**3**. Go to GitHub website and enable GitHub Pages service for the new repository `<username>.github.io`.
**4**. Visit at:

|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|

and enjoy!

**4**. Visit `https://<username>.github.io` and enjoy.

## Documentation

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).
For more information, please check out 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).

## Sponsor

Want to buy me a coffee? Click the button <kbd>❤️Sponsor</kbd> at the top of the [Home Page](https://github.com/cotes2020/jekyll-theme-chirpy) and choose a link that suits you to donate. I'd really appreciate it and take it as encouragement to work on better projects.



## License
Expand Down
Loading

0 comments on commit 8d30507

Please sign in to comment.