docs: update tutorial
docs: update tutorial
This commit is contained in:
Cotes Chung
parent
b1453ccb0c
commit
d921b981f7
3 changed files with 26 additions and 23 deletions
14
README.md
14
README.md
|
|
@ -39,15 +39,15 @@
|
|||
|
||||
## Quick Start
|
||||
|
||||
Before starting, please follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll`, and `Bundler`. In addition, [Git](https://git-scm.com/) is also required to be installed.
|
||||
Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of the basic environment. [Git](https://git-scm.com/) also needs to be installed.
|
||||
|
||||
### Step 1. Creating a New Site
|
||||
|
||||
Create a new repository from the [**Chirpy Starter**](https://github.com/cotes2020/chirpy-starter/generate) and name it `<GH_USERNAME>.github.io`, where `GH_USERNAME` represents your GitHub username.
|
||||
Sign in to GitHub and browse to [**Chirpy Starter**](https://github.com/cotes2020/chirpy-starter/), click the button <kbd>Use this template</kbd> > <kbd>Create a new repository</kbd>, and name the new repository `USERNAME.github.io`, where `USERNAME` represents your GitHub username.
|
||||
|
||||
### Step 2. Installing Dependencies
|
||||
|
||||
Before running for the first time, go to the root directory of your site, and install dependencies as follows:
|
||||
Clone it to your local machine, go to its root directory, and run the following command to install the dependencies.
|
||||
|
||||
```console
|
||||
$ bundle
|
||||
|
|
@ -55,7 +55,7 @@ $ bundle
|
|||
|
||||
### Step 3. Running Local Server
|
||||
|
||||
Run the following command in the root directory of the site:
|
||||
Run the following command in the root directory of your site:
|
||||
|
||||
```console
|
||||
$ bundle exec jekyll s
|
||||
|
|
@ -70,11 +70,11 @@ $ docker run -it --rm \
|
|||
jekyll serve
|
||||
```
|
||||
|
||||
After a while, navigate to the site at <http://localhost:4000>.
|
||||
After a few seconds, the local service will be published at _<http://127.0.0.1:4000>_.
|
||||
|
||||
## Documentation
|
||||
|
||||
For more details on usage, please refer to the tutorial on the [demo website](https://cotes2020.github.io/chirpy-demo/) / [wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki). Note that the tutorial is based on the [latest release](https://github.com/cotes2020/jekyll-theme-chirpy/releases/latest), and the features of the default branch are usually ahead of the documentation.
|
||||
For more details on usage, please refer to the tutorial on the [demo website](https://cotes2020.github.io/chirpy-demo/) or [wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki). Note that the tutorial is based on the [latest release](https://github.com/cotes2020/jekyll-theme-chirpy/releases/latest), and the features of the default branch are usually ahead of the documentation.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ Last but not least, thank [JetBrains][jb] for providing the OSS development lice
|
|||
|
||||
## 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!
|
||||
If you like it, please consider sponsoring me. It will help me to maintain this project better and I would be very grateful!
|
||||
|
||||
[](https://ko-fi.com/coteschung)
|
||||
[][cn-donation]
|
||||
|
|
|
|||
|
|
@ -133,13 +133,16 @@ _Image Caption_
|
|||
|
||||
### Size
|
||||
|
||||
In order to prevent the page content layout from shifting when the image is loaded, we should set the width and height for each image:
|
||||
In order to prevent the page content layout from shifting when the image is loaded, we should set the width and height for each image.
|
||||
|
||||
```markdown
|
||||
{: width="700" height="400" }
|
||||
```
|
||||
{: .nolineno}
|
||||
|
||||
> For an SVG, you have to at least specify its _width_, otherwise it won't be rendered.
|
||||
{: .prompt-info }
|
||||
|
||||
Starting from _Chirpy v5.0.0_, `height` and `width` support abbreviations (`height` → `h`, `width` → `w`). The following example has the same effect as the above:
|
||||
|
||||
```markdown
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ pin: true
|
|||
|
||||
## Prerequisites
|
||||
|
||||
Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll`, and `Bundler`. In addition, [Git](https://git-scm.com/) is also required to be installed.
|
||||
Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of the basic environment. [Git](https://git-scm.com/) also needs to be installed.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -22,11 +22,11 @@ There are two ways to create a new repository for this theme:
|
|||
|
||||
#### Option 1. Using the Chirpy Starter
|
||||
|
||||
Create a new repository from the [**Chirpy Starter**][use-starter] and name it `<GH_USERNAME>.github.io`, where `GH_USERNAME` represents your GitHub username.
|
||||
Sign in to GitHub and browse to [**Chirpy Starter**](https://github.com/cotes2020/chirpy-starter/), click the button <kbd>Use this template</kbd> > <kbd>Create a new repository</kbd>, and name the new repository `USERNAME.github.io`, where `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 `<GH_USERNAME>.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.
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub and rename it to `USERNAME.github.io`. Note that the default branch code is under development. To ensure the stability of your site, please switch to the [latest tag][latest-tag] and start writing.
|
||||
|
||||
And then execute:
|
||||
|
||||
|
|
@ -93,31 +93,32 @@ $ docker run -it --rm \
|
|||
jekyll serve
|
||||
```
|
||||
|
||||
After a while, the local service will be published at _<http://127.0.0.1:4000>_.
|
||||
After a few seconds, the local service will be published at _<http://127.0.0.1:4000>_.
|
||||
|
||||
## Deployment
|
||||
|
||||
Before the deployment begins, check out the file `_config.yml`{: .filepath} 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.
|
||||
Now you can choose _ONE_ of the following methods to deploy your Jekyll site.
|
||||
|
||||
### Deploy by Using GitHub Actions
|
||||
|
||||
Ensure your Jekyll site has the file `.github/workflows/pages-deploy.yml`{: .filepath}. 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. And then rename your repository to `<GH_USERNAME>.github.io` on GitHub.
|
||||
There are a few things to get ready for.
|
||||
|
||||
Furthermore, if you have committed `Gemfile.lock`{: .filepath} to the repository and your local machine is not Linux, go the the root directory of your site and update the platform list:
|
||||
- If you're on the GitHub Free plan, keep your site repository public.
|
||||
- If you have committed `Gemfile.lock`{: .filepath} to the repository, and your local machine is not running Linux, go the the root of your site and update the platform list of the lock-file:
|
||||
|
||||
```console
|
||||
$ bundle lock --add-platform x86_64-linux
|
||||
```
|
||||
```console
|
||||
$ bundle lock --add-platform x86_64-linux
|
||||
```
|
||||
|
||||
Now publish your Jekyll site:
|
||||
Next, configure the _Pages_ service.
|
||||
|
||||
1. Browse to your repository on GitHub. Select the tab _Settings_, then click _Pages_ in the left navigation bar. Then, in the **Source** section (under _Build and deployment_), select [**GitHub Actions**][pages-workflow-src] from the dropdown menu.
|
||||
|
||||
2. Push any commit to remote to trigger the GitHub Actions workflow. In the _Actions_ tab of your repository, you should see the workflow _Build and Deploy_ running. Once the build is complete and successful, the site should be deployed automatically.
|
||||
2. Push any commits to GitHub to trigger the _Actions_ workflow. In the _Actions_ tab of your repository, you should see the workflow _Build and Deploy_ running. Once the build is complete and successful, the site will be deployed automatically.
|
||||
|
||||
3. Visit your website at the address indicated by GitHub.
|
||||
At this point, you can go to the URL indicated by GitHub to access your site.
|
||||
|
||||
### Manually Build and Deploy
|
||||
|
||||
|
|
@ -149,7 +150,7 @@ It depends on how you use the theme:
|
|||
|
||||
```diff
|
||||
- gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
|
||||
+ gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"
|
||||
+ gem "jekyll-theme-chirpy", "~> 4.3", ">= 4.3.2"
|
||||
```
|
||||
{: .nolineno file="Gemfile" }
|
||||
|
||||
|
|
@ -165,7 +166,6 @@ It depends on how you use the theme:
|
|||
The merge is likely to conflict with your local modifications. Please be patient and careful to resolve these conflicts.
|
||||
|
||||
[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
|
||||
[pages-workflow-src]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow
|
||||
[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags
|
||||
|
|
|
|||
Loading…
Reference in a new issue