From d921b981f7856182d82c95334ec129c9cea8eb7a Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Mon, 20 Feb 2023 05:46:33 +0800 Subject: [PATCH] docs: update tutorial docs: update tutorial --- README.md | 14 ++++++------- _posts/2019-08-08-write-a-new-post.md | 5 ++++- _posts/2019-08-09-getting-started.md | 30 +++++++++++++-------------- 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 11774ad..427eccc 100644 --- a/README.md +++ b/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 `.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 Use this template > Create a new repository, 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 . +After a few seconds, the local service will be published at __. ## 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! [![Ko-fi](https://img.shields.io/badge/-Buy%20Me%20a%20Coffee-ff5f5f?logo=ko-fi&logoColor=white)](https://ko-fi.com/coteschung) [![Wechat Pay](https://img.shields.io/badge/-Tip%20Me%20on%20WeChat-brightgreen?logo=wechat&logoColor=white)][cn-donation] diff --git a/_posts/2019-08-08-write-a-new-post.md b/_posts/2019-08-08-write-a-new-post.md index 2254d1a..4812cee 100644 --- a/_posts/2019-08-08-write-a-new-post.md +++ b/_posts/2019-08-08-write-a-new-post.md @@ -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 ![Desktop View](/assets/img/sample/mockup.png){: 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 diff --git a/_posts/2019-08-09-getting-started.md b/_posts/2019-08-09-getting-started.md index 0677cfe..ffc8682 100644 --- a/_posts/2019-08-09-getting-started.md +++ b/_posts/2019-08-09-getting-started.md @@ -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 `.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 Use this template > Create a new repository, 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 `.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 __. +After a few seconds, the local service will be published at __. ## 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 `.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