Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
kwbunker committed Nov 3, 2024
1 parent 0e15c3b commit d599120
Showing 1 changed file with 24 additions and 6 deletions.
30 changes: 24 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,41 @@
# Electronics Lab Website for CU Boulder Physics

The website is built off of the main branch.
The website is built off of the main branch.

To contribute to the site, you should make a branch. You can then work in/commit to your new branch. When finished, create a pull request for review.
## Contributing to the Site

When you commit, please create helpful messages/descriptions (i.e. "Update Lab1 Prelab").
1. Create a new branch to contribute to the site.
2. Work in and commit to your new branch.
3. When finished, create a pull request for review.

Since GitHub pages will only build off of the main branch, you will need to host the website locally, and develop in your new branch. This can be done by following [this](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll) guide.
When you commit, please create helpful messages/descriptions (e.g., "Update Lab1 Prelab").

## Hosting the Website Locally

Since GitHub Pages will only build off of the main branch, you will need to host the website locally and develop in your new branch. The site is set up to run in a Docker container so all dependencies are consistent across all development environments.

### Prerequisites

- Docker installed on your system.
- VSCode with the Dev Containers extension installed.

### Steps

1. Pull all updates to your local repository.
2. Run `docker-compose build` then `docker-compose up`. You should now have a container running (you can verify in Docker Desktop).
3. Open the local repository folder in VSCode.
4. Press `Ctrl+Shift+P`, and choose "Dev Containers: Attach to Running Container...".
5. Open a web browser and confirm the site is hosted locally by visiting: [http://localhost:4000/PHYS-3330/](http://localhost:4000/PHYS-3330/)

## Editing Lab Guides

The "raw" lab guide markdown files are located in the `raw-content` directory. Jekyll is configured to ignore this directory, as there are additional steps required to generate the content for the site (discussed below). The files in the `raw-content` directory are what should be edited (not the html files in the `_includes` directory).

The html files in the `_includes` directory are generated by running the `raw-content\mdtohtml.ps1` script. This script requires pandoc and pandoc-xnos to be installed on your system in order to run.
The html files in the `_includes` directory are generated by running the `raw-content\mdtohtml.sh` script.

## New Lab Guide Development

The lab guide files, `raw-content\labX-raw.md,` $X=1,2,...,10$, are the "live" guides that are linked to on the website. So don't edit these unless we need to make a typo change, etc. For new lab guides (or for developing new versions), follow the "old/new" naming convention that currently exists.




0 comments on commit d599120

Please sign in to comment.