Introduction

The purpose of this post is to help you create a report website to for a team project. Sharing your work with the class and the broader community is important, as you should generate a persistent portfolio of class work to demonstrate your abilities when you apply for a job or academic career.

We will be using github to host and share websites this year. This is for a couple reasons:

• Hosting websites on github is free.
• Git is iterative. As your project evolves we can see how it has changed
• Editing content is easy, using either the web interface or windows-based clients.

Note: This template extends the basic website creation tutorial by making it possible to clone an existing repository, which uses mkdocs

Video Overviews

• Video overview for individuals
• Setting up organizations to work with the report template
• triggering that first build

External Resources

• https://learn.microsoft.com/en-us/devops/develop/git/what-is-git
• https://en.wikipedia.org/wiki/Git
• https://www.git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F
• (older) Make a Project Repository and Website: </make-a-website/>

Procedure

1. Go to Github.com
2. Create an account under the free plan
3. Verify your email, and sign in.
4. Once created, go to the template you want to fork and click on the “fork” link. This may include the:

• 304 Team Report Template

• 304 Individual Datasheet Template

• 314 Team Report Template

• 314 Individual Datasheet Template

  Note: Forking a repository creates a new repository that is linked through github to the original.

  fork

  1. De-select the “copy only the main branch” option.

  fork screen

  2. To make a website at https://.github.io, the name ofo the repository needs to be <yourusername>_EGR3x4_<semester><YY>.github.io

     For example, for a person with a user name of danaukestest01 in the Fall of 202X for EGR 304, we need to name the new repository danaukestest01_EGR304_F2x.github.io ** Or, for a person with a user name of knichols789 in the Spring of 2029 for EGR 314, the new repository would be: knichols789_EGR314_S29.github.io

2. Go to settings and then select “pages” from the links on the left side.

   1. Under “branch”, select “gh-pages”

      select gh-pages

   2. Next to the gh-pages option, select “/root” as the folder

      select /root

   3. Save

3. Go to “Actions”. If there are no errors, your page will build and show a green check box(this can take ~5 minutes):

   successfully built

4. Navigate to your web-page. Your page should now be visible at https://your-username.github.io

Settings to check

If you are forking the repository into an organization, check that

1. Deploy keys are enabled

   Ensure deploy keys are enabled

   1. Go to organization’s home, then click on settings
   2. (settings–>deploy keys –> set to enabled)

2. Github actions has read/write permission

   Check workflow permissions

   1. Go to organization’s home, then click on settings
   2. (settings–>actions–>general, then scroll down to workflow permissions and ensure that read/write permissions are enabled)

If you are forking the repository into your user account, check that

1. Deploy keys are enabled
   1. go to repository’s home, then click on settings
   2. (settings–>deploy keys –> set to enabled)
2. Github actions has read/write permission
   1. go to repository’s home, then click on settings
   2. (settings–>actions–>general, then scroll down to workflow permissions and ensure that read/write permissions are enabled)

Help, My site is not building

If, after you have checked the above settings, often renaming the workflow file will initiate builds, (for whatever reason).

1. Either on your computer or on the github website, in the files of your repository, navigate to .github/workflows/.
2. Rename pages.yml to something else (main.yml worked for me).
3. Stage, commit, and push your files
4. Check the “actions” tab (found in your repository’s main github page) to see that your commit is triggering the “mkdocs-build” action.

This seems to be required only once.