From daa2dd3d74ee46024e27a03573a2bc540d38cae3 Mon Sep 17 00:00:00 2001 From: Mimi <1119186082@qq.com> Date: Sun, 31 Mar 2024 02:10:38 +0800 Subject: [PATCH 1/5] docs: Custom Domain Issue with CNAME File --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index cb75ceb..cca2b20 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,22 @@ Additional guides: - Create a GitHub Personal Access Token. [[Link]](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) - Add authentication token to Travis CI. [[Link]](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings) +## Custom Domain Issue with CNAME File + +If you are using a custom domain with GitHub Pages, you might have encountered an issue where your custom domain configuration gets lost after deploying updates to your site. This problem occurs due to the deletion of the `CNAME` file in the root of the deployed directory during the git commit and push process performed by the `hexo-deployer-git` plugin. + +GitHub requires the `CNAME` file to be present in your repository to associate your custom domain with your GitHub Pages site. When this file is missing, GitHub resets the custom domain setting, leading to the site being accessible only through the default `github.io` domain. + +### Solution + +To ensure your custom domain remains active with each deployment, you need to include the `CNAME` file in your blog's source files. Here's how you can do it: + +1. **Create a `CNAME` File:** In the root of your blog's source directory, create a file named `CNAME`. Inside this file, enter your custom domain name. For example, if your custom domain is `example.com`, the content of the `CNAME` file should be: + ``` + example.com + ``` +2. **Deploy Your Site:** Use the `hexo-deployer-git` plugin to deploy your site as usual. Run `hexo g -d` command, the plugin will now include the `CNAME` file in the deployment, and your custom domain configuration will remain intact. + ## How it works `hexo-deployer-git` works by generating the site in `.deploy_git` and *force pushing* to the repo(es) in config. From fdef7f34e4b6f6eee35a35ac3801e70ddd2f27b9 Mon Sep 17 00:00:00 2001 From: Mimi <1119186082@qq.com> Date: Sun, 31 Mar 2024 13:53:35 +0800 Subject: [PATCH 2/5] Update README.md Co-authored-by: Uiolee <22849383+uiolee@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cca2b20..5f2354f 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ GitHub requires the `CNAME` file to be present in your repository to associate y ### Solution -To ensure your custom domain remains active with each deployment, you need to include the `CNAME` file in your blog's source files. Here's how you can do it: +To ensure your custom domain remains active with each deployment, you need to include the `CNAME` file in your blog's `source/` directory. Here's how you can do it: 1. **Create a `CNAME` File:** In the root of your blog's source directory, create a file named `CNAME`. Inside this file, enter your custom domain name. For example, if your custom domain is `example.com`, the content of the `CNAME` file should be: ``` From b70de659751d94c63d6a212a2eec5b4a745cc144 Mon Sep 17 00:00:00 2001 From: Mimi <1119186082@qq.com> Date: Sun, 31 Mar 2024 13:53:42 +0800 Subject: [PATCH 3/5] Update README.md Co-authored-by: Uiolee <22849383+uiolee@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f2354f..e4351ff 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ GitHub requires the `CNAME` file to be present in your repository to associate y To ensure your custom domain remains active with each deployment, you need to include the `CNAME` file in your blog's `source/` directory. Here's how you can do it: -1. **Create a `CNAME` File:** In the root of your blog's source directory, create a file named `CNAME`. Inside this file, enter your custom domain name. For example, if your custom domain is `example.com`, the content of the `CNAME` file should be: +1. **Create a `CNAME` File:** In the root of your blog's `source/` directory, create a file named `CNAME`. Inside this file, enter your custom domain name. For example, if your custom domain is `example.com`, the content of the `CNAME` file should be: ``` example.com ``` From 408d86646470a94ac4bf4f48ac95550a0fed92c9 Mon Sep 17 00:00:00 2001 From: Mimi <1119186082@qq.com> Date: Sun, 31 Mar 2024 14:04:27 +0800 Subject: [PATCH 4/5] Update README.md --- README.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e4351ff..0b215d5 100644 --- a/README.md +++ b/README.md @@ -113,9 +113,25 @@ Additional guides: - Create a GitHub Personal Access Token. [[Link]](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) - Add authentication token to Travis CI. [[Link]](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings) +## Important Notice: Force Push Behavior + +The `hexo-deployer-git` plugin employs a force push (`git push --force`) strategy when deploying updates to your site. This approach ensures that the remote repository aligns exactly with your local deployment, providing a clean, consistent state for each update. However, it comes with an important consideration regarding custom modifications. + +### Impact of Force Push + +Using force push means that any changes made directly in the remote repository (e.g., via GitHub's web interface or through a separate git workflow) will be **overwritten** when the next deployment occurs. This is because force push does not merge changes; it replaces the remote content with the local version entirely. + +### How to Safely Manage Your Site + +To prevent unintended loss of work, we strongly advise adhering to the following best practices: + +1. **Centralize Changes in Your Hexo Source:** Make all content and configuration changes within your local Hexo root directory. This ensures all modifications are included in the deployment process and preserved in your source control. + +2. **Avoid Direct Remote Modifications:** Refrain from directly editing files in the GitHub repository through the web interface or other git methods. Doing so could lead to these changes being lost on the next deployment. + ## Custom Domain Issue with CNAME File -If you are using a custom domain with GitHub Pages, you might have encountered an issue where your custom domain configuration gets lost after deploying updates to your site. This problem occurs due to the deletion of the `CNAME` file in the root of the deployed directory during the git commit and push process performed by the `hexo-deployer-git` plugin. +If you are using a custom domain with GitHub Pages, you might have encountered an issue where your custom domain configuration gets lost after deploying updates to your site. This problem occurs due to the overwritten / deletion of the `CNAME` file in the root of the deployed directory during the git commit and push process performed by the `hexo-deployer-git` plugin. GitHub requires the `CNAME` file to be present in your repository to associate your custom domain with your GitHub Pages site. When this file is missing, GitHub resets the custom domain setting, leading to the site being accessible only through the default `github.io` domain. From 56a141c06e5e1b7dd05f170ac84e1071397710fe Mon Sep 17 00:00:00 2001 From: Mimi <1119186082@qq.com> Date: Sun, 31 Mar 2024 14:10:56 +0800 Subject: [PATCH 5/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0b215d5..50b7cc6 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ deploy: ``` - **repo**: Repository settings, or plain url of your repo - - **url**: Url of your repositury to pull from and push to. + - **url**: Url of your repositury to pull from and push to. If you've configured SSH key authentication for git, ensure you use the SSH protocol format (for example, `git@github.com:`) for your repository URL to avoid password prompts or access denial due to security policies. - **branch**: Optional git branch to deploy the static site to. - Defaults to `gh-pages` on GitHub. - Defaults to `coding-pages` on Coding.net.