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 https://github.com/embedded-systems-design/template_report and click on the “fork” link.

   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

   1. to make a website at https://.github.io, the name ofo the repository needs to be <yourusername>.github.io

      For example, for user danaukestest01, we need to name the new repository danaukestest01.github.io

5. 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

6. 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

7. 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
   1. go to organization’s home, then click on settings
   2. (settings–>deploy keys –> set to enabled)
2. Github actions has read/write permission
   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.