-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update deploying-your-docs.md re: GitHub Pages #3692
base: master
Are you sure you want to change the base?
Changes from all commits
492e1ee
afc4c56
9c17c97
061f07d
fe557b2
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -16,7 +16,7 @@ which require a different work flow when deploying. | |||||
|
||||||
Project Pages sites are simpler as the site files get deployed to a branch | ||||||
within the project repository (`gh-pages` by default). After you `checkout` the | ||||||
primary working branch (usually `master`) of the git repository where you | ||||||
primary working branch (usually `main`) of the git repository where you | ||||||
maintain the source documentation for your project, run the following command: | ||||||
|
||||||
```sh | ||||||
|
@@ -30,27 +30,29 @@ That's it! Behind the scenes, MkDocs will build your docs and use the | |||||
Use `mkdocs gh-deploy --help` to get a full list of options available for the | ||||||
`gh-deploy` command. | ||||||
|
||||||
Be aware that you will not be able to review the built site before it is pushed | ||||||
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 | ||||||
deployed to GitHub. Instead, you may want to verify any changes you made by | ||||||
using the `build` or `serve` commands and reviewing the built files locally | ||||||
before running `gh-deploy`. | ||||||
|
||||||
WARNING: | ||||||
You should never edit files in your pages repository by hand if you're using | ||||||
the `gh-deploy` command because you will lose your work the next time you | ||||||
run the command. | ||||||
The site files in the `gh-pages` branch are **automatically generated** and | ||||||
updated when using the `gh-deploy` script. | ||||||
As such, you should never make any changes to the site files of your GitHub | ||||||
Pages site by hand. Doing so will cause you to lose these changes the next time | ||||||
the `gh-deploy` script or command is called. | ||||||
|
||||||
WARNING: | ||||||
If there are untracked files or uncommitted work in the local repository where | ||||||
`mkdocs gh-deploy` is run, these will be included in the pages that are deployed. | ||||||
`mkdocs gh-deploy` is run, these will be included in the deployed Pages site. | ||||||
|
||||||
### Organization and User Pages | ||||||
|
||||||
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: | ||||||
Organization and User 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
repository named with the GitHub account name. Therefore, you will need working | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
copies of two repositories on your local system. For example, consider the | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Doing it in another PR sounds good to me. |
||||||
following file structure: | ||||||
|
||||||
```text | ||||||
my-project/ | ||||||
|
@@ -59,21 +61,33 @@ my-project/ | |||||
orgname.github.io/ | ||||||
``` | ||||||
|
||||||
After making and verifying updates to your project you need to change | ||||||
directories to the `orgname.github.io` repository and call the | ||||||
`mkdocs gh-deploy` command from there: | ||||||
After making and verifying updates to the `my-project` repository, change | ||||||
directories to the `orgname.github.io` repository and call the `mkdocs | ||||||
gh-deploy` command from there: | ||||||
|
||||||
```sh | ||||||
cd ../orgname.github.io/ | ||||||
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master | ||||||
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch main | ||||||
``` | ||||||
|
||||||
Note that you need to explicitly point to the `mkdocs.yml` configuration file as | ||||||
it is no longer in the current working directory. You also need to inform the | ||||||
deploy script to commit to the `master` branch. You may override the default | ||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is "Please" really necessary here? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. +1 be sharp. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
What do you mean by this? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Be concise. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. i.e. remove "Please" 😉 |
||||||
file in the `my-project` folder, as it is now no longer located in your current | ||||||
working directory. | ||||||
You will also need to specify the `main` branch as the branch the deploy | ||||||
script should commit to. | ||||||
|
||||||
NOTE: | ||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Did you mean previous, or really precious? Sounds a bit too familiar. Maybe just remove it. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I did mean precious. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||||||
|
||||||
WARNING: | ||||||
The site files in the `main` branch are **automatically generated** and updated | ||||||
when using the `gh-deploy` script. | ||||||
As such, you should never make any changes to the site files of your GitHub | ||||||
Pages site by hand. Doing so will cause you to lose these changes the next time | ||||||
the `gh-deploy` script or command is called. | ||||||
|
||||||
### Custom Domains | ||||||
|
||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same remark here about "please" (I don't think it's necessary).