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. Name your repo something like your-lab-website to avoid confusion with the template itself
4. Enable GitHub Actions on your repo to allow automatic citations
5. Enable GitHub Pages on your repo with the default settings (main and /root)
6. Set up your site's url
7. Your site should be live!

Set up your url

There are a few choices you have for where your live site appears. Choose which example url below you like best and follow the given one-time instructions.

https://your-lab.github.io/your-lab-website (a "GitHub project site")

The simplest option. This is what you'll have by default after enabling GitHub Pages (if you didn't configure anything else).

1. Set the baseurl field in your site configuration to /your-lab-website (where your-lab-website is what you named your repo)
2. Publish the changes.

https://your-lab.github.io/ (a "GitHub user/organization site")

A cleaner url, but you must name your repo specifically.

1. Rename your repo to your-lab.github.io (where your-lab is your GitHub user or organization name) per GitHub requirements
2. Set the baseurl field in your site configuration to ""
3. Publish the changes.

https://your-lab.com/ (a custom url/domain)

The best option, if you can afford it. 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).

1. 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 (creates a CNAME file)
2. Set the baseurl field in your site configuration to ""
3. Publish the changes.

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 the site's Publish directory to _site/
4. Set the site's Build command to sed -i 's/baseurl:.*/baseurl: ""/' _config.yaml && jekyll build
5. Set the deploy 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 you're using 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.

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