Get Started

Set up your site

To set up the basics of your site, follow these one-time instructions:

1. Make a GitHub account.
2. Start your copy of this template in one of two ways:
   1. Generate a new repo from this template under your account with the button (leave Include all branches unchecked), if you want a fresh copy of the template and a clean break.
   2. Fork this repo under your account with the button, if you want to more easily update your template version and you're okay with having the the development of this template in your repo's commit and actions history.
3. Name your repo something like your-lab-website (to avoid confusion with the template itself).
4. Make sure "template repository" is OFF in your repo settings (so people don't accidentally use it as a template or confuse it with Lab Website Template itself).
5. Enable GitHub Actions on your repo (to allow automatic citations).
6. Enable GitHub Pages on your repo with the default settings (to start hosting your site).
7. Set up your site's url (to ensure the template can work properly, ⚠️ NOT OPTIONAL).
8. Set up previews (if you want to be able to preview changes before publishing them).
9. Your site should be live!
10. Edit your site to make changes.

Edit your site

First, find the items you need to edit to make the changes you want. Then, choose the workflow that best suits you:

On GitHub

This workflow is the easiest and requires no installation, but only allows changing 1 file at a time and usually isn't as nice as working in a good text editor that has syntax highlighting, more advanced controls, etc.

1. Edit an item through the GitHub website interface
2. Choose "Commit directly to the main branch" to publish your changes immediately, OR choose "create a new branch and start a pull request" to preview your changes before merging and publishing them

On your computer

This approach requires installing and experience with Git, but is usually easier for larger edits.

1. Install Git.
2. Decide how you'll be making changes:
   1. Make changes directly to the main branch of your website repo (publishes changes immediately).
   2. Make changes to another branch (e.g. add-sarah-bio) of your website repo (allows previewing changes before publishing).
   3. Make changes to a fork of your website repo (allows previewing changes before publishing). Unfortunately, ⚠️ making changes from a fork is not supported, due to GitHub security limitations.
3. Clone the repo to your computer.
4. Edit the cloned site on your computer with your favorite text editor.
5. Commit and push the changes with Git.
6. If working from a branch, make a pull request to your main website repo, preview the changes, and merge when ready to publish.

Set up your url

⚠️ This is not optional, even if you don't want a custom url. It is required for your website to appear and behave correctly. Failing to do this can cause unexpected problems, like non-working links, build errors, and site appearing plain/un-styled.

Choices

There are a few choices you have for where your live site appears:

Type of site	Rename your repo...	Url you get...	Set baseurl to...
GitHub "project site"	e.g. your-lab-website	https://your-lab.github.io/your-lab-website	/your-lab-website
GitHub "user/organization site"	Must be your-lab.github.io	https://your-lab.github.io/	""
Custom domain	e.g. your-lab-website	e.g. https://your-custom-domain.com/	""

(where your-lab is your GitHub user/organization name)

Choose which option you like the best, then:

1. Rename your repo accordingly.
2. Set the baseurl field in your site configuration accordingly.
3. Publish the changes.

Custom domain

Purchasing a custom domain is highly recommended. It looks professional, it's easier to remember and type, and it's easy and cheap to set up (.coms are usually only about $10 per year).

To setup a custom domain, follow the instructions above accordingly, then follow the instructions here. In summary:

1. Purchase a domain name from a reputable service.
2. Point your domain name provider to GitHub Pages using an A record. This is slightly different for each company; they should have their own instructions on how to do it.
3. Set the custom domain field in the settings of your repo (automatically creates a CNAME file).

Set up previews

When you or someone on your team wants to make changes to your website, you'll likely want a convenient way to 👁️ preview and ✏️ review the changes before publishing them. To set this up, follow these one-time instructions:

1. Make a Netlify account.
2. Hook up Netlify to your website repo.
3. Set Netlify's Publish directory to _site/ (the directory where your built site outputs to).
4. Set Netlify's Build command to sed -i 's/baseurl:.*/baseurl: ""/' _config.yaml && jekyll build (to automatically set baseurl to "" before building on Netlify, because Netlify previews are always hosted at root).
5. Set the Netlify notifications you want. A bunch are enabled by default. We recommend deleting them all, then adding just:
   • GitHub commit status → Deploy Preview succeeded
   • GitHub commit status → Deploy Preview failed
   • GitHub pull request comment → Deploy Preview succeeded
   • GitHub pull request comment → Deploy Preview failed

Now, when you open or update a pull request on GitHub, Netlify will post a comment on it with a temporary link specific to that pull request that shows the site with the new changes (i.e. how your live site will look after the pull request is merged).

It will also put a check/status on the pull request that shows a big red warning if the changes cause the site to fail to compile for some reason. You can use this to prevent merging/publishing when the changes fail.

Update the template

If you've already created your website with the template, and the template has since changed, here's how to update your site to the latest version of the template.

If your repo was generated from the template, see this post about pulling upstream changes from a template repository. Requires manual merging (because there is no shared commit history between the two repos).

If your repo was forked from the template, see this article about syncing a fork. Allows automatic merging, though some items will still need to be resolved manually.