Creating a Reproducibility Guide using Github Pages

Let's do reproducible science! We can create a Github Page that goes along with our project repo (our project code on github) that walks others through our project, code, analyses, and how to reproduce or implement all code associated with a given publication.

Step 1. Navigate to your local github repository in the terminal

Step 2. Create a new branch associated with your repo that has no files and no commit history

git switch –orphan gh-pages

Step 3. Create a _config.yml file which includes the page title, description, logo (image file), and theme for your Project Page.
Your _config.yml file should look something like this:

title: <br>Cortical Myelin Maturation
description: <br>Project Information and Reproducibility Guide
logo: ./project_abstract.png
theme: jekyll-theme-minimal

The title appears at the top of the Project Page. This can be left blank, commented out, or deleted if desired.
The description appears somewhere below the title. This can be left blank, commented out, or deleted if desired.
If using a logo (project_abstract.png), you must upload the image file to the gh-pages branch (see below). This can be commented out or deleted if desired.
The theme controls what your Project Page looks like. Themes can be selected with jekyll-theme-themename; supported themes are listed here https://pages.github.com/themes/ and you can preview what they look by searching here http://jekyllthemes.org/

Step 4. Create an index.md file.
This file includes all of the text, links, etc. that you want to include on your Project Page! The text you write should comply to and will follow the formatting of Markdown syntax: https://github.com/Manuel83/sample/blob/master/index.md. Here is an example of an index.md file that served as one of Valerie’s study reproducibility guides.

Step 5. Add, commit and push your config file, index file, and logo image to the gh-pages branch

git add _config.yml index.md project_abstract.png 
git commit -m “initiating Project Page!” #edit the message after -m to your liking
git push gh-pages

Step 6. Tell github to build your Project Page from your gh-pages branch
Finally, go to your github repository on github.com (in the web browser) and follow these steps:

• Click on Settings on your repo page
• Click on Pages on the left column
• Under “Build and deployment” select “Deploy from a branch”
• Under Branch, change “main” to “gh-pages” and click Save

Your site should be live ! At https://labneurocogdevel.github.io/my_reponame or https://mygitusername.github.io/my_reponame (depending where your repo lives)

Step 7+. Toggle between gh-pages and main branches for Project Page and code editing
Once your gh-pages branch has been initiated and your site is live, you can edit the logo/description/theme (_config.yml) or content (index.md) while on your gh-pages branch by making the desired changes and then following the git add - git commit - git push process. When you are (temporarily or permanently) done making changes and want to work on your actual code again, just check out your main branch!

git checkout main

Now you can continue to used github for your code as before!