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. Create 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. Make a fork of 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 commit history
3. Enable GitHub Actions on your repo to allow automatic citations
4. Enable GitHub Pages on your repo with the default settings (main and /root)
5. Set up your site's url to ensure the template can work properly
6. Your site should be live!

Set up your url

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-lab-domain.com/	""

Where your-lab is your GitHub user or org name. Choose which type you like the best, then:

1. Rename your repo accordingly. To avoid confusion with the template itself, please don't leave your repo name as lab-website-template.
2. Set the baseurl field in your site configuration accordingly. Failing to do this properly can cause unexpected problems.
3. Publish the changes.

Custom domain

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

To setup a custom url, 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 Jekyll outputs your built site to)
4. Set Netlify's Build command to sed -i 's/baseurl:.*/baseurl: ""/' _config.yaml && jekyll build. This will automatically set baseurl to "" before building on Netlify, because Netlify previews are 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 with any of the workflows below, Netlify will post a comment on it with a link to the preview.

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.

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

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

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.

On your computer

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)
3. If working from a fork, enable GitHub actions on the FORK, BEFORE opening the pull request, otherwise automatic citations might not work
4. Clone the repo to your computer
5. Edit the cloned site on your computer with your favorite text editor
6. Commit and push the changes with Git
7. If working from a branch or fork, make a pull request to your main website repo, preview the changes, and merge when ready to publish

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

Update the template

Here's how to update your site to the latest version of the template.

If your repo says generated from greenelab/lab-website-template, see this post about pulling upstream changes from a template repository. Requires manually resolving merge conflicts, because there is no shared commit history between the two repos.

If your repo says forked from greenelab/lab-website-template, see this article about syncing a fork. Allows automatic merging, though some items will still need to be resolved manually.