Skip to content

Github Pages#

Github Pages is an easy way to create a documentation website (Like this one!).

Creating a GitHub Pages documentation site#

Devex has a UMN GitHub Pages template you can use to setup a Github Pages site quickly with Material for MkDocs; this template currently leverages a Docker container for the MkDocs installation, but for production sites it's recommended to use python for the installation.

To use the template, click the 'Use this template' button in the upper right. Instructions on how to customize the repository are in the README.

[!IMPORTANT] If you use a custom domain for your site, be aware of the possibility of subdomain takeovers! Do not delete the repository where you have the custom domain set, or your domain could be immediately recycled by a malicious entity.

Deleting a GitHub Pages documentation site#

  1. Request that NTS deletes the CNAME alias for your site's custom domain if one exists
  2. Remove the custom domain from Pages settings
  3. Follow GitHub's Deleting a GitHub Pages site instructions

Verifying a custom domain for your GitHub Pages site#

If you use a custom *.umn.edu domain for your Pages site, you should verify it in GitHub. Verification proves you own the domain and protects it from subdomain takeover - once verified, no one else can publish a Pages site to that domain unless you release it first.

[!IMPORTANT] Verify your domain before anyone else does. GitHub Pages domain verification happens at the org or user level, not enterprise-wide, so being part of the UMN enterprise does not automatically protect your subdomain. If a broader domain (for example umn.edu itself) gets verified before you verify your subdomain, your unverified site can be immediately released and taken over by someone else.

To verify your domain:

  1. Go to your org or personal account settings -> Pages
  2. Under Verified domains, click Add a domain
  3. Enter your custom domain (e.g. yoursite.umn.edu)
  4. GitHub will give you a DNS TXT record to add
  5. Submit that TXT record to NTS(nts-help@umn.edu) to have it added to DNS
  6. Once the record has propagated, return to the same page and click Verify

[!WARNING] Only request a DNS TXT record for your specific subdomain (e.g. yoursite.umn.edu). Never request a TXT record change on the root umn.edu domain - this is reserved for enterprise-level verification and modifying it could break enterprise-level domain protection.

Full instructions: Verifying your custom domain for GitHub Pages