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
Add a more generic deploy command and deprecate gh-deploy #3373
Labels
Comments
Hi, i like @Andre601's idea, i however i would love to have an option to set a different repo as well so i could have the documents in repo 1 and the site it self in repo 2. Second thing is that i would have the settings in the mkdocs.yml like: deployment:
repo_url: https://github.com/esphome/esphome[.git] # the .git could be optional.
repo_branch: gh-pages
repo_username: ....
repo_pw: !ENV git_password |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
As per this comment does the
gh-deploy
command seem to be nothing more than a defaultmkdocs build -> Commit to branch gh-pages -> Push
with the target branch being the only GitHub-specific thing.I've mentioned it in the linked discussion, but repeat it here again for sake of being clear: I believe it would be a beneficial move to have the
gh-deploy
command be deprecated and instead add a more genericdeploy
command to use.The main reason here is, that when people look at the command (And especially its description when running
--help
) do they get the impression that the command is only meant for GitHub and GitHub Pages when it could theoretically be used for any remote git repo host.With a more generic command name, people would know that it can be used for hosts other than GitHub.
I personally would imagine the following command structure:
TARGET_BRANCH
would be required here. Reason is that withgh-deploy
we can assume the default beinggh-pages
but with a more neutral command, this wouldn't be a good aproach as other repo hosts such as Codeberg have different branch names (In that examplepages
).Tho maybe MkDocs could assume the branch to use based on the provided repo URL in the config (if any), but I feel like this would be kinda risky to do here...
[OPTIONS]
could be one or multiple of these (Basically copied from gh-deploy help):One issue I can think of is a feature of MkDocs, which is displaying the URL your page is being deployed to, which I assume has some logic involved regarding CNAME file and github.io URL stuff, but I believe this option could be safely dropped as it usually doesn't have any main use outside of being informative.
Tho, if it should be included could perhaps the site_url within the config file be used to display. Or MkDocs could look for certain files (CNAME for GitHub, .domains for Codeberg as an example) to get the domain from...
Another alternative to the above suggestion I could see here is to deprecate the
gh-deploy
command and instead recommend and promote CI/CD setups to automatically publish your pages with.I could think of two examples right now that could be shown in the docs:
Tho, I can see the benefit in having a deploy command for a quick and easy update of the site, so personally would I go with the first suggestion instead of the latter one.
The text was updated successfully, but these errors were encountered: