Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tools:project_reproducibility_guides_with_gh-pages [2024/07/30 10:56] – vsydnortools:project_reproducibility_guides_with_gh-pages [2025/08/18 10:44] (current) – [Step 4. doc/index.md] will
Line 3: Line 3:
 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. 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. Create a /docs directory in your local github repository**+To uses github's built-in support for the [[https://jekyllrb.com/|jekyll static site generator]], 
 +a minimal documentation setup includes a ''docs/'' directory with two files: ''_config.yaml'' and ''index.md''. 
 +<code> 
 +docs/ 
 +  _config.yaml   # theme and configuration 
 +  index.md       # actual documentation 
 +</code> 
 +===== Step 1. make docs/ ===== 
 + 
 +First, create a ''docs/'' directory in your local github repository 
 <code> <code>
 cd /path/to/mygithub/repo cd /path/to/mygithub/repo
Line 9: Line 19:
 </code> </code>
  
-**Step 2. Create a _config.yml file in docs which includes the page title, description, logo (image file), and theme for your Project Page.**\\ +===== Step 2. docs/_config.yml ===== 
-Your _config.yml file should look something like this:+ 
 +Create a ''_config.yml'' file in docs which includes the page **title**, **description**, **logo** (image file), and **theme** for your Project Page. 
 +Your ''_config.yml'' file should look something like this:
  
 <code> <code>
Line 19: Line 31:
 </code> </code>
  
-The title appears at the top of the Project Page. This can be left blank, commented out, or deleted if desired.\\ +  * 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.\\ +  * 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.\\ +  * If using a **logo** (eg ''project_abstract.png''), you must upload the image file to the selected branch (maybe ''gh-pages'' or ''main'', 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/+  * 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.**\\+===== Step 4. doc/index.md ===== 
 + 
 +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 [[https://github.com/PennLINC/thalamocortical_development/blob/gh-pages/index.md | an example of an index.md file]] that served as one of Valerie’s study reproducibility guides.  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 [[https://github.com/PennLINC/thalamocortical_development/blob/gh-pages/index.md | 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**+Here's a contrived example 
 +<code> 
 +# My Project 
 +This project **does amazing things**. Use it like 
 +```bash 
 +./01_organize_data.bash 
 +./02_run_stats.R 
 +``` 
 + 
 +> [!NOTE] 
 +> Watch out for this made up statistical //edge case// 
 +</code> 
 +===== Step 5. commit changes =====
  
 +Add, commit and push your config file, index file, and logo images. (Here we are using the ''main'' branch. Others may want to use ''gh-pages'' branch.)
 <code> <code>
 git add docs  git add docs 
-git commit -m “initiating Project Page!” #edit the message after -m to your liking+git commit -m "initiating Project Page!" #edit the message after -m to your liking
 git push origin main git push origin main
 </code> </code>
  
-**Step 6. Tell github to build your Project Page from /docs on your main branch**\\ +===== Step 6. configure github ===== 
-Finally, go to your github repository on github.com (in the web browser) and follow these steps:+Finally, tell github to build your Project Page from /docs on your main branch. 
 +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 **Settings** on your repo page 
-  * Click on Pages on the left column +  - Click on **Pages** on the left column 
-  * Under “Build and deployment” select “Deploy from a branch” +  - Under "__Build and deployment__" select **Deploy from a branch** 
-  * Under Branch, choose "main" and "/docs"+  - Under **Branch**, choose ''main'' and ''/docs'' (use ''gh-pages'' instead of ''main'' if you made that choice above).
  
 Your site should be live 8-)! At https://labneurocogdevel.github.io/my_reponame or https://mygitusername.github.io/my_reponame (depending where your repo lives) Your site should be live 8-)! At https://labneurocogdevel.github.io/my_reponame or https://mygitusername.github.io/my_reponame (depending where your repo lives)
 +
 +{{:tools:pasted:20250818-103700.png}}