Using GitHub

Section 2.1 Using GitHub

Subsection 2.1.1 What is 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

cocalc.com

(see Section 5.14) and GitLab

about.gitlab.com/

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 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

github.com/signup

. 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).

Tip!

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 increase GitHub’s free Codespaces usage quotas.

Apply at Education.GitHub.com

⁴

education.github.com/discount_requests/pack_application

to unlock these features. In our experience, applications are usually processed quickly for .edu email addresses, but you do not need to wait for approval to continue on with this tutorial.

Subsection 2.1.2 Three GitHub concepts

This tutorial uses three GitHub services:

Codespaces (github.dev): The Codespace for your project is an application run in your web browser that gives you access to a virtual computer with all the software recommended to author PreTeXt installed for you automatically. This Codespace is private to you, and lives at an address like https://username-random-words-abc123.github.dev.
Repository hosting (github.com): The repository for your project represents the history of its edits that have been “committed and synced” from your Codespace to it. This repository can be public or private (though we encourage public repositories as they help the community provide support for each other), and lives at an address like https://github.com/username/reponame/.
GitHub Pages (github.io): The GitHub Pages service provides free hosting for websites such as the HTML generated from a PreTeXt project. This website is public, and lives at an address like https://username.github.io/reponame/.

Broadly speaking, you “author” within your Codespace, which you periodically “commit and sync” to your repository, and then occassionally “deploy” to your public GitHub Pages website.

Subsection 2.1.3 Creating your repository and Codespace

Follow the instructions at https://github.com/PreTeXtBook/pretext-codespace to get started creating your repository and Codespace. You’ll have the option to make your repository public (recommended if you want support from the rest of the PreTeXt community) or private. Either way, those instructions will also walk you through creating your private Codespace for authoring.

This takes a few moments, but is a one-time process. Take note of the github.com URL your new repository lives at so you can find it the next time you want to work on your project. (You can always access your github.dev Codespace link from there via the Code menu.) Then you’ll be ready for Section 2.2.

Prev Top Next