Skip to content
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

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 38 additions & 24 deletions docs/user-guide/deploying-your-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Contributor

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).

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
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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

repository named with the GitHub account name. Therefore, you will need working
Copy link
Author

Choose a reason for hiding this comment

The 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
repository named after the GitHub account or organisation. Therefore, you will need working

copies of two repositories on your local system. For example, consider the
Copy link
Author

Choose a reason for hiding this comment

The 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
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

Copy link
Author

Choose a reason for hiding this comment

The 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.

Copy link
Contributor

Choose a reason for hiding this comment

The 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/
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is "Please" really necessary here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 be sharp.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 be sharp.

What do you mean by this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be concise.

Copy link
Contributor

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did mean precious.

Copy link
Contributor

@pawamoy pawamoy May 4, 2024

Choose a reason for hiding this comment

The 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

Expand Down
Loading