Publish your book online#

Once you’ve built the HTML for your book locally, you can host it online. In this manual, we’ll cover how to publish your book online in TU Delft GitLab and make it publically available.

In order to publish your book at the TU Delft webpage, you first have to create a repository to TU Delft GitLab, upload the necessary content and, finally communicate your request to the responsible department. Below are all the required steps in detail.

Working with Git#

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 whatever you’re working on) and to collaborate on projects, with an easy way of integrating changes. Rather than making new copies of a document every time you add changes (a very common practice among scientists writing papers, alas), the Git software keeps track only of the changes in your document, allowing you to step back however far you wish, and to compare versions - both with changes you made, and with changes made by collaborators. The ‘undo’ option in many other software packages does the same thing. Very likely you’ve unwittingly already worked with versions of Git, for example when writing on Overleaf.

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. You can then be added to 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 VS Code. 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.

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. There is no need to do any of this if you integrate with an IDE.

  1. 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
    
  2. If you want to add the files to track with Git, you need to use git add command. if you want to add new or modified or deleted files to the current directory, then add . to select all the files.

    git add .
    
  3. 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"
    
  4. 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
    
  5. Get the changes from the remote with git pull.

    git pull origin master
    
  6. Push the commits to the GitLab project.

    git push origin master
    
  7. If any problem occurs in pushing, use the following command for force push.

    git push --force origin master
    

Publish your book online to GitLab#

We have just pushed the source files for our book into our GitLab repository. This makes them publicly accessible for you or others to see.

Read this before you publish anything!

Before performing the steps below, ensure that an 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 this procedure, the following commands may not work, and you may lose uncommitted work!

Now, it is time to publish the build artifact of your book online, so that it is rendered as a website. For this, use 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> should 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.

To update your HTML files and 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.

Working with GitLab through VS Code#

This process is expl

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

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.

More Information#

Find out more about creating your book: