{"id":20301887,"url":"https://github.com/medic/cht-docs","last_synced_at":"2025-09-23T20:20:31.888Z","repository":{"id":37075686,"uuid":"261618856","full_name":"medic/cht-docs","owner":"medic","description":"Documentation site for the Community Health Tookit","archived":false,"fork":false,"pushed_at":"2025-09-22T22:25:25.000Z","size":136453,"stargazers_count":14,"open_issues_count":145,"forks_count":40,"subscribers_count":39,"default_branch":"main","last_synced_at":"2025-09-22T22:25:53.446Z","etag":null,"topics":["cht","documentation","health"],"latest_commit_sha":null,"homepage":"https://docs.communityhealthtoolkit.org","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/medic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"medic","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-05-06T01:06:04.000Z","updated_at":"2025-09-22T22:25:29.000Z","dependencies_parsed_at":"2023-10-22T23:30:07.240Z","dependency_job_id":"a759bd33-9911-44bb-a39f-fd957181f8c9","html_url":"https://github.com/medic/cht-docs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/medic/cht-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/medic","download_url":"https://codeload.github.com/medic/cht-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276641414,"owners_count":25678541,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cht","documentation","health"],"created_at":"2024-11-14T16:28:09.785Z","updated_at":"2025-09-23T20:20:31.764Z","avatar_url":"https://github.com/medic.png","language":"HTML","funding_links":["https://github.com/sponsors/medic"],"categories":[],"sub_categories":[],"readme":"# Documentation for the Community Health Toolkit\n\n[![CHT Documentation Site Build](https://github.com/medic/cht-docs/workflows/CHT%20Documentation%20Site%20Build/badge.svg)](https://github.com/medic/cht-docs/actions)\n\n## About\n\nThis repo contains documentation for the Community Health Toolkit (CHT), including how to build digital health applications with [CHT Core](https://github.com/medic/cht-core). This repository powers the CHT documentation site at [docs.communityhealthtoolkit.org](https://docs.communityhealthtoolkit.org).\n\nThe 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 [Hextra theme](https://themes.gohugo.io/themes/hextra/). 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](https://docs.communityhealthtoolkit.org/contribute/docs/style-guide/).\n\n## Build dependencies\n\nThe documentation site uses [Hugo](https://gohugo.io/) including the extended version of Hugo (see `.tool-versions` [file](https://github.com/medic/cht-docs/blob/main/.tool-versions) for specific version).\n\nTo proceed, choose one of the three options below of Docker, native packages or using `asdf` then proceed to [\"Run Hugo\" below](#run-hugo) to start your local instance.\n\nFor folks using `asdf` and native packages, be sure the correct `hugo` version is installed per `.tool-versions` [file](https://github.com/medic/cht-docs/blob/main/.tool-versions).\n\n### Docker\n\nRunning `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](https://docs.docker.com/compose/install/).\n\nThe 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 `.\n\n### Native packages\n\nIf you'd like to install packages directly on your workstation, follow the [installation instructions for your Operating System](https://gohugo.io/getting-started/installing/), 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`.\n\n### `asdf` version manager\n\n[asdf](https://asdf-vm.com/guide/getting-started.html) is another way to manage `hugo` and `golang` versions for local development.\n\nAfter installing `asdf`, run:\n```shell\nasdf plugin add golang\nasdf plugin add hugo\n```\n\n### Run Hugo\n\nYou can start your local CHT Docs instance by:\n\n1. Clone the `cht-docs` repo\n2. From the command line, navigate to the local directory where you cloned the repo\n3. To start `hugo` run:\n   * `hugo server` for `asdf` and native packages **OR**\n   * `docker compose up` for Docker compose\n4. Preview your site in your browser at: http://localhost:1313/\n5. As you make changes to the site, your browser will automatically reload your changes.\n\nAny users who experience errors running `hugo server`, please see our [Troubleshooting guide](./troubleshooting.md).\n\n## Link Checking [Optional]\n\nWe have two types of link checking:\n\n* All links - tests all links within docs and outbound\n* Internal links - takes all internal links from [production site](https://docs.communityhealthtoolkit.org/) and tests them on your branch\n\n### All links, including outbound \n\nWe validate that all links on the docs site work (do not 404) using a tool called [Muffet](https://github.com/raviqqe/muffet) along with [Actions](https://github.com/features/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.\n\n#### Running\n\n1. Start the docker container: `docker compose up -d`\n2. Test the links with the [`muffet.sh`](https://github.com/medic/cht-docs/blob/main/.github/scripts/muffet.sh) script: `docker exec cht-hugo sh -c \"cd .github/scripts/; ./muffet.sh\"`\n  \nIt can take many minutes depending on your Internet connection. If Muffet returns no output, you have no broken links, congrats! \n\n\u003e [!NOTE] \n\u003e 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429). Our script intentionally reduces concurrency and excludes some repetitive GitHub URLs.\n\n#### Example\n\nNote that you may see transient errors as shown here with lookup errors:\n\n\n```shell\n$ docker exec  cht-hugo sh -c \"cd .github/scripts/; ./muffet.sh\" \n\nhttp://localhost:1313/hosting/4.x/production/docker/adding-tls-certificates/\n        lookup letsencrypt.org: i/o timeout     https://letsencrypt.org/\nhttp://localhost:1313/technical-overview/concepts/offline-first/\n        lookup blog.couchdb.org: i/o timeout    https://blog.couchdb.org/2017/09/19/couchdb-takes-medic-mobile-to-the-front-lines-of-healthcare-work/\nhttp://localhost:1313/hosting/monitoring/production/\n        lookup letsencrypt.org: i/o timeout     https://letsencrypt.org/\nhttp://localhost:1313/building/forms/app/\n        lookup www.w3.org: i/o timeout  https://www.w3.org/TR/1999/REC-xpath-19991116/ \n```\n\n### Internal links after major re-organization\n\nIf you're moving more than ~5 pages around, you should check that they either correctly redirect with the `aliases` [feature](https://hugo-docs.netlify.app/en/content-management/urls/#aliases) or 404 if the page is indeed removed with no replacement.  There's a script that will get all the URLs from the [production site](https://docs.communityhealthtoolkit.org/) and then check your branch for the result of every URL.  If it gets a `200` with no redirect, nothing is shown.  All other results, like `404` or a `200` which results in a redirect are shown.\n\nThis is mainly to help preserve SEO and to help folks who bookmark specific pages.  \n\n#### Running\n\n1. Make your changes, for example moving 10s of pages to a new location\n2. Check that `hugo` compiles and doesn't complain of any broken links\n3. Start the docker container: `docker compose up -d`\n4. Test the links with the bash script: `docker exec cht-hugo .github/scripts/check.urls.sh`\n\n#### Example\n\n```shell\n$ docker exec  cht-hugo .github/scripts/check.urls.sh           \n\nAre you on a test branch and is hugo running on http://localhost:1313 ?\n\nFetching URLs from production.\n\nChecking 435 URLs, be patient.  Any non 200 URLs will be listed here:\n\nSuccessfully checked 435 URLs!\n```\n\n## Continuous Deployment\n\nAll changes to `main` branch run a [GitHub action](.github/workflows/ci.yml) to first check for any broken links ([per above](#link-checking-optional)) and then deploy to the documentation site: [docs.communityhealthtoolkit.org](https://docs.communityhealthtoolkit.org)\n\n## Upgrading dependencies\n\n### Hugo\n\nThe version of Hugo used to deploy the site is specified in `.tool-versions`. \n\n\u003e [!NOTE] \n\u003e Note there is also a minimum version of Hugo required to deploy the site specified via `module.hugoVersion` in the [`hugo.toml`](./hugo.toml) file.\n\nSee the [Hugo Release Notes](https://github.com/gohugoio/hugo/releases) for documentation regarding what has changed in the new versions.\n\n### Hextra\n\nThe current version of Hextra is pinned in the [`go.mod`](./go.mod) file. See the [Hextra Releases](https://github.com/imfing/hextra/releases) for documentation regarding what has changed in the new versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedic%2Fcht-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmedic%2Fcht-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedic%2Fcht-docs/lists"}