4. Publish your book online#
Once you’ve built the HTML for your book, you can host it online. In this manual, we’ll cover how to publish your book online in TU Delft GitLab and make it public for everyone for free.
In order to publish your book at the TU Delft webpage, you have first to create a repository to TU Delft GitLab, upload the necessary content and finally, communicate your request with the responsible department. Below, you can find all the required steps in detail.
4.1. Working with Git#
4.1.1. Version control#
Git is a method for what software developers call version control, allowing you to efficiently store and share versions of your code (or whichever thing you’re working on) and to collaborate on projects, with an easy way of integrating changes. Rather than making new copies of a document anytime you add changes, the Git software keeps track only of the changes in your document, allowing you to step back however far you wish. This makes it easy to keep track of different versions - both with changes you made, and with changes made by collaborators. The ‘undo’ options in many other software packages do the same thing. Very likely you’ve unwittingly already worked with versions of git, for example when writing on Overleaf.
4.1.2. GitLab#
TU Delft hosts a local server with GitLab software, which is an implementation of Git with a lot of useful extensions. Anyone with a TU Delft NetID can get a GitLab account, simply by logging in on https://gitlab.tudelft.nl. There you can be added to existing projects or start your own.
The easiest way to work on a project on GitLab with version control is to use an integrated environment in an Integrated Development Environment (IDE), such as DataSpell that we discovered in Install the environment. The website of DataSpell contains detailed instructions. Many people find it easiest to start an empty project on GitLab, then link it (with the provided key) in their IDE; you can then simply add files to the project folder, which the IDE will sync for you with your GitLab repository. If you have never used Git, there are a few setup steps; plenty of online tutorials will guide you through them.
4.2. Upload a project from a local file system to GitLab#
Source: Stackoverflow: How to upload project from local file system to GitLab
NB: This is a hands-on instruction for use on a terminal. No need to do any of this if you integrate with an IDE.
You have to create a new repository. Use the following command to create a Git repository. It can be used to convert an existing, non-versioned project to a Git repository or initialize a new, empty repository. A .git folder is created in your directory. This folder contains Git records and configuration files. You should not edit these files directly.
git init
If you want to add the files to track with Git then you need to use
git add
command. if you want to add new or modified or deleted files in the current directory. then add.
to select all the files.git add .
git commit
creates a snapshot of the changes made to a Git repository which can then be pushed to the main repository. The-m
option of the commit command lets you write the commit message.git commit -m "first commit"
You add a “remote” to tell Git which remote repository in GitLab is tied to the specific local folder on your computer. The remote tells Git where to push or pull from. You have to create a project to hold your files. You should create a project in GitLab. This path should be given in the following command.
git remote add origin git@gitlab.com:username/projectpath.git
Get the changes from the remote with
git pull
.git pull origin master
Push
the commits to the GitLab project.git push origin master
If any problem occurs in pushing use the following command for
force
push.git push --force origin master
4.3. Publish your book online to GitLab#
We have just pushed the source files for our book into our GitLab repository. This makes it publicly accessible for you or others to see.
Read this before publishing anything!
Before performing the below steps, ensure that HTML has been built for each page of your book. There should be a collection of HTML files in your book’s _build/html
folder.
Also, make sure that you have already committed and pushed your book and everything works perfectly. Otherwise, review your work again, and try publishing later.
Lastly, make sure that your command line is at the base path of the project.
If you haven’t followed all the previous procedures, the following commands may not work, and you may lose uncommitted work!
I have uncommitted work but I don’t want to commit, yet. What can I do?
You can use the command git stash
which “saves” your work at the current state before running the commands for publishing. After publishing, run git stash apply
to return to your work!
Find more about git stash
at: Git Stash
Now, it is time to publish the build artifact of your book online, so that it is rendered as a website. For this reason, we have the following sequence of commands. There is no need to understand each step, but pay attention and change the text in <>
as mentioned.
git checkout --orphan <book-version-branch>
git reset
git add _build/html/*
git commit -m "New book version <book-version>"
git push origin <page-version-branch> --force
git update-ref -d HEAD
git reset
git checkout main --force
This is a non-reversible step!
Pay attention to the name of the branch that you will use! <book-version-branch>
whould be different than your main branch (usually ‘master’ or ‘main’) or any other working branch you use. Otherwise, you may lose all the activity of that branch including your files.
Book versions
If you want to separate the book in versions every time you publish your book, you can state the current version in the branch name (<book-version-branch>
) and at the commit message (<version>
)!
To update your HTML files, make changes to your book’s content on the working branch of your repository, re-build your book with jupyter-book build --all <book-path>
and then apply the same procedure with or without a different version name.
4.4. Communicate with TU Delft#
To ensure that your book appears on the central page of open books at TU Delft, it is necessary to notify the responsible department of any changes made. To do so, simply email ??? with the subject line “???” and include a link to the book each time you upload a new version. If you are uploading a newer version, please also provide the link to the previous version so that it can be updated accordingly. If you are not using book versions, simply provide the link once, and it will be automatically updated every time you make changes.
Only complete books
Moreover, if you are not using version control for your book, please ensure that your book is complete before proceeding to the previous step (Publish your book online to GitLab). This is important because your public book will be automatically updated with new content, and incomplete versions may be removed when identified.
4.5. More Information#
Find more information about creating your book: