Skip to main content

The PreTeXt Guide

Section 2.1 Using GitHub and Codespaces

Subsection 2.1.1 GitHub

GitHub is a freely-available service for authoring, sharing, and deploying documents and source code, owned by Microsoft. It uses the free and open-source Git software for version management.
There are other services such as CoCalc 1  (see Section 5.14) and GitLab 2  for managing PreTeXt documents online, as well as other ways to write PreTeXt that don't require anything besides installing the free and open-source PreTeXt software onto your own device (see Section 2.4 to learn more).
We will use GitHub's service for this tutorial as it the most popular way to share and disseminate PreTeXt documents, and provides the easiest pathway to getting started writing in the PreTeXt language.
To create your free GitHub account, follow the instructions on GitHub's signup page 3 . You can also log into an existing GitHub account if you already have one. Be sure to note your GitHub username and password in your password manager (or however you usually keep track of login credentials).
Educators and non-profit researchers can get many of GitHub's paid features for free. While this is not strictly required for the rest of the tutorial, it's a useful way to avoid GitHub's limit on free Codespaces usage.
Apply at Education.GitHub.com 4  to unlock these features (in our experience, applications are usually processed quickly for .edu email addresses).

Subsection 2.1.2 Codespaces

A Codespace is an authoring environment that lives in the “cloud”, that is, a virtual machine hosted by GitHub that has all of the software needed to create great accessible documents, accessible with just your web browser.
This coding environment uses a web version of Virtual Studio Code, an open-source text editor, along with the PreTeXt community's custom plugins and software to get started authoring quickly.
Follow the instructions at https://github.com/PreTeXtBook/pretext-codespace to get started. You'll have the option to make your work public (recommended if you want support from the rest of the PreTeXt community) or private.
Either way, this is a one-time process. Take note of the URL your new repository lives at (something like https://github.com/user-name/repository-name) so you can find it the next time you want to work on your project. Then you'll be ready for Section 2.2.
cocalc.com
about.gitlab.com/
github.com/signup
education.github.com/discount_requests/pack_application