fix: update information in Contributing section (#121)

* fix: update all port references to 8001

* refactor: style command snippets for consistency

* refactor: update some wording for clarity and consistency

* docs: add info on useful `pixi run serve` flags

* fix: correct typo on Conventional Commits title

* refactor: add periods for consistency

* fix: remove weird hanging sentences

* docs: add note to use latest dev version and hyperlinked the site

* refactor: update tense to present

* refactor: capitalize line for consistency

* refactor: add consistent formatting for release-please and mike references

* style: ran linting

docs/contributing/adding_content.md

@@ -52,14 +52,15 @@ $ git checkout -b jjjermiah/adding-getting-started-page
 If you already have a named branch, you can switch to it with the following command:
 
 ```console
-git switch jjjermiah/adding-getting-started-page
+git switch <branch-name>
+$ git switch jjjermiah/adding-getting-started-page
 ```
 
 ### 2. Add your new content to the `docs` directory
 
 ??? question "How do I know where to create my file?"
 
-    This will create an empty Markdown file called `my_new_page.md` in the `docs/onboarding` directory.
+    The command below will create an empty Markdown file called `my_new_page.md` in the `docs/onboarding` directory.
     The relative path to the `docs` directory, will be the link to your new page. <br>
     i.e the link to your new page will be `<website-url>/handbook/onboarding/my_new_page/`
 
@@ -71,27 +72,46 @@ $ touch docs/onboarding/my_new_page.md
 You should now see a new file at `docs/onboarding/my_new_page.md`.
 ```
 
-To learn more about how to actually write content, see the [HandBook MkDocs Page][mkdocs] and
+To learn more about how to actually write content, see the [Handbook MkDocs Page][mkdocs] and
 [Handbook Markdown page][markdown].
 
 ### 3. Preview your changes
 
 The following is a [`pixi task`](https://pixi.sh/latest/features/advanced_tasks/)
-that will start a local server and preview the documentation at `http://localhost:8000`.
+that will start a local server and preview the documentation at `http://localhost:8001` (aka `http://127.0.0.1:8001`).
 
 ```console
 $ pixi run serve
 INFO    -  Building documentation...
 INFO    -  Cleaning site directory
 ...
-INFO    -  [08:55:05] Serving on http://127.0.0.1:8000/handbook/
+INFO    -  [08:55:05] Serving on http://127.0.0.1:8001/handbook/
 ```
 
-You should see your changes appear at `http://127.0.0.1:8000/handbook/onboarding/my_new_page/`
+You should see your changes appear at `http://127.0.0.1:8001/handbook/onboarding/my_new_page/`
+
+!!! tip
+    You can set the handbook website to automatically open in your default
+    browser by using the `-o` flag:
+
+    ```sh
+    pixi run serve -o
+    ```
+
+!!! note "About the port number"
+    By default, we host the local site on port `8001` because it is more likely
+    to be unused and available for the local server to use. In the case that you
+    would like to manually specify a different port (e.g. if it's in use by
+    something else), you can use the `-a` flag after `pixi run serve`.
+
+    For example, to run on port `1234`:
+    ```sh
+    pixi run serve -a localhost:1234
+    ```
 
 ### 4. Commit and push your changes to your branch
 
-```console
+```sh
 git add .
 git commit -m "Add new getting started page"
 git push --set-upstream origin jjjermiah/adding-getting-started-page

docs/contributing/conventional_commits.md

@@ -1,6 +1,6 @@
-# [Convential Commits](#convential-commits)
+# [Conventional Commits](#conventional-commits)
 
-We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps us automate our release process and keep our commit history clean. 
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps us automate our release process and keep our commit history clean.
 
 This style is mandatory for [merging pull requests][modify-the-commit-message-as-needed] on the handbook, but are recommended for all commits.
 
@@ -30,14 +30,13 @@ The `<scope>` of the header is optional and provides context for where the chang
 - `perf`: A code change that improves performance.
 - `test`: Changes to the test framework.
 - `build`: Changes to the build process or tools.
-- `ci`: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
-- `chore`: Other changes that don't modify src or test files
+- `ci`: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
+- `chore`: Other changes that don't modify src or test files.
 
 Other types may be defined per project, but these are the most common.
 
-
 ## Sources
 
 1. [Angular Commit Format Reference Sheet - Brian Clements](https://gist.github.com/brianclements/841ea7bffdb01346392c)
 2. [Origin of Angular Commit Style - AngularJS Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)
-3. [Py-Pkgs tutorial - Automatic version bumping using Angular Commit Style](https://py-pkgs.org/en/latest/development/commit-guidelines.html)
+3. [Py-Pkgs tutorial - Automatic version bumping using Angular Commit Style](https://py-pkgs.org/en/latest/development/commit-guidelines.html)

docs/contributing/merging_pr.md

@@ -27,7 +27,7 @@ This is called a **Merge Commit**.
   <figcaption>Merge commit example</figcaption>
 </figure>
 
-We will be using the **Squash Merge** strategy for merging pull requests.
+We use the **Squash Merge** strategy for merging pull requests to the lab handbook.
 
 Squash merges are a way to combine multiple commits into a single commit.
 Instead of seeing all the author's individual commits in the main branch's
@@ -68,15 +68,20 @@ Feel free to modify the body of the commit message to include only the relevant
 
 !!! note
 
-    Only the PR Title needs to follow the [Conventional Commits][convential-commits] specification.
+    Only the PR Title needs to follow the [Conventional Commits](conventional_commits.md) specification.
     The commit message body can be modified to include any relevant commits.
 
 ![better_pr](images/better_pr_body.png){: style="height:100%;width:100%"}
 
 ### Verify GitHub Pages Deployment
 
 After merging the pull request, the changes will be deployed to GitHub Pages.
-Check the website at `https://bhklab.github.io/handbook/` to verify that the changes are correct.
+Check the website at [`https://bhklab.github.io/handbook/`](https://bhklab.github.io/handbook/)
+to verify that the changes are correct.
+
+!!!note
+    To view the latest merged PR changes, ensure you are on the `dev` version of
+    the site. The version dropdown selector is located next to the site title.
 
 ### Delete the branch
 

docs/contributing/release_deployment.md

@@ -36,10 +36,10 @@ the latest version of the website.
 
 ## Releases and Versioned Documentation
 
-We leverage both [release-please](https://github.com/googleapis/release-please)
-and `mike` to automate the release process and manage versioned documentation,
-making it easier to maintain version control, changelogs, and multiple
-documentation versions.
+We leverage both [`release-please`](https://github.com/googleapis/release-please)
+and [`mike`](https://github.com/jimporter/mike) to automate the release process
+and manage versioned documentation, making it easier to maintain version control,
+changelogs, and multiple documentation versions.
 
 ### How Releases Work
 
@@ -52,7 +52,7 @@ You can view the release automation action at
 
 Key aspects of this combined approach include:
 
-- **Automated Release Creation with release-please**: The tool automatically
+- **Automated Release Creation with `release-please`**: The tool automatically
    generates a release with changelogs and updates the version number based
    on the changes merged into `main`.
 - **Dynamic Pull Request Updates**: If additional changes are pushed to the
@@ -62,14 +62,13 @@ Key aspects of this combined approach include:
 - **Controlled Release Process**: Maintainers can merge changes into the
   release PR only when they are ready to publish a new version, giving them
   full control over the timing of each release.
-- **Versioned Documentation with mike**: Once a new release is prepared,
+- **Versioned Documentation with `mike`**: Once a new release is prepared,
   `mike` is used to manage and deploy versioned documentation. This allows us
   to provide a separate set of documentation for each release, maintaining
   historical versions accessible on the website.
 
 This automated approach ensures consistency, reduces manual effort, and allows
 users to access documentation relevant to any specific version of the project.
-required to manage releases.
 
 ### Manual Release Process
 

docs/contributing/submitting_issues.md

@@ -7,7 +7,7 @@ the documentation, you can submit an issue directly on our GitHub repository.
 We have a set of pre-defined issue templates to help categorize and address
 your concerns efficiently.
 
-link: [Submit and view issues](https://github.com/bhklab/handbook/issues)
+Link: [Submit and view issues](https://github.com/bhklab/handbook/issues)
 
 ## Available Issue Templates
 
@@ -44,7 +44,7 @@ When creating a new issue, you will be presented with the following options:
 
 1. Go to the GitHub repository and navigate to the "Issues" tab.
 2. Click on the "New Issue" button.
-3. Select the appropriate issue template from the list
+3. Select the appropriate issue template from the list.
 4. Fill out the template, providing as much detail as possible to help us
    understand and address your issue.
 5. Submit the issue.
@@ -60,5 +60,3 @@ also select **Open a blank issue** to describe your concern freely.
   section, page, or example, include links and screenshots to provide context.
 - **Suggest Solutions**: If you have an idea on how to fix or improve the
   issue, let us know! Your suggestions can help expedite the process.
-
-Your feedback is invaluable, and we