From 159d536003d3adadf359dafaea5da7d2653fdde2 Mon Sep 17 00:00:00 2001 From: geekifan Date: Wed, 7 May 2025 12:19:44 +0800 Subject: [PATCH] docs: update demo posts --- .../2019-08-08-write-a-new-post/index.en.md | 51 ++++++------------- .../index.zh-CN.md | 2 + .../2019-08-09-getting-started/index.en.md | 31 +++++------ .../2019-08-09-getting-started/index.zh-CN.md | 3 ++ .../index.en.md | 2 +- .../index.zh-CN.md | 2 +- 6 files changed, 37 insertions(+), 54 deletions(-) diff --git a/content/post/2019-08-08-write-a-new-post/index.en.md b/content/post/2019-08-08-write-a-new-post/index.en.md index 2f694ac..8f792bb 100644 --- a/content/post/2019-08-08-write-a-new-post/index.en.md +++ b/content/post/2019-08-08-write-a-new-post/index.en.md @@ -11,31 +11,37 @@ tags: pin: True --- +> **NOTE:** This tutorial is not fully migrated from the Jekyll version -- please reference with caution. +{ .prompt-warning } + This tutorial will guide you how to write a post in the _Chirpy_ template, and it's worth reading even if you've used Jekyll before, as many features require specific variables to be set. ## Naming and Path -Create a new file named `YYYY-MM-DD-TITLE.EXTENSION`{: .filepath} and put it in the `_posts`{: .filepath} of the root directory. Please note that the `EXTENSION`{: .filepath} must be one of `md`{: .filepath} and `markdown`{: .filepath}. If you want to save time of creating files, please consider using the plugin [`Jekyll-Compose`](https://github.com/jekyll/jekyll-compose) to accomplish this. +Create a new file using `hugo new content/post/YYYY-MM-DD-TITLE.md`. You can change the path as you like, but note that all the posts should be placed in {{< markdown/filepath src="content/post" >}} of the root directory. ## Front Matter -Basically, you need to fill the [Front Matter](https://jekyllrb.com/docs/front-matter/) as below at the top of the post: +Basically, the [Front Matter](https://jekyllrb.com/docs/front-matter/) is initialized by hugo as below at the top of the post: ```yaml --- title: TITLE date: YYYY-MM-DD HH:MM:SS +/-TTTT -categories: [TOP_CATEGORY, SUB_CATEGORY] -tags: [TAG] # TAG names should always be lowercase +draft: true --- ``` +You can add the following fields as needed: +```yaml +categories: [TOP_CATEGORY, SUB_CATEGORY] # only two categories are supported +tags: [TAG] # TAG names should always be lowercase +pin: true # it means this post will show at the top of the home page. +description: Hello, World! # description of this post +``` + > The posts' _layout_ has been set to `post` by default, so there is no need to add the variable _layout_ in the Front Matter block. -{: .prompt-tip } - -### Timezone of Date - -To accurately record the release date of a post, you should not only set up the `timezone` of `_config.yml`{: .filepath} but also provide the post's timezone in variable `date` of its Front Matter block. Format: `+/-TTTT`, e.g. `+0800`. +{ .prompt-tip } ### Categories and Tags @@ -50,32 +56,7 @@ tags: [bee] ### Author Information -The author information of the post usually does not need to be filled in the _Front Matter_ , they will be obtained from variables `social.name` and the first entry of `social.links` of the configuration file by default. But you can also override it as follows: - -Adding author information in `_data/authors.yml` (If your website doesn't have this file, don't hesitate to create one). - -```yaml -: - name: - twitter: - url: -``` -{: file="_data/authors.yml" } - -And then use `author` to specify a single entry or `authors` to specify multiple entries: - -```yaml ---- -author: # for single entry -# or -authors: [, ] # for multiple entries ---- -``` - -Having said that, the key `author` can also identify multiple entries. - -> The benefit of reading the author information from the file `_data/authors.yml`{: .filepath } is that the page will have the meta tag `twitter:creator`, which enriches the [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/guides/getting-started#card-and-content-attribution) and is good for SEO. -{: .prompt-info } +The author information of the post usually does not need to be filled in the _Front Matter_ , they will be obtained from variables `social.name` and the first entry of `social.links` of the configuration file by default. But you can also override it in the configuration. ### Post Description diff --git a/content/post/2019-08-08-write-a-new-post/index.zh-CN.md b/content/post/2019-08-08-write-a-new-post/index.zh-CN.md index 6e745a8..785175f 100644 --- a/content/post/2019-08-08-write-a-new-post/index.zh-CN.md +++ b/content/post/2019-08-08-write-a-new-post/index.zh-CN.md @@ -10,6 +10,8 @@ tags: - 写作 pin: True --- +> **NOTE:** 该教程还没有完成从 Jekyll 版本的迁移，请谨慎参考。 +{ .prompt-warning } 本教程将指导您如何在 _Chirpy_ 模板中撰写文章，即使您以前使用过Jekyll，也值得阅读，因为许多功能需要设置特定变量。 diff --git a/content/post/2019-08-09-getting-started/index.en.md b/content/post/2019-08-09-getting-started/index.en.md index 0f53a4d..fe71807 100644 --- a/content/post/2019-08-09-getting-started/index.en.md +++ b/content/post/2019-08-09-getting-started/index.en.md @@ -13,6 +13,9 @@ tags: pin: true --- +> **NOTE:** This tutorial is not fully migrated from the Jekyll version -- please reference with caution. +{ .prompt-warning } + ## Creating a Site Repository When creating your site repository, you have two options depending on your needs: @@ -30,7 +33,7 @@ This approach simplifies upgrades, isolates unnecessary files, and is perfect fo This approach is convenient for modifying features or UI design, but presents challenges during upgrades. So don't try this unless you are familiar with Jekyll and plan to heavily modify this theme. 1. Sign in to GitHub. -2. [Fork the theme repository](https://github.com/cotes2020/jekyll-theme-chirpy/fork). +2. [Fork the theme repository](https://github.com/geekifan/jekyll-theme-chirpy/fork). 3. Name the new repository `.github.io`, replacing `username` with your lowercase GitHub username. ## Setting up the Environment @@ -58,10 +61,9 @@ For Unix-like systems, you can set up the environment natively for optimal perfo **Steps**: -1. Follow the [Jekyll installation guide](https://jekyllrb.com/docs/installation/) to install Jekyll and ensure [Git](https://git-scm.com/) is installed. +1. Follow the [Hugo installation guide](https://gohugo.io/installation/) to install Hugo and ensure [Git](https://git-scm.com/) is installed. 2. Clone your repository to your local machine. -3. If you forked the theme, install [Node.js][nodejs] and run `bash tools/init.sh` in the root directory to initialize the repository. -4. Run command `bundle` in the root of your repository to install the dependencies. +3. Run command `hugo mod get` to install the dependencies. ## Usage @@ -70,26 +72,21 @@ For Unix-like systems, you can set up the environment natively for optimal perfo To run the site locally, use the following command: ```terminal -$ bundle exec jekyll serve +hugo serve ``` > If you are using Dev Containers, you must run that command in the **VS Code** Terminal. -{: .prompt-info } +{ .prompt-info } -After a few seconds, the local server will be available at . +After a few seconds, the local server will be available at . ### Configuration -Update the variables in {{< markdown/filepath src="_config.yml">}} as needed. Some typical options include: - -- `url` -- `avatar` -- `timezone` -- `lang` +Update the variables in {{< markdown/filepath src="hugo.html">}} as needed. Some typical options include: ### Social Contact Options -Social contact options are displayed at the bottom of the sidebar. You can enable or disable specific contacts in the {{< markdown/filepath src="_data/contact.yml">}} file. +Social contact options are displayed at the bottom of the sidebar. You can enable or disable specific contacts in the {{< markdown/filepath src="config/_default/params.toml">}} file. ### Customizing the Stylesheet @@ -97,9 +94,9 @@ To customize the stylesheet, copy the theme's {{< markdown/filepath src="assets/ ### Customizing Static Assets -Static assets configuration was introduced in version `5.1.0`. The CDN of the static assets is defined in {{< markdown/filepath src="_data/origin/cors.ymll">}}. You can replace some of them based on the network conditions in the region where your website is published. +The CDN of the static assets is defined in {{< markdown/filepath src="data/origin/cors.yaml">}}. You can replace some of them based on the network conditions in the region where your website is published. -If you prefer to self-host the static assets, refer to the [_chirpy-static-assets_](https://github.com/cotes2020/chirpy-static-assets#readme) repository. +If you prefer to self-host the static assets, modify {{< markdown/filepath src="config/_default/params.toml">}} and turn `self_host` on. The static files are from [geekifan/chirpy-static-assets](https://github.com/geekifan/chirpy-static-assets#readme) which is a fork of [cotes2020/chirpy-static-assets](https://github.com/cotes2020/chirpy-static-assets#readme) with minimal changes to make it work with hugo. ## Deployment @@ -145,7 +142,7 @@ $ JEKYLL_ENV=production bundle exec jekyll b Unless you specified the output path, the generated site files will be placed in the {{< markdown/filepath src="_site" >}}folder of the project's root directory. Upload these files to your target server. [nodejs]: https://nodejs.org/ -[starter]: https://github.com/cotes2020/chirpy-starter +[starter]: https://github.com/geekifan/chirpy-starter [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 [docker-desktop]: https://www.docker.com/products/docker-desktop/ [docker-engine]: https://docs.docker.com/engine/install/ diff --git a/content/post/2019-08-09-getting-started/index.zh-CN.md b/content/post/2019-08-09-getting-started/index.zh-CN.md index a48ca10..7ae774c 100644 --- a/content/post/2019-08-09-getting-started/index.zh-CN.md +++ b/content/post/2019-08-09-getting-started/index.zh-CN.md @@ -13,6 +13,9 @@ tags: pin: true --- +> **NOTE:** 该教程还没有完成从 Jekyll 版本的迁移，请谨慎参考。 +{ .prompt-warning } + ## 创建站点仓库 创建站点仓库时，根据您的需求有两种选择： diff --git a/content/post/2019-08-11-customize-the-favicon/index.en.md b/content/post/2019-08-11-customize-the-favicon/index.en.md index a999152..04f8c2f 100644 --- a/content/post/2019-08-11-customize-the-favicon/index.en.md +++ b/content/post/2019-08-11-customize-the-favicon/index.en.md @@ -27,7 +27,7 @@ Download the generated package, unzip and delete the following two from the extr - {{< markdown/filepath src="browserconfig.xml" >}} - {{< markdown/filepath src="site.webmanifest" >}} -And then copy the remaining image files ({{< markdown/filepath src=".PNG" >}} and {{< markdown/filepath src=".ICO" >}}) to cover the original files in the directory {{< markdown/filepath src="assets/img/favicons/" >}} of your Jekyll site. If your Jekyll site doesn't have this directory yet, just create one. +And then copy the remaining image files ({{< markdown/filepath src=".PNG" >}} and {{< markdown/filepath src=".ICO" >}}) to cover the original files in the directory {{< markdown/filepath src="assets/img/favicons/" >}} of your Hugo site. If your Hugo site doesn't have this directory yet, just create one. The following table will help you understand the changes to the favicon files: diff --git a/content/post/2019-08-11-customize-the-favicon/index.zh-CN.md b/content/post/2019-08-11-customize-the-favicon/index.zh-CN.md index 3fde058..794c860 100644 --- a/content/post/2019-08-11-customize-the-favicon/index.zh-CN.md +++ b/content/post/2019-08-11-customize-the-favicon/index.zh-CN.md @@ -27,7 +27,7 @@ pin: true - {{< markdown/filepath src="browserconfig.xml" >}} - {{< markdown/filepath src="site.webmanifest" >}} -然后将剩余的图像文件（{{< markdown/filepath src=".PNG" >}}和{{< markdown/filepath src=".ICO" >}}）复制到您的Jekyll站点的{{< markdown/filepath src="assets/img/favicons/" >}}目录中，覆盖原始文件。如果您的Jekyll站点还没有这个目录，只需创建一个。 +然后将剩余的图像文件（{{< markdown/filepath src=".PNG" >}}和{{< markdown/filepath src=".ICO" >}}）复制到您的Hugo站点的{{< markdown/filepath src="assets/img/favicons/" >}}目录中，覆盖原始文件。如果您的Hugo站点还没有这个目录，只需创建一个。 下表将帮助您理解网站图标文件的变化：