Merge branch 'master' into 260-named-anchor-fixes

.github/scripts/muffet.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# This script is used in Github Actions to do link checking on commits to branches and master, so
+# please edit with care!  See ../workflows/ci.yml for specific usage.
+#
+# If you're doing local development and want to run link checkers locally, please use this script!
+# You'll need:
+# - install go - https://golang.org/doc/install
+# - install muffet - https://github.com/raviqqe/muffet
+# - make sure muffet is in your PATH
+# - run from root of this repo: ./.github/scripts/muffet.sh
+#
+# If we have errors from this script being too aggressive (see how large downloads on
+# download.docker.com are excluded below) you can add additional sites as needed. Please
+# use extremely granular URLs so as not to exclude more than we need to.
+
+muffet http://localhost:1313 \
+  --buffer-size 50000 \
+  --timeout 35 \
+  --concurrency 2 \
+  --ignore-fragments \
+  --exclude ".*demo\.app\.medicmobile\.org.*" \
+  --exclude ".*download\.docker\.com.*" \
+  --exclude ".*www\.npmjs\.com/org/medic/team/developers" \
+  --exclude "https://github\.com/medic/cht-docs/issues/new.*" \
+  --exclude "https://github\.com/medic/cht-core/issues/new.*" \
+  --exclude "https://github\.com/medic/cht-docs/commit.*" \
+  --exclude "https://github\.com/medic/cht-core/commit.*" \
+  --exclude "https://github\.com/medic/cht-docs/edit/master/.*" \
+  --exclude ".*localhost:5984.*"

.github/workflows/ci.yml

@@ -1,40 +1,72 @@
-name: CHT Documentation Site Build
+# Notes:
+#  - All software installed below is pinned so they don't get upgraded and break w/o us knowing why.
+#  - If you bump one version up to latest, please bump them all so we stay current!
+#  - Hugo builds the site twice: once for link checking and once minified for pushing live
+#  - Bash script for muffet is intentionally stand alone so devs/content editors can easily run it locally
 
-on: 
+on:
   push:
     branches:
-      - master
+      - '*' # branch checking is below so all this is one CI file
 
+name: Test site and push live if we're on Master
 jobs:
-  build:
-
+  BuildLinkCheckPushLive:
+    name:
     runs-on: ubuntu-18.04
-
     steps:
-      - name: Git checkout
+
+      - name: All Branches - Git checkout, including recursive call for Docsy theme
         uses: actions/checkout@v2
         with:
           submodules: recursive  # Fetch the Docsy theme
           fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
 
-      - name: Install Node depencies
-        uses: actions/setup-node@v1
-        with:
-          node-version: '12.x'
-      - run: npm install
-      - run: npm install -g postcss-cli
-      - run: npm i -D autoprefixer
-
-      - name: Setup hugo
+      - name: All Branches - Install hugo extended v0.71.1
         uses: peaceiris/actions-hugo@v2
         with:
           hugo-version: "0.71.1"
           extended: true
 
-      - name: Build
+      # Pinning to current version as of Aug 3, 2020 for stability
+      - name: All Branches - Install Go v1.14
+        uses: actions/setup-go@v2
+        with:
+          go-version: '1.14'
+
+      # Pinning to current version as of Aug 3, 2020 for stability
+      - name: All Branches - Install Muffet v1.3.3
+        run: env GO111MODULE="on" go get github.com/raviqqe/[email protected]
+
+      # run in background so CI doesn't hang waiting for "ctrl + c".  Sleep so hugo server is ready
+      - name: All Branches - Serve Hugo site
+        run: |
+          hugo server&
+          sleep 5
+
+      - name: All Branches - Run Muffet link checker
+        shell: bash
+        run: ./.github/scripts/muffet.sh
+
+      - name: Master Branch Only - Install Node 12.x
+        if: ${{ github.ref == 'refs/heads/master' }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: '12.x'
+
+      - name: Master Branch Only - Install npm modules for hugo build
+        if: ${{github.ref == 'refs/heads/master' }}
+        run: |
+          npm install
+          npm install -g postcss-cli
+          npm i -D autoprefixer
+
+      - name: Master Branch Only - Build for prod with minify
+        if: github.ref == 'refs/heads/master'
         run: env HUGO_ENV="production" hugo --minify
 
-      - name: Deploy
+      - name: Master Branch Only - Deploy to GH pages
+        if: ${{ github.ref == 'refs/heads/master' }}
         uses: peaceiris/actions-gh-pages@v3
         with:
           personal_token: ${{ secrets.DEPOLY_TO_SITE}}
@@ -44,16 +76,14 @@ jobs:
           user_email: medic-ci@github
           publish_branch: master
 
-      - name: Failed Deploy
+      - name: Master Branch Only - Report errors to Slack, if any
+        if: ${{ github.ref == 'refs/heads/master' && failure() }}
         uses: rtCamp/[email protected]
-        if: ${{ failure() }}
         env:
           SLACK_WEBHOOK: '${{ secrets.SLACK_WEB_HOOK }}'
           SLACK_CHANNEL: '#cht-squad-docs'
           SLACK_COLOR: '#3278BD'
           SLACK_ICON: ":flappingphone:"
           SLACK_MESSAGE: 'Deploy Failed'
-          SLACK_TITLE: CHT DOCS  DEPLOY
-          SLACK_USERNAME: Medic-Bot
-
-
+          SLACK_TITLE: CHT DOCS DEPLOY
+          SLACK_USERNAME: Medic-Bot

.gitignore

@@ -5,3 +5,4 @@ node_modules/
 tech-doc-hugo
 
 .DS_Store
+.idea

README.md

@@ -1,10 +1,12 @@
-# Documentation for the Community Health Tookit
+# Documentation for the Community Health Toolkit
+
+[![CHT Documentation Site Build](https://github.com/medic/cht-docs/workflows/CHT%20Documentation%20Site%20Build/badge.svg)](https://github.com/medic/cht-docs/actions)
 
 ## About
 
 This repo contains documentation for the Community Health Toolkit (CHT), and how to build digital health applications with [CHT Core](https://github.com/medic/cht-core).
 
-The documentation is built using Markdown pages, which can be converted into a navigatable 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](https://docs.communityhealthtoolkit.org/contribute/docs/style-guide/).
+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](https://themes.gohugo.io/docsy/). 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/).
 
 ## Installing Hugo
 
@@ -16,15 +18,25 @@ To install, follow the [installation instructions for your Operating System](htt
 
 1. Get local copies of the project submodules so you can build and run your site locally:
    - `git submodule update --init --recursive`
-
-2. Build your site:
+1. Build your site:
    - `hugo server`
    - If there are any errors, check that you have the latest version of Hugo, and are using the extended version.
+1. Preview your site in your browser at: http://localhost:1313/
+1. As you make changes to the site, your browser will automatically reload your local dev site so you can easily and quickly see your changes. 
 
-3. Preview your site in your browser at: http://localhost:1313/
+## Link Checking [Optional]
 
-## Continuous Deployment
+We 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.
 
-All changes to `master` branch run a [GitHub action](.github/workflows/ci.yml) to deploy the documentation site: [docs.communityhealthtoolkit.org](https://docs.communityhealthtoolkit.org)
+  - Install [Go](https://golang.org/doc/install) as a prerequisite 
+  - Install Muffet: `go get -u github.com/raviqqe/muffet`
+  - Ensure you've run `hugo server` so your local docs instance is reachable at http://localhost:1313/
+  - Test the links with the [`muffet.sh`](https://github.com/medic/cht-docs/blob/master/.github/scripts/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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429). Our script intentionally reduces concurrency and excludes some repetitive GitHub URLs.
+
+## Continuous Deployment
 
-![CHT Documentation Site Build](https://github.com/medic/cht-docs/workflows/CHT%20Documentation%20Site%20Build/badge.svg)
+All changes to `master` 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)

content/en/apps/examples/anc.md

@@ -11,22 +11,23 @@ relatedContent: >
 ---
 
 {{% pageinfo %}}
-This "reference application" for maternal and newborn health provides a template for structuring and organizing your Community Health Toolkit digital health app, its configuration and test code. It can be used as is, or serve as a great way to learn about the CHT's foundation for forms, data fields, and analytics that can be easily customized to fit your context.
+This "reference application" for maternal and newborn health provides a template for structuring and organizing your Community Health Toolkit digital health app, its configuration, and test code. It can be used as is, or serve as a great way to learn about the CHT's foundation for forms, data fields, and analytics that can be easily customized to fit your context.
 {{% /pageinfo %}}
 
 ## Problem Being Addressed
 
-Maternal health is the cornerstone of many community health programs. Pregnancy can be a [vulnerable time](https://www.who.int/health-topics/maternal-health) for women living in communities far from medical care. Additionally, the short window immediately after pregnancy is a critical time for catching life-threatening danger signs for the new mother and baby. Newborns that are not delivered at a facility are much [less likely to survive and thrive](https://www.who.int/health-topics/newborn-health).
+Access to quality maternal and newborn care is the cornerstone of many community health programs. For many women living in communities at the last mile, pregnancy can be a [vulnerable time](https://www.who.int/health-topics/maternal-health). There is a need for community health programs to support early pregnancy registration, consistent antenatal care (ANC) visits, and in-facility deliveries. In addition, the short time window following delivery for postnatal care (PNC) is a critical time for catching life-threatening danger signs for the new mother and baby. 
 
 ## Solution Overview
 
-The maternal and newborn health workflows help ensure that women are safe and supported in a timely manner throughout their pregnancy. Early and timely maternal health visits and improved coordination between CHWs and clinics lead to an increase in facility-based deliveries, which in turn has a strong correlation to maternal and newborn survival. Community Health Toolkit applications with maternal and newborn workflows are used by health workers and clinical staff to:
+The maternal and newborn health workflow ensures that women receive the care that they need during their pregnancy with the support of CHWs. Early pregnancy registration, timely antenatal care visits, and improved care coordination between CHWs and clinics increase the likelihood that women will deliver in a facility with the support of skilled birth attendants. This ultimately will help save the lives of mothers and babies, as well as strengthen the maternal and newborn health services of the health system. Community Health Toolkit applications with maternal and newborn workflows are used by health workers and clinical staff to:
 
-- Provide on-time antenatal care visits
-- Educate at each stage of pregnancy
-- Screen and report mother and newborn danger signs
-- Refer and encourage facility delivery
-- Improve delivery rates in facilities with skilled care
+- Register pregnancies
+- Provide a schedule for on-time ANC visits
+- Offer education for the mother at each stage of pregnancy
+- Screen for and report danger signs in the pregnant woman and newborn
+- Refer and encourage pregnant women to deliver at a facility 
+- Ensure on-time PNC visits for mother and newborn
 
 ## Forms Hierarchy
 
@@ -38,7 +39,7 @@ Once a [hierarchy]({{< relref "apps/concepts/hierarchy" >}}) of people and place
 
 ## Workflows
 
-Pregnancy and delivery care workflows are defined to connect form actions and data with people. Detailed documentation for these forms and task schedules are linked from the workflow diagrams below. Accompanying this documentation are tips and insights into the design decisions made along the way, and suggestions for how and where to customize the forms.
+Both maternal and newborn care workflows are defined to connect form actions and data with people. Detailed documentation for these forms and task schedules are linked from the workflow diagrams below. Accompanying this documentation are tips and insights into the design decisions made along the way, and suggestions for how and where to customize the forms.
 
 ### Pregnancy Workflow
 
@@ -100,3 +101,4 @@ Here are a few additional resources to help get you started with the maternal an
 - View the [configuration code for this reference app](https://github.com/medic/cht-core/tree/master/config/default/)
 - Install the reference app following these [easy installation instructions]({{< ref "apps/tutorials/local-setup" >}})
 - Modify the maternal and newborn reference application for your project context using [configuration best practices]({{< ref "design/apps" >}}) 
+- Understand the basis for measuring the impact of maternal and newborn workflows by reviewing the World Health Organization's [Core Health Indicators](https://www.who.int/healthinfo/indicators/2018/en/)

content/en/apps/examples/training.md

@@ -4,7 +4,9 @@ linkTitle: "Remote Training"
 weight: 
 description: >
   App and care workflow training using remote capabilities.
-keywords: training onboarding 
+keywords: training onboarding
+relatedContent: >
+  apps/reference/app-settings/token_login/
 ---
 
 The CHT’s Remote Onboarding and Training functionality enables Supervisors and Administrators to train CHWs on care workflows and related app use without being physically present. It is designed for:
@@ -40,17 +42,19 @@ The CHT’s onboarding and training capabilities offer a remote way to provide e
 
 ### Remote Login by App
 
-When creating users, the admin has the option to send a user their credentials via SMS using a [magic link](https://hackernoon.com/magic-links-d680d410f8f7). This generates a new, random and complex password with a 24-hour expiry. 
+When creating users, the admin has the option to send a user their credentials via SMS using a [magic link](https://hackernoon.com/magic-links-d680d410f8f7). This generates a new, random and complex password with a 24-hour expiry. If no gateway is set up, the message may be sent via another messaging app. 
 
-By clicking the magic link to log in, the user is able to enter their project's instance directly, bypassing the need to enter their username and password. If the app is not installed on their phone, the default SMS encourages users to download it. 
+![admin-magiclink](admin-magiclink.png)
+
+By clicking the magic link to log in, the user is able to enter their project's instance directly, bypassing the need to enter their username and password. If the app is not installed on their phone, it will open in their default browser.
+
+![login.png](login.png)
 
 To recover a password, the user needs to contact the admin so that they may regenerate a new magic link and repeat the workflow. 
 
 {{% alert title="Note" %}}
 The magic link workflow will not work for users who want to use multiple devices or for multiple users on one device.
 {{% /alert %}}
-
-![login.png](login.png)
 
 ### Remote Training Overview
 
@@ -69,5 +73,6 @@ These SMS and App based workflow examples illustrate how the CHT enables remote
 
 {{< youtube pFEFIY_SA7M >}}
 
+<br>
 
 More background information can be found in this [summary deck](https://docs.google.com/presentation/d/13bFoyU2vhwPiOUiVWzUJ2urtAyR6_XKTxp0XASCLVko).

content/en/apps/tutorials/application-settings.md

@@ -1,7 +1,7 @@
 ---
 title: "CHT Application Settings"
 linkTitle: Application Settings
-weight: 1
+weight: 4
 description: >
   Managing CHT application settings
 relatedContent: >

content/en/apps/tutorials/sms-forms.md

@@ -1,7 +1,7 @@
 ---
 title: "Building SMS Forms"
 linkTitle: SMS Forms
-weight: 1
+weight: 5
 description: >
   Building CHT application SMS forms
 relatedContent: >