Skip to content

docs: mention .nojekyll file to avoid issues with _astro directory - #12106

Merged
sarah11918 merged 13 commits into
withastro:mainfrom
trueberryless:github-pages-nojekyll-file
Aug 1, 2025
Merged

sarah11918 merged 13 commits into
withastro:mainfrom
trueberryless:github-pages-nojekyll-file

Conversation

@trueberryless

@trueberryless trueberryless commented Aug 1, 2025 •

Copy link
Copy Markdown
Contributor

Description (required)

Add documentation for adding a .nojekyll file and downgrade the other caution aside to normal text.
Also adding a link in the new paragraph to this article as it perfectly describes this specific problem with the solution. I think it's okay to link to this article here, we can remove the link tho if you think so.

Related issues & labels (optional)

@netlify

netlify Bot commented Aug 1, 2025 •

Copy link
Copy Markdown

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit 6b0662b
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/688d0a17dbb0560009b8a5f7
😎 Deploy Preview https://deploy-preview-12106--astro-docs-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@astrobot-houston

astrobot-houston commented Aug 1, 2025 •

Copy link
Copy Markdown
Contributor

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File Note
en/guides/deploy/github.mdx Source changed, localizations will be marked as outdated.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

@bjohansebas bjohansebas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM

@sarah11918 sarah11918 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This looks great, and just like what I was thinking of @trueberryless !

I've done some light editing of the text for your consideration!

trueberryless and others added 6 commits August 1, 2025 20:08
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
@trueberryless

Copy link
Copy Markdown
Contributor Author

Awesome, thanks for all the beautiful suggestions, reads much more user-friendly now! 🙌

LGTM 👍

@sarah11918 sarah11918 added add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. Merge Queue Approved and ready to be merged (wait for feature release if also labelled M-O-R)! labels Aug 1, 2025

@sarah11918 sarah11918 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thank you for adding this extra needed info so people can be successful deploying! I don't doubt that there are other improvements that could be made to this page, but our immediate need was to make sure people had the new info that was missing, and this does that wonderfully! 🎉

@sarah11918
sarah11918 merged commit 0ba9dba into withastro:main Aug 1, 2025
@trueberryless
trueberryless deleted the github-pages-nojekyll-file branch August 1, 2025 19:28
ArmandPhilippot added a commit to ArmandPhilippot/astro-docs that referenced this pull request Aug 4, 2025
@vrabe

vrabe commented Aug 4, 2025

Copy link
Copy Markdown
Contributor

I investigated this before. My finding is if I follow the guide and use withastro/action + actions/deploy-pages in the action, .nojekyll file isn't needed. That file is only needed when I commit the build to a branch and "Deploy from a branch". I wrote a blog post for it (in Chinese).

@vrabe

vrabe commented Aug 4, 2025 •

Copy link
Copy Markdown
Contributor

I just read the discussion on Discord. This PR really simplifies the whole thing too much. I disagree with this PR but I don't think it'll be changed. I had better not translate it and add a caution in my blog post.

@delucis

delucis commented Aug 4, 2025

Copy link
Copy Markdown
Member

Thanks @vrabe — I don’t have the full context, but was also a bit surprised to see this PR as I’ve often deployed to GH Pages using the approach in this guide and never needed a .nojekyll file.

@sarah11918

Copy link
Copy Markdown
Member

I just read the discussion on Discord. This PR really simplifies the whole thing too much. I disagree with this PR but I don't think it'll be changed. I had better not translate it and add a caution in my blog post.

@vrabe I don't know why you don't think it will be changed! We had two people testing and following advice found in others blogs and this worked for them, and it seemed consistent with content linked from the issue of someone saying "this worked for me" so we published it. We really do want to get it correct, of course!

Can you suggest exactly what is incorrect here? As in, by editing sections of text with suggested improved wording? It seems that no one can ever agree on this guide in particular, and I honestly don't know why it causes so many problems for people and yet there never seems to be one method that everyone agrees on.

The only thing I can do is review changes to text as I'm unfamiliar with this deploy method myself, and need people saying "this part of the instruction should say X instead" to give examples of updated text that corrects it. I don't know how to interpret and improve this document based on "this simplifies it too much" and can only rely on our reviewers who report that following the instructions does or doesn't work for them.

If you are willing to contribute corrections, then please do! That is the only way these guides are improved and we welcome that!

@vrabe

vrabe commented Aug 4, 2025 •

Copy link
Copy Markdown
Contributor

@sarah11918 It's completely correct! It's just in the wrong place. I don't want readers follow the guide and add the file which isn't needed even though it's not harmful. Instead users who write their own workflow files and/or upload their builds to gh-pages branch are the target audience. This approach is not even seen in the guide. I understand it's hard to find out and mention who needs to read this part of guide. But the arrangement of the guide is so strange that I have to point out.

@ArmandPhilippot

Copy link
Copy Markdown
Member

Thanks @vrabe for catching that! I was part of the earlier discussion and since I'm not familiar with Github Pages, I wasn't aware of these subtleties! Doing some researches in Github docs, I thought the .nojekyll file was necessary in every cases.

Rereading Static site generators (for future reference, in case this topic came up again) with your explanation makes a bit more sense. But, I think the need or not of a .nojekyll file is still subtle in their docs... I guess what was confusing for me was reading about Configuring a publishing source for your GitHub Pages site and checking the Astro action without finding any .nojekyll reference. 😅

So thank you again for testing and reporting this! 🙌🏽

@sarah11918

sarah11918 commented Aug 5, 2025 •

Copy link
Copy Markdown
Member

Thanks @vrabe and for all the extra context!

You may have noticed that we've reverted this PR to go back to the original guide, and you're right, we don't mention deploying with gh-pages at all in this guide. After discussing internally with the team, we've decided that's intentional, and we do not intend to show guidance for deploying with gh-pages and to only show deploying with our GitHub Action. Therefore, we don't need to show this information at all, and following our guide to the letter should lead to a successful outcome.

While it is possible to deploy in different ways, the docs team has decided that the only method we intend to document is using our GitHub Action. So in future, we shouldn't end up making this mistake again! 😄 And, if someone reports deployment not working for them, we will confirm that they are following this method, exactly as laid out. If they decide they would rather deploy another way, they are welcome to, and they can visit support for help, but we will not be documenting any other methods.

Thank you again for helping us sort through this all! Many of us here are not experience with GH Pages deployment, and are trying our best to respond when people report issues following our instructions. But now, I think more of us are better informed about how to respond to reports like this in future because of your input!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. Merge Queue Approved and ready to be merged (wait for feature release if also labelled M-O-R)!

Projects

None yet

Development

Successfully merging this pull request may close these issues.

(en) github.mdx: The description of the text is discrepancy.

7 participants