To make edits to docs locally, you'll need to have a GitHub account and be listed as a contributor to the
phillycommunitywireless/docs repository. You'll also need
git and a markdown editor of your choice.
Clone the repo
First things first: if you haven't already done so copy the docs repository to your local machine:
git clone https://github.com/phillycommunitywireless/docs.git cd docs
If you already have the repo cloned, you should pull any new changes to synchronize with the remote repo:
Edit markdown files
You should see several markdown files in the
docs/docs subfolder. These correspond to the pages on the main site. You can open and edit these files in a markdown editor of your choice!
Finalizing your changes
Once you're confident in the changes you've made to the docs, you can push them back to the remote repo. ReadTheDocs will be notified of these changes and immediately rebuild the public site with your changes reflected.
git add . git commit -m "Add a message specifying what you changed" git push
If this is your first time pushing, you may need to run this instead:
git push --set-upstream origin main
Adding new files
If you just add a new
.md doc to the
docs folder, you won't see it immediately reflected on the live site. To add it, you'll need to add it to the site nav configuration, which is set in the
mkdocs.yml file at the root of the project.
# /mkdocs.yml nav: - Home: index.md - Mesh Kit Setup Guide: mesh-kit/mesh-kit.md - Hardware: hardware.md - Onboarding: onboarding.md - Editing these docs: edit-docs.md
- Your New Page: new-page.md
Running a local version of the docs site
This is only necessary if you need to see how the docs are specifically rendered on our live site. Any markdown editor should be able to preview the docs as they will appear on the site, without much deviation. If you want to make styling / structural changes to the site and/or its theme, this is also the way to do that.
First, clone the repo.
Run a local server with Docker
- Download Docker, which should include Docker Compose on most machines.
docker-compose upinside the project directory.
- The mkdocs server will start up, and can be accessed at
localhost:8000. Any changes made to the docs will automatically update the page.
Optional: Setup Python Environment
If you need your development environment to integrate with other programs on your machine, e.g. for linting in a text editor, you'll need to set up a Python virtual environment with the necessary dependencies installed.
First, make sure you have Python 3 and
pip installed, and run the following commands:
# install the pipenv package pip install pipenv # create a virtual environment and install dependencies in it pipenv install -r requirements.txt
Your dependencies are now installed in a virtual environment (usually located somewhere in your $HOME/.local/ folder). To active the environment on the command line, type
pipenv shell. If you're using Visual Studio Code for editing, change the Python Interpreter setting to point to the path returned by
pipenv which python.