Quick Start Guide: GitHub Pages

IntroductionInstructions

Introduction

GitHub Pages are public webpages hosted and published through GitHub. The following sections provide instructions on how to set up a GitHub Pages site. Complete them in order.

Important Note

These instructions are for Windows only.

Prerequisites

Ensure that the following tools/programs have been installed:

• Git
• GitHub Desktop
• Visual Studio Code (VS Code)
• Python and Pip
• MkDocs
• Material for MkDocs
• Vale

Notes

• Installing Python and Pip is a prerequisite to installing MkDocs.
• Vale must be installed locally and as an extension in VS Code with spell check enabled.

Create a Repository

1. Open GitHub Browser.

2. Click New at the top of the dashboard.

   

3. Enter the new repository name into the corresponding field.

4. Provide any additional settings.
5. Click Create repository at the bottom of the window.

Clone the Repository

1. Navigate to the desired repository.

2. Click <> Code.

   

3. Copy the URL.

4. Open GitHub Desktop.

5. Select the Current repository drop-down list.

   

6. Click Add > Clone repository.

   

7. Select the URL tab.

8. Paste the URL into the corresponding field.

9. Click Clone.

   

Create a New Branch

1. Select a repository from the Current repository drop-down list.

2. Click the Current branch drop-down list.

   Note

   Ensure the current branch selected is Main.

3. Click New branch.

   

4. Enter the branch name into the corresponding field.

5. Click Create branch.

   

6. Click Publish branch.

Configure the Repository

1. Create and publish a new branch.
2. Click Open in Visual Studio Code in GitHub Desktop.
3. Open the VS Code terminal.

4. Run the following command to create a docs folder and the mkdocs.yml and index.md files:

   mkdocs new .
   

5. Open the mkdocs.yml file.

6. Add the following plugins to the file:

   MkDocs Material PluginsPython Plugins

   theme:
     name: material
     icon:
       repo: fontawesome/brands/github
       edit: material/pencil
     features:
       - navigation.tabs
       - navigation.tracking
       - navigation.expand
       - toc.integrate
       - content.action.edit
     language: en
   

   markdown_extensions:
   - admonition
   - codehilite
   - smarty
   - pymdownx.magiclink
   - pymdownx.betterem
   - pymdownx.details
   - pymdownx.emoji
   - pymdownx.saneheaders
   - pymdownx.highlight
   - pymdownx.critic
   - pymdownx.caret
   - pymdownx.mark
   - pymdownx.tilde
   - pymdownx.inlinehilite
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.tasklist:
       clickable_checkbox: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format  
   - pymdownx.tasklist:
       custom_checkbox: true          
   - attr_list
   - md_in_html
   - sane_lists
   - tables
   

7. Save the changes.

8. Click the New Folder icon.

   

9. Enter “.github/workflows”.

10. Click the New File icon.

    

11. Enter “ci.yml”.

12. Open the ci.yml file.

13. Paste the following into the file:

    name: ci
    on:
      push:
        branches:
          - master
          - main
    permissions:
      contents: write
    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - uses: actions/setup-python@v4
            with:
               python-version: 3.x
          - uses: actions/cache@v2
            with:
              key: ${{ github.ref }}
              path: .cache
          - run: pip install mkdocs-material
          - run: mkdocs gh-deploy --force
    

14. Save the changes.

15. Exit the .github folder.
16. Click the New File icon.
17. Enter “.vale.ini”.
18. Open the .vale.ini file.

19. Paste the following into the file:

    StylesPath = .github/styles
    
    MinAlertLevel = warning
    
    Vocab = vale
    
    [*.md]
    BasedOnStyles = Vale
    ignore = URL, Consistency
    
    Vale.Terms = NO
    

20. Save the changes.

21. Select the .github folder
22. Click the New Folder icon.
23. Enter “styles/config/vocabularies/vale”.
24. Click the New File icon.

25. Enter “accept.txt”.

    Note

    The accept.txt file allows spelling rule exceptions.

26. Save the changes.

27. Commit the changes to Main.

Create a Virtual Environment

Info

Setting up a virtual environment within a repository’s directory using Python’s venv module provides the ability to preview changes made before making a commit. It will run a web server that exposes the website at http://127.0.0.1:8000.

1. Click Open in Visual Studio Code in GitHub Desktop after creating a new branch.
2. Open the terminal in VS Code.

3. Enter the following commands into the terminal:

   python -m venv ./venv
   ./venv/scripts/activate
   

4. Run:

   mkdocs serve
   

5. Open the http://127.0.0.1:8000 link.

Publish to GitHub Pages

1. Open GitHub Browser.
2. Navigate to the repository being used.

3. Select the Settings tab at the top of the window.

   

4. Select Pages from the left-hand side menu.

5. Select gh-pages from the branch drop-down list and select /(root) from the file drop-down list under the page’s Branch section.

   

6. Click Save.

7. Click Visit Site at the top of the page.

   

Sign-off Date	Name
03/09/2024	Mickey Mouse