docs: improved GitLab deployment docs

[DobbiKov]

divided gitlab deployment into two sections (pixi + poetry) and improved the tutorial for gitlab deployment with pixi

Changes:

• Previously the GitLab deployment documentation contained a window with two tabs: for pixi and poetry. As deployment with pixi requires lots of steps, I divided them into two separate sections (deployment with pixi and poetry).
• I added more details to the deployment process with pixi, especially I have tried to inform that we can use pixi for deployment without using it for other purposes in the project
• Fixed syntax errors in provided code

Things to consider:

• I don't think that pushing lock file should be obligatory, it is a file that should be created on CI part
• The documentation should be more detailed for people who use institutional gitlab and myst for writing documents but are not familiar with git nor gitlab.

@FreekPols @sbonaretti

#myst-education-2026

Closes jupyter-book/jupyter-book#2648

[changeset-bot]

⚠️ No Changeset found

Latest commit: c2ea536

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[fwkoch]

Thanks for the PR! This looks great - hiding the poetry instructions in a tab behind pixi instructions didn't really make sense (especially since pixi instructions were already partially outside the tabs too). Nice you've broken it up and created sections with explicit (and improved) instructions for each.

I won't merge quite yet, in case either of the folks you tagged have comments.

Oh - there's also some overlap with the recent PR from @sbonaretti: #2959 - We should probably make sure content and structural changes from both PRs are included.

[FreekPols]

Will take a look later, also need to make a small change for the server instruction which changes due to higher nodejs

[DobbiKov]

Thank you for your feedback. I've just pushed a new commit where I added a section called deployment where the steps are as simple as possible without technical details to make it less confusing for people who are not familiar with programming and other tools such as uv, pixi, etc. The CI is using uv with slim debian and installs node.js to deploy the pages.

I would like to hear your opinion about this section.

[sbonaretti]

Thanks @DobbiKov for your contributions! Great work!

@maintainers (@fwkoch, @choldgraf, and all): @DobbiKov and I were in the same working group at #myst-education-2026, together with also @chavid and others. If that works for you, we can close the PR I created yesterday #2959 and work directly on this one! Please, let me know if you prefer to close the PR #2959 yourselves or want me to close it (same here!).

Thanks! :)

[FreekPols]

Oeh, I would prefer that... and then test it on our gitlab pages as well and add the things that I found on multibranch output with GL and --execute.

[DobbiKov]

Oeh, I would prefer that... and then test it on our gitlab pages as well and add the things that I found on multibranch output with GL and --execute.

Would be nice if you test the last pipeline that I've added (with uv) and you say if it works for your institutional gitlab. I would like to improve this one.

[DobbiKov]

@fwkoch @FreekPols @sbonaretti what do you think about making detailed tutorial for people who are not familiar with git or terminal about pushing must book to gitlab pages ?

[FreekPols]

@fwkoch @FreekPols @sbonaretti what do you think about making detailed tutorial for people who are not familiar with git or terminal about pushing must book to gitlab pages ?

Ideally a myst init --gl-pages would do most of the work for you...

I am a little hesitant about the amount of information to provide on either GL or GH, I would point to existing resources like TTW.

Another option is to expand the jupyter workshop to include for GL.

[sbonaretti]

For a bit more context about the whole page, line 8 could be removed and substituted with the following:

=====================
There are different ways to do so:

• Deployment
• Deployment with poetry
• Deployment with pixi

In this page, you will learn also find information on how to host your webpage on an external server through GitLab CI/CD

=====================

Also:

• How can we specify the first Deployment better?
• Please, double-check that the links above with # work

[DobbiKov]

• How can we specify the first Deployment better?

This is a good question. I named it deployment to show that it happens independently from user's package manager, to be more precise, without technical details. Just paste a file with provided contents and it will work. However, the name should be changed.

On the other hand, we could make poetry and pixi subsections of a section choose your favourite package manager.

[sbonaretti]

What about Deployment the easy way?

[sbonaretti]

@fwkoch @FreekPols @sbonaretti what do you think about making detailed tutorial for people who are not familiar with git or terminal about pushing must book to gitlab pages ?

Ideally a myst init --gl-pages would do most of the work for you...

I am a little hesitant about the amount of information to provide on either GL or GH, I would point to existing resources like TTW.

Another option is to expand the jupyter workshop to include for GL.

I added a comment at line 13 with an admonition containing infos for new GitLab users. I tried the steps myself this morning as I had never used GitLab before. It took me quite a bit to find the links to the right official pages, so I hope this is going to be useful!

[sbonaretti]

Oeh, I would prefer that... and then test it on our gitlab pages as well and add the things that I found on multibranch output with GL and --execute.

Would be nice if you test the last pipeline that I've added (with uv) and you say if it works for your institutional gitlab. I would like to improve this one.

@DobbiKov I have just tried this:

1. Created the .yml file as here (lines 26-76)
2. Pushed the file as here (lines 20-22)

And I get the following error:

[sbonaretti]

Oh - there's also some overlap with the recent PR from @sbonaretti: #2959 - We should probably make sure content and structural changes from both PRs are included.

I closed PR #2959

[sbonaretti]

This addresses the comments

[sbonaretti]

We could add something like this people who have never used GitLab before:

=====================
:::{tip}New to GitLab

If this is your first time using GitLab, complete these one-time setup steps:

1. Install Git
2. Create a GitLab account
3. Set up SSH authentication

Once set up, you have two options to connect your project to GitLab:

1. Start from GitLab: Create a repository on GitLab, clone it to your computer, add your files, and push them
2. Start from your computer: Initialize your local folder as a Git repository and push it to GitLab using the following commands:

   cd your-project-folder   # go to your local folder
   git init                 # initialize git
   git add .                # stage all files
   git commit -m "first commit"
   git remote add origin git@gitlab.com:username/project.git
   git push -u origin main

:::

=====================

We can also make the admonition collapsible by adding :class: dropdown below :::{tip}New to GitLab

[DobbiKov]

This is a very good idea, I will work on that this evening :)

[DobbiKov]

I suggest do it in the next way: in Instructions section add :::{warning} that says if you are new to gitlab please proceed to the section Instructions for beginners` (of course it will be a link that will point to the section). In that section we will describe detailed process.

On the other hand, people who are not familiar with git, usually are not familiar with terminal neither. Thus, we have a question, should we describe the whole process as for complete beginners who never touched terminal. With explanations about how to install code editor, create myst project, and push to gitlab.

[sbonaretti]

For the first part, as you want

For the second part, I think we can assume a minimum of knowledge of the terminal commands, as they use it also to create the book itself...

[DobbiKov]

I have finally added information about where to find GitLab Pages. However, it does not work for everyone and it depends on the configuration of each gitlab, i.e. sometimes, someone should manually pass trough the windows of setting up GitLab because GitLab thinks that pages are not enabled, for someone just .gitlab-ci.yml push is enough.

@fwkoch @FreekPols We tested the setup with @sbonaretti and it works. Do you think we are ready to merge?

[FreekPols]

I run your script and needed to add a -y (question in CLI). After that fix it works, nice.
Also made a notification on the dependence of institution gitlab settings and updated my server script. Made a P.R. to your branch to have it included here...

After this, I think it is ready to merge

[DobbiKov]

I run your script and needed to add a -y (question in CLI). After that fix it works, nice. Also made a notification on the dependence of institution gitlab settings and updated my server script. Made a P.R. to your branch to have it included here...

After this, I think it is ready to merge

Done!