web/_posts/2019-08-09-getting-started.md

131 lines
4.1 KiB
Markdown
Raw Normal View History

2019-09-30 15:38:58 +03:00
---
2019-11-18 17:36:22 +03:00
title: Getting Started
2019-09-30 15:38:58 +03:00
date: 2019-08-09 20:55:00 +0800
categories: [Blogging, Tutorial]
2019-11-05 17:14:02 +03:00
tags: [getting started]
2019-09-30 15:38:58 +03:00
---
2019-11-05 17:14:02 +03:00
## Preparation
2019-09-30 15:38:58 +03:00
2019-11-18 17:36:22 +03:00
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/).
2019-09-30 15:38:58 +03:00
2019-11-18 17:36:22 +03:00
Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your replicated repository locally.
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
2019-11-18 17:36:22 +03:00
## Install Jekyll Plugins
2019-10-11 19:46:12 +03:00
2019-11-05 17:14:02 +03:00
Go to root directory of the repository and run the following:
2019-10-11 19:46:12 +03:00
```terminal
$ bundle install
```
`bundle` will install all the dependent Jekyll Plugins listed in file `Gemfile` automatically.
2019-09-30 15:38:58 +03:00
2019-11-18 17:36:22 +03:00
## File Structure
2019-11-05 17:14:02 +03:00
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
```
2019-09-30 15:38:58 +03:00
## Configuration
Customize the variables in file `_config.yml` as needed.
2019-10-11 19:46:12 +03:00
2019-09-30 15:38:58 +03:00
## Atom Feed
The Atom feed url of your site will be:
```
2019-11-05 17:14:02 +03:00
<SITE_URL>/feed.xml
2019-09-30 15:38:58 +03:00
```
2019-11-05 17:14:02 +03:00
The `SITE_URL` was defined by variable `url` in file `_config.yml`.
2019-09-30 15:38:58 +03:00
2019-11-18 17:36:22 +03:00
## Run Locally
2019-09-30 15:38:58 +03:00
2019-11-05 17:14:02 +03:00
You may want to preview the site before publishing, so just run the script tool:
2019-09-30 15:38:58 +03:00
```terminal
$ bash run.sh
```
2019-11-18 17:36:22 +03:00
>**Note**: 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.
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.
2019-09-30 15:38:58 +03:00
## Deploying to GitHub Pages
2019-11-16 18:12:26 +03:00
Before the deployment begins, ensure the `url` in `_config.yml` has been set to `https://<username>.github.io`.
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
### Option 1: Built by GitHub Pages
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
By deploying your site in this way, you can push the source code to GitHub repository directly.
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
> **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:
2019-09-30 15:38:58 +03:00
```console
2019-10-11 19:46:12 +03:00
$ bash init.sh
2019-09-30 15:38:58 +03:00
```
2019-10-11 19:46:12 +03:00
It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repository `<username>.github.io`.
2019-09-30 15:38:58 +03:00
**4**. Visit `https://<username>.github.io` and enjoy.
2019-11-18 17:36:22 +03:00
### Option 2: Build Locally
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
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**.
2019-09-30 15:38:58 +03:00
2019-11-16 18:12:26 +03:00
**1**. On GitHub website, create a brand new repository with name `<username>.github.io` and then clone it locally.
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
**2**. Build your site by:
2019-09-30 15:38:58 +03:00
```console
2019-10-11 19:46:12 +03:00
$ bash build.sh -d /path/to/<username>.github.io/
2019-09-30 15:38:58 +03:00
```
2019-10-11 19:46:12 +03:00
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.
2019-09-30 15:38:58 +03:00
2019-10-11 19:46:12 +03:00
**3**. Go to GitHub website and enable GitHub Pages service for the new repository `<username>.github.io`.
2019-09-30 15:38:58 +03:00
**4**. Visit `https://<username>.github.io` and enjoy.