Summary and Schedule
Prerequisites
Before following this lesson, learners should ideally be able to:
- create a project on GitLab / EMBL GitLab.
- clone a local copy of a project with Git, add and commit modified files, and push/pull changes between local and remote repositories.
- execute commands in the shell.
None of the prerequisite above is absolutely necessary to follow the lesson. They will, however, be necessary to efficiently manage the website development from your laptop and test how it looks before creating official versions.
If you’d like to learn any of the skills listed above, the [Software Carpentry][swc] lessons on [the Shell][swc-shell] and [Git][swc-git] are a good place to start.
For those already familiar with the ways that Git and an online platform like GitLab or GitHub can help them track and compare changes to flat text files and collaborate with others on projects, GitLab (and GitHub) Pages provide a cost-free way to build and host webpages. This approach is commonly used to provide documentation on software projects, and to create blogs and websites for individuals and organisations already used to working with the Git toolset for their other projects. However, for those taking their first steps towards building sites like this, the process can be confusing and intimidating. This tutorial aims to address this, by
- providing a step-by-step guide to creating a collection of pages,
- showing multiple examples of how to structure them into a coherent site,
- demostrating how to use multiple frameworks for web pages development, from plain HTML to Jekyll and Sphinx.
The difference between GitLab and GitHub pages development will also be briefly discussed.
Outdated Screenshots
Throughout this lesson we will make use and show content and screenshots from git.embl.de. As an ever evolving platform, GitLab is always adding new features and new visual elements to its website. Screenshots in the lesson may then become out-of-sync, refer or show content that no longer exists.
If during the lesson you find screenshots that no longer match what you see in your browser, please open an issue describing what you see and how it differs from the lesson content. Feel free to add as many screenshots as necessary to clarify the discrepancy.
| Setup Instructions | Download files required for the lesson | |
| Duration: 00h 00m | 1. Introduction |
What is static web content? Why should I use GitHub or GitLab Pages to create my website? |
| Duration: 00h 00m | 2. Authoring With Markdown |
How can I write content for my webpages? How do I link to other pages? |
| Duration: 00h 00m | 3. Hosting Pages on GitLab | How do I publish my pages via GitLab? |
| Duration: 00h 00m | 4. GitLab Pages with Jekyll | |
| Duration: 00h 00m | 5. GitLab Pages with Sphinx | How do I publish web pages through GitLab and Sphinx? |
| Duration: 00h 00m | 6. GitLab Pages with Jupyter books | How do I publish web pages through GitLab and Jupyter books? |
| Duration: 00h 00m | 7. GitLab Templates | Where can I find pre-built projects/themes for my site? |
| Duration: 00h 00m | 8. When things go wrong | How do I troubleshoot errors in the GitLab pipelines? |
| Duration: 00h 00m | Finish |
The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.
Required
Prior to the workshop you will need to setup a free account for GitLab or (preferentially) on the local EMBL instance git.embl.de. If you need assistance with loggin in the EMBL GitLab platform, check these instructions.
Optional
During the course we will teach how to use GitLab in the online platform, but not how to use Git locally on your laptop. Still, knowing Git might be useful to take your web dev skills next level. So, please consider installing the Bash Shell and Git in your laptop, following these instructions from The Carpentries.
Once you have Git and the Bash Shell installed, you are all set to follow these training materials and learn the basis of Git.