This repository contains the public-facing Tucson Mesh Documentation website. It is intended to provide interested community members a sort of manual or guidebook discussing how to get involved in the community network from a technical perspective. It is not a networking tutorial, and does assume that readers have some familiarity with basic networking concepts, but we strive to provide external links suggested educational resources for newcomers when it makes sense for us to do so.
The remainder of this document describes the process for contributing to the documentation itself or developing the documentation website.
The best way to start is to make a local copy of the docs website on your development computer. This way, you can experiment safely, without affecting the live site.
To develop locally, you will need:
- a computer with a modern operating system, such as
- an active Internet connection,
- a (free) GitHub.com account,
- basic command-line (terminal/shell) experience. If you have never touched a command line before, consider spending an hour at Codecademy's interactive tutorial, "Learn the Command Line" (for macOS or GNU/Linux users), Computer Hope's article, "How to use the Windows command line (DOS)" (for Windows users), or the Anarcho-Tech NYC Collective's command-line introductory practice lab.
In addition to the prerequisites above, you will need to install the following software on your computer:
- Git - Free and open source distributed version control system. See GitHub's own help article, Set up Git for additional instructions.
- Hugo - One of the most popular open-source static site generators, and the one on which our Documentation website is built. See the Hugo project's documentation for installation instructions specific to your platform.
After you have installed the necessary software on your development computer, you will need to download our website's source code for the first time. Git calls this process "cloning." To clone our repository, use the following command in your terminal or shell:
git clone https://github.com/mackncheesiest/tucsonmesh-docs.git tucsonmesh-docsThe above will create a folder called tucsonmesh-docs that is an exact copy of the code published on our GitHub Organization's repository.
At this point, you should be able to go into the project folder (cd tucsonmesh-docs on your command line) and start the Hugo server:
cd tucsonmesh-docs # Enter the project directory.
hugo server # Start the Hugo development server.If successful, Hugo will print a message that shows you where the development copy of the website is running. This will probably be http://localhost:1313, as that is Hugo's default. Open your Web browser to the address Hugo reports and you will be able to browse a local copy of the documentation website running on your computer.
The source code for this repository contains both the Documentation website's codebase (HTML templates, CSS stylesheets, and more) as well as the documentation content itself. You are welcome to offer your suggestions for improving any and all parts of this website.
Our website codebase generally follows Hugo's content management best practices.
All documentation content is located in the content folder. Each folder inside the content folder is its own section. You can edit existing pages or create new ones by editing or creating files in any of these folders. By default, any changes you make will trigger Hugo to start a live rebuild, so you can see your changes in your browser immediately upon saving the file.
For example, to add a new doc in the Hardware section, create a new file such as content/hardware/awesome-device.md in that section's folder. Begin that file with Hugo front matter to give the new page metadata such as a title:
---
title: "Awesome Device"
---Next, write the content for your new page below the front matter, so that your new file looks something like this:
---
title: "Awesome Device"
---
This awesome device is great because it's so cheap and easy to install!Once you save the file, check out the changes to the local copy of the documentation website in your browser. To learn more about editing content in Hugo, refer to the official Hugo documentation.
🚧 TODO: Better instructions for new contributors would be nice, here.
See the layouts and static folders.
When you are happy with your changes, it is time to send them to the Tucson Mesh Docs team for review. Their job is to ensure that the changes you made are accurate, function well in Tucson Mesh's production environments, and improve the project as a whole. The Tucson Mesh Docs team prefers to receive edits via Pull Requests on GitHub, as this is the process by which we keep track of, review, and merge changes to the docs. If everything looks good, someone will merge your changes in to the main branch, which will update the public docs website.
For more information, please read "Creating a pull request" in the official GitHub documentation.
If you make many good changes, you may be invited to join the documentation project as a contributor. You may also ask us to grant you contributor access in Slack.
As always, if you need any help, don't hesitate to reach out in our Slack group. Invites to our Slack are available here.