This repo contains documentation for the Community Health Toolkit (CHT), and how to build digital health applications with CHT Core. This repository powers the CHT documentation site at docs.communityhealthtoolkit.org.
The documentation is built using Markdown pages, which can be converted into a navigable website using a static-site-generator. The Hugo static-site-generator is being used with the Docsy theme. To maintain portability, content should be written in plain Markdown with limited use of HTML, custom shortcodes, and modifications to the theme. Contributions should align with the documentation style guide.
The documentation site uses Hugo including the extended version of Hugo (see .tool-versions
file for specific version).
To proceed, please choose one of the three options below of Docker, native packages or using asdf
then proceed to "Run Hugo" below to start your local instance.
For folks using asdf
and native packages, be sure the correct hugo
version is installed per .tool-versions
file.
Running hugo
locally using Docker is likely the easiest way to update the docs. You only need to ensure you have Docker and Docker compose installed.
The steps below will leave a hugo container on your system. If you're not going to edit docs for the foreseeable future, you can delete it with docker rm cht-hugo
.
If you'd like to install packages directly on your workstation, follow the installation instructions for your Operating System, and be sure to get the extended version. Most users will be able to simply install using their native package manager like brew
, apt
or snap
.
asdf
version managerasdf is another way to manage hugo
and golang
versions for local development.
After installing asdf
, run:
asdf plugin add golang
asdf plugin add hugo
You can start your local CHT Docs instance by:
cht-docs
repohugo
run:
hugo server
for asdf
and native packages ORdocker compose up
for Docker composeAny users who experience errors running hugo server
, please see our Troubleshooting guide.
We validate that all links on the docs site work (do not 404) using a tool called Muffet along with Actions. If you're creating a lot of new links, or editing a lot of existing links, you may optionally run Muffet locally before pushing your commits. Running Muffet locally can save time by exposing broken links before pushing a build since you can avoid waiting for the Action to run, finding you have a broken link, fixing it, and pushing a new change.
go get -u github.com/raviqqe/muffet
asdf
you need to reshim (asdf reshim golang
)hugo server
so your local docs instance is reachable at http://localhost:1313/muffet.sh
script. If you're in the root of this repo, that'd be: ./.github/scripts/muffet.sh
It should take about 60 seconds depending on your Internet connection. If Muffet returns no output, you have no broken links, congrats!
Note: The muffet.sh
script here is the identical script we run on GitHub. If you simply run muffet http://localhost:1313
you will hit GitHub's rate limiting and get lots of 429's. Our script intentionally reduces concurrency and excludes some repetitive GitHub URLs.
All changes to main
branch run a GitHub action to first check for any broken links (per above) and then deploy to the documentation site: docs.communityhealthtoolkit.org
The version of Hugo used to deploy the site is specified in .tool-versions
.
(Note there is also a minimum version of Hugo required to deploy the site specified via module.hugoVersion
in the config.toml
file.)
See the Hugo Release Notes for documentation regarding what has changed in the new versions.
The current version of Docsy is pinned in the go.mod
file. To upgrade to a new version of Docsy, use the hugo mod get
command as described in the Docsy documentation.
See the Docsy CHANGELOG for documentation regarding what has changed in the new versions.