Github

Hacksburg maintains a Github organization here.

Github

Board members should get push access to the Hacksburg repositories. For this, they will need to make a Github account (if they don't have one already). Members pushing to repos should use Git or some UI equivalent (eg, TortoiseGit for Windows).

A full Git tutorial is beyond the scope of this document, but in general, here's how you do things with regular command-line Git (TortoiseGit and other GUI-based Git clients will be different!).

To clone the Hacksburg website's GitHub repository, run:

git clone https://github.com/hacksburg/hacksburg.github.io

This will create a local copy of the remote repository on your machine (which you can then modify).

Github Pages

The Hacksburg website lives at hacksburg.org. It's hosted on Github's servers (thereby taking advantage of Github's good uptime). The repository is here.

Posting to the Site

The site is built automatically using GitHub Actions. Every time a pull request is merged into the master branch, an action runs which executes build.py to write posts to index.html based on the contents of posts.json.

To create a new post (or modify an existing one), clone the repository, modify posts.json, and create a pull request. Once your pull request is merged, the action will run and your post(s) will be live at https://hacksburg.org.

Post Structure

Posts, as defined in posts.json, have the following structure:

{
	"title": "Woodworking 101",
	"subtitle": "Make sawdust (and a wooden box) in Hacksburg's woodshop",
	"description": "<p>Attendees will have the opportunity to make a simple wooden box with handles and a lid. This project is designed to utilize almost all of the woodworking tools Hacksburg offers and provide a great introduction to woodworking.</p><p>To cover the cost of wood, this class will include a $30 materials fee.</p><p>Ages 16+. Attendees under 18 must be accompanied by a parent or guardian at all times.</p>",
	"date": "2025-02-16",
	"start_time": "01:00pm",
	"end_time": "04:00pm",
	"offsite_location": null,
	"offered_online": false,
	"offered_in_person": true,
	"member_price": 0,
	"non_member_price": 5,
	"materials_fee": 30,
	"image": "wooden_box_2.jpg",
	"zeffy_link": "https://www.zeffy.com/en-US/ticketing/woodworking--101",
	"cancelled": false,
	"sold_out": false
},

The build.py script uses these variables to build index.html automatically. Post images are stored in /resources/images. You can reference an existing image in your post, or add a new one.

Previewing Posts

To preview your post(s) locally,

1. Modify and save your local version of posts.json
2. Run build.py to update index.html
3. Run python -m http.server (or other similar command) to initialize a local webserver
4. Open http://localhost:8000/ (or similar) in your web browser to preview your changes

Creating a Pull Request

To create a pull request, follow these steps:

1. Create and switch to a new branch for your changes:

git checkout -b your-branch-name

2. Add your modified files to the staging area:

git add posts.json
git add resources/images/your-new-image.jpg  # if you added a new image

3. Commit your changes with a descriptive message:

git commit -m "Add new post for upcoming cider making event"

4. Push your branch to GitHub:

git push origin your-branch-name

5. Visit the Hacksburg website repository on GitHub

6. You should see a prompt to "Compare & pull request" for your recently pushed branch. Click it.

7. Fill out the pull request form:

• Give your PR a descriptive title
• Add any relevant details in the description
• Request review from another board member if needed

8. Click "Create pull request"

Once your pull request is approved and merged, GitHub Actions will automatically rebuild the site with your changes. Your new post should appear on hacksburg.org within a few minutes.

Best Practices

• Always preview your changes locally before creating a pull request
• Use clear, descriptive commit messages
• Include any relevant context in your pull request description
• Make sure images are appropriately sized and optimized before adding them
• Double-check dates, times, and links in your posts
• If you're unsure about any changes, ask another board member to review them

Troubleshooting

If you encounter issues:

• Check the GitHub Actions tab to see if there were any build failures
• Verify your JSON syntax is valid using a tool like JSONLint
• Ensure all required fields in posts.json are properly filled out
• Make sure any new images are committed to the repository
• If you need help, reach out to a board member for assistance