Update GitLab Pages deployment guide

[menghif]

Description (required)

This PR improves the Deploy your Astro Site to GitLab Pages guide in the following ways:

• Use Expressive Code title and diff features for code blocks.
• Separate site and base from the main deployment steps and add more information about the two options (similar to the "Deploy to GitHub Pages" Guide).
• Add .gitignore changes for the build output folder.

I tested deployments on Gitlab.com with a repository under my profile and another one under a group.

Related issues & labels (optional)

• Closes Error in Gitlab deploy code? #8780
• Suggested label: "improve documentation"

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	ab1957a
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/669ac765197ff6000806a8b2
😎 Deploy Preview	https://deploy-preview-8811--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Vercel 🥳

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[astrobot-houston]

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

Locale	File	Note
en	guides/deploy/gitlab.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.

[sarah11918]

Thank you @menghif for testing deployment and adding helpful information to the docs!

So that I can better review the deploy preview, could you please make the following changes first:

1. Please do not use all 1. for our ordered lists. Please revert these back to their original numbers. I know it renders the same in Markdown, but it is harder to maintain if we know there is a typo in "Step 3" -- it's easier to compare the code to the output for community members making small edits.

2. It's very helpful to have the extra context from the GitHub deploy guide! Thank you for adding! However, like that page, this information is helpful to have first, not last on the page. This is what messes people up the most, and it's the most complicated thing to understand, so they should tackle it first while they're fresh. And, after finishing a set of steps, people will expect things to work... and it will not! So like the other page, can you bring that information up as the first thing people should set!

3. With the above changes: you should keep base and site from the code example in lines 32-33 because they will have already set those, which is a good thing! Now we do not show an "incomplete" example of what their config should look like.

4. Double check that everything that did say gitHUB now says gitLAB (I notice at least lines 92 and 93)

Thank you again, this contribution is very helpful! After you make these changes, I'll read through it again and look closely for any typos or small fixes etc.!

[menghif]

Hi @sarah11918, thank you for the feedback! I can definitely make all those changes.

I thought I would separate base and site since they are not required for deploying an Astro site to GitLab (as opposed to GitHub Pages). The official example from GitLab that we link to does not include them. I tried to do the same on one of my test repos and the website was deployed successfully.

Let me know if this information changes anything on how I should rewrite the page.

[sarah11918]

Just to clarify what you mean: they are not needed, but if you have set them, this is how they work?

If they're not needed then I'm not sure why they are included here at all. Can you explain more about why you added them here, and what you mean when you say you tested them?

[menghif]

The site option is not needed but strongly recommended. The Astro docs explain that it is used to generate the sitemap and canonical URLs.

The base option is technically not needed but, not having one can lead to problems like failing to load css files or images. My example repository was deployed successfully without a base option only because it is a simple Astro "Get Started" single page. A more complex site would not work correctly without base.

I understand the logic of putting site and base as the first step of the instructions to avoid causing potential problems. I modified the page accordingly!

[sarah11918]

Thanks! I added a couple of more questions calling out specific content because I'm worried this may have been just taken from GitHub, which works differently from most other hosts. We went through a LOT of careful pain figuring out exactly what was needed for GitHub pages, and we haven't had similar comments/complaints about GitLab. So I just want to be EXTRA sure that we are not overcopying and using GitHub as a kind of general model... because from our experience, GitHub pages has been anything but typical! 😂

[sarah11918]

Thank you so much @menghif for your patience and attention to detail here! We really appreciate having updated content that works! Welcome to Team Docs! 🥳