How to develop the BCCA website

This guide explains how to set up GitHub, GitHub Copilot, Visual Studio Code, extensions, Git, and the local Jekyll development environment for the Bassendean Community Children’s Association website.

The website is a static Jekyll site. It uses HTML, CSS, JavaScript, YAML data, and Markdown content. You do not need a traditional server-side application or framework to edit it.

1. What you need

Before beginning, make sure you have:

A Windows computer.
An internet connection.
A GitHub account.
A GitHub Copilot subscription or access through an eligible plan. (The free one is fine)
Visual Studio Code.
Git.
Ruby and Bundler.
A terminal in Visual Studio Code.

The commands in this guide are written for Windows PowerShell. If you use Git Bash, the same Git commands work, but the PowerShell environment variables below will need to be adapted.

2. Create a GitHub account

Open https://github.com/.
Select Sign up in the upper-right corner.
Enter your email address and choose a strong password.
Choose a GitHub username. Use a name you are comfortable sharing publicly.
Confirm that you are human if GitHub requests verification.
Select Create account.
If prompted, complete the account-security checks.
Sign in to GitHub and open Settings → Emails to verify your email address.
Add a GitHub email address that you check regularly. This is important because GitHub uses it for account recovery and repository notifications.

You may be asked to enable two-factor authentication. GitHub offers several security methods, including passkeys and authenticator applications. A passkey is usually the simplest option for a personal computer.

GitHub Copilot availability depends on the plan and account type offered to you. The free plan has been offered to eligible users, but GitHub can change its availability and limits.

Sign in to GitHub.
Open https://github.com/features/copilot or go to Settings → Billing and plans.
Review the available Copilot plans.
Choose a plan that includes Copilot Chat and completion features.
If you are using a free plan, follow the prompts to join the eligible free tier and confirm your account information.
Sign out and back in if GitHub does not immediately show Copilot in your account.
Open the GitHub Copilot subscription page in your account settings and confirm that the correct plan is active.

If you are using GitHub through an organisation, ask the organisation owner whether Copilot is already enabled for your account. You may need to accept an invitation or sign in through the organisation’s GitHub account.

Do not share your password, authentication codes, or private API keys with an AI assistant. Copilot can help edit and explain code, but you remain responsible for reviewing the produced changes.

4. Install Visual Studio Code

Open https://code.visualstudio.com/.
Select Download for Windows.
Run the installer.
Select Add Visual Studio Code to PATH if the installer offers that option. This makes it easier to open the editor from PowerShell.
Select Install.
After installation, open Visual Studio Code.
If prompted, select Open Visual Studio Code.

To verify the installation, open a PowerShell terminal and run:

code --version

If the command is not found, restart PowerShell and run the command again. You can also use the Command Palette with Shell Command: Install ‘code’ command in PATH.

5. Install Git

Git is required to work with GitHub and to track changes in the repository.

Download Git for Windows from https://git-scm.com/download/win.
Run the installer and allow Git to add itself to your PATH.
Restart Visual Studio Code or the PowerShell terminal.
Verify Git:

git --version

Configure your Git identity for commits. Replace the sample values with your own name and email:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Verify the configuration:

git config --global --list

Use an email that GitHub can associate with your account. If GitHub provides a GitHub-specific email address, you can use that address here.

6. Install the recommended Visual Studio Code extensions

Open Visual Studio Code, select Extensions in the left sidebar, and search for the following extensions. Install each one that is not already installed.

GitHub Copilot

Search for GitHub Copilot.
Install the extension published by GitHub.
Search for GitHub Copilot Chat.
Install that extension as well.
Open the Command Palette with Ctrl+Shift+P.
Run GitHub Copilot: Sign in.
Follow the browser prompts to sign in with the GitHub account that has the Copilot plan.

Copilot can help explain files, generate code, suggest content, and review changes. It is not a replacement for reviewing the source files or testing the site.

Realistically though, if you make it here you should be alright. Between Google and Copilot you should be able to fenagle your way into making changes -> reviewing them locally -> creating a pull request -> merge to kick off a build.

GitHub Pull Requests and Issues

Install the extension named GitHub Pull Requests and Issues by GitHub. It provides a convenient interface for issues, pull requests, and branch-based workflows.

GitLens

Install GitLens — Git supercharged. It adds useful Git features, including commit history, repository status, blame information, and branch management.

Markdown Preview Enhanced

Install Markdown Preview Enhanced by shd101wyy. This is useful for previewing these instructions and any documentation you create.

Markdownlint

Install Markdownlint by David Anson. It checks Markdown formatting and common mistakes. You can enable formatting on save with the Markdownlint: Format all files command.

YAML

Install YAML by redhat. This helps validate YAML files such as _data/navigation.yml and _data/committee.yml.

Prettier

Install Prettier - Code formatter by Prettier. It helps keep HTML, CSS, JavaScript, and Markdown consistent. You can use Format Document from the Command Palette or enable format-on-save.

Code Spell Checker

Install Code Spell Checker by streetsidesoftware. It helps catch typos in content and documentation.

Jekyll and Liquid support

The repository does not currently include a dedicated Jekyll extension. Instead, use the Jekyll build and the Markdown, YAML, and HTML extensions above. The Jekyll compiler can still be run from the terminal.

Recommended optional extensions

-files: GitHub for repository file links and interactions.
Files: Explorer for selecting files from the workspace.
Better Comments for colour-coded comments.
Live Server for a simple local static preview, although this project should use the Jekyll build and local server command because it depends on Liquid and generated site assets.

You can install all of the extensions from the Extensions view by searching for the names above. The editor will often suggest installing an extension when you open a file type or use a feature.

7. Connect Visual Studio Code to GitHub

Open Visual Studio Code.
Open the Command Palette with Ctrl+Shift+P.
Run GitHub: Sign in.
Enter the GitHub account that owns or has access to the repository.
Complete any two-factor authentication or browser approval steps.
Confirm that the account appears in the Source Control view.

Open the Extensions view.
Search for GitHub Pull Requests and Issues.
Select the extension and choose Sign in.
Select the correct GitHub organisation or personal account.
If prompted, authorize the extension and allow it to use GitHub.

Connect a repository

If you are already using a local repository, follow these steps:

Open the repository folder in Visual Studio Code.
Open the Source Control view.
Select Initialize Repository if the folder is not already a Git repository.
If the repository is already initialized, you can use the Source Control view to create a branch and make commits.

If you have not downloaded the repository yet, clone it from GitHub:

git clone https://github.com/AndrewRLogan/bcca-website.git
cd REPOSITORY
code .

8. Apply to contribute and clone the website repository

The repository must already exist and the project owner must grant you contributor access before you can push changes.

Apply to become a contributor using the repository owner’s approved process.
Wait until your GitHub account has been granted access to the repository.
Sign in to GitHub with the account that has contributor access.
Open the repository and confirm that you can push to the repository or create branches from it.
Clone the existing repository locally:

git clone https://github.com/AndrewRLogan/bcca-website.git
cd bcca-website
code .

Confirm the remote is the repository you were granted access to:

git remote -v

Create a descriptive branch from the appropriate main branch:

git switch main
git pull origin main
git switch -c your-branch-name

Use a branch name that describes your work, such as update-home-page or add-committee-profile.

9. Install Ruby and Bundler

The site is configured with Jekyll 4.4 and Gemfile-based plugins. Ruby is the runtime used to build the site locally.

Windows installation with RubyInstaller

Download RubyInstaller from https://rubyinstaller.org/.
Run the installer.
Choose a recent Ruby version supported by the project’s gems.
Add Ruby and Bundler to your PATH.
Restart the terminal after installation.
Verify Ruby:

ruby -v

Verify Bundler:

bundle -v

If bundle is not available, install it:

gem install bundler

If Ruby resolves to the wrong installation

The current project instructions mention a common Windows problem where ruby resolves to an application-controlled Ruby installation, often under C:\Program Files. This can cause permission errors while installing gems.

First check where Ruby is being resolved:

Get-Command ruby
ruby -v

If Ruby is not from the installation you want, place your Ruby installation first on the current PowerShell PATH. For example:

$env:Path = "C:\Ruby40-x64\bin;$env:Path"

Replace the path with the actual version installed on your computer. Then verify:

ruby -v
bundle -v

Only change the current terminal’s PATH if you do not want this setting to apply across sessions. You can also add the Ruby installation directory permanently through the Windows environment editor after verifying the path.

10. Install the project dependencies

Open the project folder in Visual Studio Code. Then run the following commands in the integrated PowerShell terminal:

gem install bundler
bundle install

The bundle install command reads the Gemfile and installs the Jekyll and plugin dependencies required by the site.

If Bundler reports that a gem cannot be installed, run the following commands:

gem update --system
bundle update

If you see a permission error, confirm that the Ruby executable used by the terminal is the Ruby installation you installed, then rerun the command.

Do not commit the generated vendor, node_modules, or local Ruby gem caches. The project already excludes vendor and Gemfile.lock in _config.yml, but other local environment files should also be ignored.

11. Build and preview the website locally

The site uses a Jekyll layout and _data files. The local server should be started from the repository root.

Run the site with the recommended command

From the integrated terminal, run:

bundle exec jekyll serve --livereload

Open:

http://127.0.0.1:4000/

Jekyll rebuilds the site when its source files change. The --livereload option reloads the browser when files are changed.

Run the site from a VS Code task

Open the Command Palette with Ctrl+Shift+P.
Run Tasks: Run Task.
Select Serve site locally if the repository has a task configured.
If the task is not listed, create a task or run the command manually from the integrated terminal.

The current repository should contain a task configuration before this option appears. If the task does not exist, you can add one to .vscode/tasks.json.

Run a one-time build without serving

bundle exec jekyll build

The generated site is written to _site/. The _site/ folder is normally ignored by Git, and the README describes this folder as a local preview output.

12. Understand the website structure

The site is organized around the following files and folders:

index.html — the home page.
about.html — the about page.
contact.html — the contact page.
support.html — the support page.
_layouts/default.html — the common page layout.
_includes/header.html — the shared header.
_includes/footer.html — the shared footer.
_data/navigation.yml — the main navigation links.
_data/committee.yml — committee member details.
assets/css/style.css — the main site stylesheet.
assets/img/ — images used by the site.
_config.yml — Jekyll site settings and excluded files.
Gemfile — Ruby dependencies.
CNAME — the custom domain used for GitHub Pages.

The page files use Jekyll front matter. For example, the home page begins with:

---
layout: default
title: Home
hide_title: true
---

The YAML front matter controls how Jekyll processes the page. The layout setting selects the shared layout, while title and hide_title control the page heading.

13. Use the content data files

Edit _data/navigation.yml to change the navigation labels and URLs. The file currently contains a list of navigation entries with title and url fields.

Example:

- title: About Us
  url: /about/

Committee members

Edit _data/committee.yml to change committee member names, roles, images, and blurbs. Each member should include the name, role, image, and blurb fields.

Example:

- name: "Jane Doe"
  role: "Committee Member"
  image: "/assets/img/committee/jane-doe.png"
  blurb: "A short description of the committee member."

Make sure that an image path is valid and that the image exists under assets/img/committee/.

Site title and metadata

Edit _config.yml for global site settings such as the site title, description, email, and URL. The file includes the Jekyll site settings used by the website.

14. Edit and preview changes

Open the relevant page or data file in Visual Studio Code.
Make the change.
Save the file with Ctrl+S.
Check the editor’s Errors screen for HTML, YAML, CSS, or Markdown problems.
Run the local site preview if you need to inspect the rendered page:

bundle exec jekyll serve --livereload

Open the local site in a browser.
Test the page, links, images, navigation, and content on desktop and mobile widths.
Run a full build before pushing:

bundle exec jekyll build

Review the generated files in _site/ if needed, but do not commit generated output unless the project specifically requires it.

15. Use Git and GitHub for changes

Create a branch

From the repository root, run:

git status
git switch -c your-branch-name

Use a descriptive branch name, such as update-home-page or add-committee-profile.

Review changes

git diff
git diff --stat

Review every change before committing. If you used Copilot to generate content, verify accurate names, URLs, spelling, accessibility, and page behavior.

Commit changes

git add .
git commit -m "Describe the change"

The git add . command stages all changes in the current repository. If you only want to commit selected files, replace the period with the specific paths.

Push the branch

git push -u origin your-branch-name

The origin remote must point to the repository where you have contributor access. If it does not, update the remote before pushing.

Open a pull request

Sign in to GitHub.
Open the BCCA website repository.
Select Compare & pull request.
Choose the branch you changed.
Select Create pull request.
Add a clear title and description.
Use the pull request to explain what changed and how it was tested.

16. Publish the site with GitHub Pages

This repository is described as a GitHub Pages site. The build is normally performed by GitHub rather than by your local computer.

Open the repository on GitHub.
Select Settings → Pages.
Choose the source branch used for the site.
Select the branch and folder expected by the repository, commonly main and / or /docs.
Select Save.
Confirm that the repository contains a CNAME file with the public domain if the site uses a custom domain.
Push the branch to GitHub.
Wait for GitHub Pages to build the site.
Open the public URL shown in the Pages settings.

If the repository has no GitHub Pages configuration, use the repository’s existing settings or ask the project owner for the required branch and domain configuration. Do not rename or move the generated _site/ folder as a substitute for configuring GitHub Pages.

17. Configure the GitHub account and repository settings

For a personal development workflow, make sure that:

Your GitHub account has a verified email address.
GitHub Copilot is enabled for the correct account.
The repository is public or private as intended.
The default branch is named main or the branch that your workflows expect.
Your GitHub account has permission to push to the repository.
The remote URL points to the correct repository.

Check the repository remote:

git remote -v

If the remote is wrong, remove and add the correct repository URL:

git remote remove origin
git remote add origin https://github.com/AndrewRLogan/bcca-website.git

Use the exact repository URL granted to you, and confirm that your account has permission to push to the repository.

18. Troubleshooting

`code` is not recognized

Open Visual Studio Code and run Shell Command: Install ‘code’ command in PATH from the Command Palette. Restart PowerShell, then run:

code --version

Git is not recognized

Install Git for Windows, restart the terminal, and run:

git --version

If Git still does not work, search the installed Git location and add its bin folder to the PATH.

Copilot does not appear

Confirm that you signed in to the correct GitHub account.
Confirm that your account has an eligible Copilot plan.
Confirm that your organisation has enabled Copilot.
Restart Visual Studio Code.
Run GitHub Copilot: Sign in from the Command Palette.
Open the GitHub Copilot settings and verify the account and plan.

Ruby or Bundler is not recognized

Check ruby -v and bundle -v. If Ruby is from the wrong application, move a recent Ruby installation to the front of the PATH as described above.

`bundle install` fails

Run:

ruby -v
bundle -v
Get-Command ruby
Get-Command bundle

Confirm that Ruby and Bundler come from the same installation. Then rerun:

bundle install

If the project uses a newer Ruby version than the installed version supports, install a newer Ruby version before running Bundler again.

Jekyll cannot find a page or image

Check the file path and use the project-relative path. For example, an image in assets/img/committee/ should be referenced with a path beginning at the site root:

<img src="/assets/img/committee/cara.png" alt="Cara">

Jekyll links and assets can use Bash or Liquid expressions in the existing project. Use relative_url for site root paths when the page is rendered under a subpath or custom domain.

The site does not refresh after file changes

Stop the existing server and start it again:

bundle exec jekyll serve --livereload

Then open http://127.0.0.1:4000/. If the terminal is still running, use Ctrl+C to stop it before starting a new server.

GitHub Pages shows an error

Confirm that the site is built from the correct branch.
Confirm that the source folder is correct.
Confirm that the repository is compatible with GitHub Pages.
Check the GitHub Pages build log.
Re-run bundle exec jekyll build locally to catch Jekyll errors first.

19. Recommended development routine

For each change:

Open the repository in Visual Studio Code.
Sign in to GitHub and Copilot.
Create a branch for the work.
Edit the relevant HTML, CSS, YAML, or Markdown file.
Use Copilot for explanation or suggestions, but review all output.
Validate files with the editor’s Errors view.
Run the local Jekyll preview.
Test important pages and links.
Run bundle exec jekyll build.
Commit and push the changes.
Open a pull request or publish through the expected GitHub Pages workflow.

20. A quick checklist

Before starting to build the website, verify that you can complete all of these items: