Update deploying-your-docs.md re: GitHub Pages #3692
Conversation
re: GitHub Pages - GitHub changed the default branch for new repositories to "main" instead of "master" - Reworded some rections to clarify the intent and/or process - Changed a note into a NOTE: section - Unified word usage between the Project and User/Organisation sections. This also changes/fixes the title for Organisations/Users, as the order of these to words was reversed from the text below.
Replace more references to the `master` branch with references to the `main` branch, as per recent and new standard for new repositories by GitHub.
Organisation changed to Organization, in accordance with other spellings of the word.
| with the [remote_branch] configuration setting, but if you forget to change | ||
| directories before running the deploy script, it will commit to the `master` | ||
| branch of your project, which you probably don't want. | ||
| Please note that you need to explicitly point to the `mkdocs.yml` configuration |
There was a problem hiding this comment.
Is "Please" really necessary here?
There was a problem hiding this comment.
+1 be sharp.
What do you mean by this?
There was a problem hiding this comment.
i.e. remove "Please" 😉
| You may override the default branch with the [remote_branch] setting in the | ||
| mkdocs.yml configuration file, but forgetting to change directories before | ||
| running the deploy script will commit to the `main` branch of `my-project`, | ||
| likely overwriting the contents of your precious project. |
There was a problem hiding this comment.
Did you mean previous, or really precious? Sounds a bit too familiar. Maybe just remove it.
There was a problem hiding this comment.
OK thanks. I'd prefer we remove "precious" then. It particularly sounds bad for French readers, as we often use "precieux" sarcastically (I suspect it might be the same for other languages, and English in particular). Even if not, let's be concise as mentioned previously.
| to GitHub. Therefore, you may want to verify any changes you make to the docs | ||
| beforehand by using the `build` or `serve` commands and reviewing the built | ||
| files locally. | ||
| Please note that you will not be able to review the built site before it is |
There was a problem hiding this comment.
Same remark here about "please" (I don't think it's necessary).
| with the GitHub account name. Therefore, you need working copies of two | ||
| repositories on our local system. For example, consider the following file | ||
| structure: | ||
| User and Organization GitHub Pages sites are not tied to a specific project, |
There was a problem hiding this comment.
| User and Organization GitHub Pages sites are not tied to a specific project, | |
| User and Organization GitHub Pages sites are not tied to a project repository. |
There was a problem hiding this comment.
Looks like this suggestion wasn't committed but is now outdated. Could you update it? It's required for the suggestion right below it to make sense.
| repositories on our local system. For example, consider the following file | ||
| structure: | ||
| User and Organization GitHub Pages sites are not tied to a specific project, | ||
| and the site files are deployed to the `main` branch in a dedicated |
There was a problem hiding this comment.
| and the site files are deployed to the `main` branch in a dedicated | |
| By default, the site files are deployed to the `main` branch in a dedicated |
| structure: | ||
| User and Organization GitHub Pages sites are not tied to a specific project, | ||
| and the site files are deployed to the `main` branch in a dedicated | ||
| repository named with the GitHub account name. Therefore, you will need working |
There was a problem hiding this comment.
| repository named with the GitHub account name. Therefore, you will need working | |
| repository named after the GitHub account or organisation. Therefore, you will need working |
| User and Organization GitHub Pages sites are not tied to a specific project, | ||
| and the site files are deployed to the `main` branch in a dedicated | ||
| repository named with the GitHub account name. Therefore, you will need working | ||
| copies of two repositories on your local system. For example, consider the |
There was a problem hiding this comment.
| copies of two repositories on your local system. For example, consider the | |
| copies of two repositories on your local system: one for the website's source markdown or text files, and one for the deployed website. For example, consider the |
There was a problem hiding this comment.
I clarified what the two repositories actually refers to, but in reality this entire section should be rewritten. It is at present not true or the case that one needs a separate repository for the source files. As with any repository Pages site, you can choose the deployment source in the repository settings, with options for both automation with Actions or deployment from a branch of your choosing (with or without /docs subfolder) using the built-in deployment.
A proper fix for this would be to delete the organisation section in its entirety, and describe changing the deployment source if necessary.
I may or may not implement this in this PR, depending on whether it gets merged before I get to it or not.
There was a problem hiding this comment.
Doing it in another PR sounds good to me.
| with the [remote_branch] configuration setting, but if you forget to change | ||
| directories before running the deploy script, it will commit to the `master` | ||
| branch of your project, which you probably don't want. | ||
| Please note that you need to explicitly point to the `mkdocs.yml` configuration |
There was a problem hiding this comment.
+1 be sharp.
What do you mean by this?
| You may override the default branch with the [remote_branch] setting in the | ||
| mkdocs.yml configuration file, but forgetting to change directories before | ||
| running the deploy script will commit to the `main` branch of `my-project`, | ||
| likely overwriting the contents of your precious project. |
|
Fair that! I'll commit the changes suggested to a new branch.
…On Sun, 5 May 2024, 12:17 am Timothée Mazzucotelli, < ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In docs/user-guide/deploying-your-docs.md
<#3692 (comment)>:
>
-User and Organization Pages sites are not tied to a specific project, and the
-site files are deployed to the `master` branch in a dedicated repository named
-with the GitHub account name. Therefore, you need working copies of two
-repositories on our local system. For example, consider the following file
-structure:
+User and Organization GitHub Pages sites are not tied to a specific project,
+and the site files are deployed to the `main` branch in a dedicated
+repository named with the GitHub account name. Therefore, you will need working
+copies of two repositories on your local system. For example, consider the
Doing it in another PR sounds good to me.
—
Reply to this email directly, view it on GitHub
<#3692 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AD32W6GHGS4WNRCJT346DFDZAVM75AVCNFSM6AAAAABHCITN5CVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDAMZZGU2TKNJSGQ>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
re: GitHub Pages