[Sync to prerelease] Clarify that quarto publish gh-pages creates the branch automatically#2002
Merged
cderv merged 1 commit intoprereleasefrom Apr 28, 2026
Merged
Conversation
…#2001) * Clarify that quarto publish gh-pages creates the branch automatically The Source Branch section instructed users to manually create a gh-pages branch and configure Pages settings before publishing, but quarto publish gh-pages handles both already (gitCreateGhPages in quarto-cli). Lead with the automatic behavior, document the user/org site exception that still needs a manual source switch, and fold the manual git steps into a collapsible callout for users who want to set up the branch beforehand. Reported in quarto-dev/quarto-cli#14448. * Link GitHub docs and clarify user/org-site behavior is GitHub-specific * Link 'User and organization sites' term to GitHub docs for symmetry (cherry picked from commit 56cb6d7)
Member
|
/deploy-preview |
Contributor
Author
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-2002.quarto.org 🔄 Modified Documents |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Sync of #2001 to
prerelease.Original PR
Clarify that quarto publish gh-pages creates the branch automatically
The Source Branch section in
docs/publishing/github-pages.qmdinstructed readers to manually create agh-pagesbranch and configure GitHub Pages settings before runningquarto publish gh-pages. As reported in quarto-dev/quarto-cli#14448, this is misleading:quarto publish gh-pagesalready creates the branch (locally and on the remote) on its first run viagitCreateGhPages, and for project sites GitHub auto-detects the new branch and configures Pages without any settings change.The manual steps were added in #550 to address the case of a repo with no pre-existing
gh-pagesbranch, butquarto publish gh-pagesalready covers that.Changes
### Source Branchto lead with the automatic behavior.mainand does need a manual switch togh-pages) with the existing screenshot. Quarto already prints a notice with a direct link to the settings page in this case.git checkout --orphan gh-pagesrecipe into a collapsiblecallout-tipfor users who still want to set the branch up beforehand.## Publish Commandintro and the### Publishingopening sentence.The
#source-branchanchor is preserved so the existing link from## User Sitekeeps working.closes quarto-dev/quarto-cli#14448