chirpy.wiki

.gitignore

@@ -0,0 +1 @@
+.idea

Development-&-Test-Environments.md

@@ -0,0 +1,80 @@
+**Table of Contents**
+
+- [Startup](#startup)
+- [Modifying JavaScript](#modifying-javascript)
+  - [Inline JavaScript/JSON comments](#inline-javascriptjson-comments)
+  - [External JavaScript](#external-javascript)
+- [How to pass the CI tests](#how-to-pass-the-ci-tests)
+  - [Check commit messages](#check-commit-messages)
+  - [Check the core functionality](#check-the-core-functionality)
+  - [Check the SASS code style](#check-the-sass-code-style)
+
+---
+
+## Startup
+
+Install [VS Code][vscode], [Dev Containers][extension], and [Docker][docker].
+
+Next, fork this repository and then open VS Code to [clone your repo in container volume][clone-in-vol]. Wait a few minutes for Docker to create the container, and once everything is ready, you can start the Jekyll server in the VS Code terminal:
+
+```console
+./tools/run.sh
+```
+
+[vscode]: https://code.visualstudio.com/
+[extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
+[docker]: https://docs.docker.com/get-docker/
+[clone-in-vol]: https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume
+
+## Modifying JavaScript
+
+If your changes involve JavaScript, please read the following sections.
+
+### Inline JavaScript/JSON comments
+
+For inline JS (code between `<script>` and `</script>`) or JS / JSON file containing [Front Matter][front-matter], use `{%- comment -%}` and `{%- endcomment -%}` for comments instead of two slashes `//`. For example: `{%- comment -%} code comment message {%- endcomment -%}`. This is because in a _production_ environment, [jekyll-compress-html][html-compressor] compresses HTML files but does not recognize `//` correctly, which can break the HTML structure.
+
+### External JavaScript
+
+If you changed the files in the `_javascript/` directory, you need to rebuild the JS.  During development, real-time debugging can be performed with the following commands:
+
+Firstly, start a Jekyll server:
+
+```console
+./tools/run.sh
+```
+
+And then open a new terminal session and run:
+
+```console
+npm run watch:js
+```
+
+When you are finished developing, press <kbd>ctrl</kbd> + <kbd>C</kbd> to end the `npm` process above, and then run the
+`npm run build:js` command. The new compressed JS files will be exported to `assets/js/dist/`.
+
+## How to pass the CI tests
+
+This project has [CI][ci] enabled. To ensure your Pull Request passes the tests, please follow these guidelines.
+
+### Check commit messages
+
+Once you've run `npm install` in the root directory of the repository, [`commit-lint`][commitlint] is activated. Every commit you create will be checked to ensure it meets the requirements of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+> [!IMPORTANT]
+> If you use a Node version manager and want to use Git hooks through Git GUIs, you might encounter a "command not found" error when committing your changes.
+>
+> For more information on the cause and solution, refer to the Husky docs: "[Node Version Managers and GUIs](https://typicode.github.io/husky/how-to.html#node-version-managers-and-guis)".
+
+### Check the core functionality
+
+```console
+bash ./tools/test.sh
+```
+
+### Check the SASS code style
+
+```console
+npm test
+```
+

FAQ.md

@@ -0,0 +1,14 @@
+**Table of Contents**
+
+- [Why is there a blank page after the website is deployed to GitHub Pages?](#why-is-there-a-blank-page-after-the-website-is-deployed-to-github-pages)
+- [Why isn't the website content updated immediately?](#why-isnt-the-website-content-updated-immediately)
+
+---
+
+## Why is there a blank page after the website is deployed to GitHub Pages?
+  
+Please take the time to read the [tutorial on deployment](https://chirpy.cotes.page/posts/getting-started/#deployment).
+
+## Why isn't the website content updated immediately?
+
+To load web pages offline, we used [PWA](https://web.dev/progressive-web-apps/) in this project. Every time you use a browser to visit your website, the local cache will be displayed to you first. At the same time, a background process will check for website updates and refresh the local cache. After that, you will be able to see the latest website contents; usually, this process takes tens of seconds to several minutes. If you want to see the latest content right away, please use the incognito mode of your browser.

Home.md

@@ -0,0 +1,16 @@
+## Tutorial
+
+- [Getting Started](https://chirpy.cotes.page/posts/getting-started/)
+- [Customize the Favicon](https://chirpy.cotes.page/posts/customize-the-favicon/)
+- [Writing a New Post](https://chirpy.cotes.page/posts/write-a-new-post/)
+
+## Showcase
+
+- [Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/)
+
+## Misc
+
+- [FAQ](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/FAQ)
+- [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide)
+- [Development](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments)
+- [Maintenance](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Maintenance)

Maintenance.md

@@ -0,0 +1,36 @@
+**Table of Contents**
+
+- [Releasing a New Version](#releasing-a-new-version)
+- [Managing the Hotfix Branches](#managing-the-hotfix-branches)
+
+---
+
+## Releasing a New Version
+
+To release a new **Major** or **Minor** version, perform a *no fast-forward* merge from the `master` branch into the `production` branch.
+
+To release a new **Patch** version, perform a *no fast-forward* merge from the `hotfix` branch into the `production` branch.
+
+When GitHub Actions detects updates to the `production` branch, it will automatically trigger the release process.
+
+> [!IMPORTANT]
+> Please **do not enable** any check tools such as `Codacy Static Code Analysis` or `commitlint` under the repository’s branch protection rule *Require status checks to pass before merging*. Doing so will prevent GitHub Actions from pushing commits to the `master` branch, which will cause the automated release process to fail.
+
+## Managing the Hotfix Branches
+
+The `hotfix` branch naming format is `hotfix/<MAJOR>.<MINOR>.<PATCH>`, e.g. `hotfix/3.2.1`. It is a temporary branch with a life cycle:
+
+1. Create a new `hotfix` branch from the `production` branch (on GitHub).
+2. Commit the patch to the `hotfix` branch by:
+
+   1. Branching from `hotfix` and then committing patches to the new `patch` branch.
+   2. Creating a PR for the `patch` branch on GitHub, then squash merge it into the `hotfix` branch.
+
+3. When hotfixes are done, create a PR for the `hotfix` branch and merge it into the `production` branch using the `--no-ff` option.
+4. Delete this branch.
+
+[front-matter]: https://jekyllrb.com/docs/front-matter/
+[html-compressor]: https://github.com/penibelst/jekyll-compress-html
+[ci]: https://en.wikipedia.org/wiki/Continuous_integration
+[commitlint]: https://commitlint.js.org/
+

Upgrade-Guide.md

@@ -0,0 +1,122 @@
+**Table of Contents**
+
+- [Upgrading from Starter](#upgrading-from-starter)
+  - [Preparation](#preparation)
+    - [Adding Upstream](#adding-upstream)
+    - [Handling Submodule](#handling-submodule)
+  - [Fetch Updates](#fetch-updates)
+- [Upgrade the Fork](#upgrade-the-fork)
+- [Major Version Upgrades](#major-version-upgrades)
+
+## Upgrading from Starter
+
+If your website was created using [`chirpy-starter`][starter], follow these steps to update your repository.
+
+### Preparation
+
+The operations mentioned in this section only need to be performed once after cloning your repository locally.
+
+#### Adding Upstream
+
+```console
+git remote add chirpy https://github.com/cotes2020/chirpy-starter.git
+```
+
+Verify the remote was added successfully:
+
+```console
+git remote -v
+```
+
+The output should include:
+
+```log
+chirpy  https://github.com/cotes2020/chirpy-starter.git (fetch)
+chirpy  https://github.com/cotes2020/chirpy-starter.git (push)
+```
+
+#### Handling Submodule
+
+If your workflow does not require the submodule `assets/lib`, run command:
+
+```console
+git config submodule.assets/lib.ignore all
+```
+
+This prevents the submodule from pulling files and taking up local disk space.
+
+### Fetch Updates
+
+The following steps need to be performed for each update.
+
+1. Fetch all tags from upstream:
+
+   ```console
+   git fetch chirpy --tags
+   ```
+
+2. Merge the latest tag from upstream into your local branch. For example, to merge tag `vX.Y.Z`, run:
+
+   ```console
+   git merge vX.Y.Z --squash --allow-unrelated-histories
+   ```
+
+3. If the list of conflicting files includes the submodule `assets/lib`:
+   - If you do not want to use the submodule, execute:
+
+     ```console
+     git restore --staged assets/lib
+     ```
+
+   - If you have already initialized and enabled the submodule, follow the output hint:
+
+     ```
+     hint:  - go to submodule (assets/lib), and either merge commit <submodule_commit_hash>
+     ```
+
+     Record the `submodule_commit_hash` and update the local submodule:
+
+     ```console
+     git -C assets/lib merge <submodule_commit_hash>
+     ```
+
+4. Resolve any remaining file conflicts manually. Keep any custom modifications if needed.
+
+5. Once conflicts are resolved, create a new commit to save the upgrade:
+
+   ```console
+   git add . && git commit -m "chore: upgrade to X.Y.Z"
+   ```
+
+6. Update the local theme gems:
+
+   ```console
+   bundle update
+   ```
+
+## Upgrade the Fork
+
+If you forked from the source project (there will be `gemspec` in the `Gemfile` of your site), merge the [latest upstream tags][latest-tag] into your Jekyll site to complete the upgrade.
+The merge may conflict with your local modifications. Be patient and careful when resolving these conflicts.
+
+JS distribution files have been removed since [`v5.6.0`][v5.6.0], and Bootstrap CSS has been lean since [`v7.0.0`][v7.0.0]. For future upgrades, compile the CSS/JS files yourself:
+
+```console
+npm run build
+```
+
+Then add them to your repository files:
+
+```console
+git add assets/js/dist _sass/vendors -f
+```
+
+## Major Version Upgrades
+
+When upgrading to a **Major** version, read the [release notes][release-notes] for that version to understand any changes in project configuration.
+
+[starter]: https://github.com/cotes2020/chirpy-starter
+[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags
+[v7.0.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v7.0.0
+[v5.6.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v5.6.0
+[release-notes]: https://github.com/cotes2020/jekyll-theme-chirpy/releases

_Footer.md

@@ -0,0 +1 @@
+[:pencil: Helps improve this page](https://github.com/cotes2020/jekyll-theme-chirpy/discussions/new?category=general)

_Sidebar.md

@@ -0,0 +1,12 @@
+- [**Back to Home**](https://github.com/cotes2020/jekyll-theme-chirpy/wiki)
+- **Tutorial**
+  - [Getting Started](https://chirpy.cotes.page/posts/getting-started/)
+  - [Customize the Favicon](https://chirpy.cotes.page/posts/customize-the-favicon/)
+  - [Writing a New Post](https://chirpy.cotes.page/posts/write-a-new-post/)
+- **Showcase**
+  - [Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/)
+- **Misc**
+  - [FAQ](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/FAQ)
+  - [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide)
+  - [Development](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments)
+  - [Maintenance](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Maintenance)