Docs: Build in strict mode

.github/workflows/docs.yml

@@ -27,7 +27,7 @@ jobs:
           pip install -r requirements/docs.txt
 
       - name: Build docs
-        run: mkdocs build
+        run: mkdocs build --strict
 
       - name: Publish docs
         run: mkdocs gh-deploy

docs/atomic-structure.md

@@ -11,7 +11,7 @@ If a component doesn’t have user interactions or require styling,
 then it won’t have an associated JS and/or Less file.
 Components that are available for adding to a Wagtail page also
 require some Python programming—see the
-[creating and editing components](../editing-components/) page for details.
+[creating and editing components](editing-components.md) page for details.
 
 We compose our atomic components as follows:
 

docs/contributing-docs.md

@@ -44,7 +44,7 @@ nav:
 ## Running the docs locally
 
 With a
-[stand-alone Python virtualenv for consumerfinance.gov](../installation/#set-up-a-local-python-environment-optional):
+[stand-alone Python virtualenv for consumerfinance.gov](installation.md#set-up-a-local-python-environment-optional):
 
 ```bash
 pyenv activate consumerfinance.gov
@@ -59,7 +59,7 @@ Once running, they are accessible at http://localhost:8888.
 Every time a PR is merged to main,
 GitHub Actions will build and deploy the documentation to
 https://cfpb.github.io/consumerfinance.gov/.
-See [How we use GitHub Actions](../github-actions/) for more info.
+See [How we use GitHub Actions](github-actions.md) for more info.
 
 If you would like to deploy to a fork of consumerfinance.gov owned by another user
 you can provide the `-r` argument:

docs/editing-components.md

@@ -46,7 +46,7 @@ Blocks are implemented via several different bits of code:
 1. [(Optionally) adding some JavaScript for adding advanced behavior](#adding-javascript)
 
 Before you dive in further,
-[check out the Notes on Atomic Design page](../atomic-structure/)
+[check out the Notes on Atomic Design page](atomic-structure.md)
 and familiarize yourself with our basic concepts
 of atoms, molecules, and organisms.
 
@@ -179,7 +179,7 @@ but in the footer on others) on the sidebar tab.
 ### The front end
 
 Before diving into the front-end code, a reminder to
-visit the [Notes on Atomic Design](../atomic-structure/) page
+visit the [Notes on Atomic Design](atomic-structure.md) page
 to learn about how we conceive of components in a hierarchy
 of atoms, molecules, and organisms.
 
@@ -268,7 +268,7 @@ you can add it by creating a new
       Also be sure that new component designs have gone through
       our internal approval process before adding them to the project.
 
-If you're working on a general-purpose [atomic component](../atomic-structure/)
+If you're working on a general-purpose [atomic component](atomic-structure.md)
 for site-wide use, this file should live in
 `cfgov/unprocessed/css/<atoms|molecules|organisms>/`.
 (Choose the deepest folder according to the atomic rank of the component.)
@@ -311,7 +311,7 @@ class RelatedContent(blocks.StructBlock):
 
 (The `related-content.js` file would need to be placed in
 `cfgov/unprocessed/js/molecules/`;
-see [Notes on Atomic Design](../atomic-structure/).)
+see [Notes on Atomic Design](atomic-structure.md).)
 
 This will load the `related-content.js` script on any page
 that includes the `RelatedContent` molecule in one of its StreamFields.
@@ -320,7 +320,7 @@ that includes the `RelatedContent` molecule in one of its StreamFields.
 
 ### Creating a new component
 
-1. Review the [Notes on Atomic Design](../atomic-structure/) page.
+1. Review the [Notes on Atomic Design](atomic-structure.md) page.
 1. Add each of the parts mentioned above:
    1. [Create the Python class](#the-python-class)
    1. [Add the class to a StreamField](#adding-it-to-a-streamfield)
@@ -457,4 +457,4 @@ experience a gap in the data that is being manually replaced.
 ---
 
 For more details on both kinds of migrations,
-see [the Wagtail Migrations page](../migrations/).
+see [the Wagtail Migrations page](migrations.md).

docs/github-actions.md

@@ -28,6 +28,6 @@ Our workflows are defined in our [`.github/workflows`](https://github.com/cfpb/c
 
 ## An extra task for satellite repositories
 
-For our [satellite apps](../related-projects/#satellite-apps), we use GitHub Actions (or Travis, if a repo hasn't been migrated to Actions yet) to build and attach a deployment wheel file to every release.
+For our [satellite apps](related-projects.md#satellite-apps), we use GitHub Actions (or Travis, if a repo hasn't been migrated to Actions yet) to build and attach a deployment wheel file to every release.
 
 An example is the `.whl` file on [this release of the retirement app](https://github.com/cfpb/retirement/releases/tag/0.7.6).

docs/installation.md

@@ -28,7 +28,7 @@ The Wagtail admin area will be available at <http://localhost:8000/admin/>,
 which you can log into with the credentials `admin`/`admin`.
 
 Please see
-our [running consumerfinance.gov](/running/) documentation
+our [running consumerfinance.gov](running-virtualenv.md) documentation
 for next steps.
 
 There are also optional steps described below, as well as
@@ -69,7 +69,7 @@ cp -a .env_SAMPLE .env
 ### Set up a local Python environment (optional)
 
 For running our
-[Python unit tests, linting, etc](/python-unit-tests/)
+[Python unit tests, linting, etc](python-unit-tests.md)
 outside of the Docker container, we rely on a local Python environment.
 
 !!! note
@@ -185,7 +185,7 @@ to assist developers with linting without thinking.
 
 We have a single script that will install our frontend dependencies for both
 building and
-[unit testing/linting/etc](/javascript-unit-tests/):
+[unit testing/linting/etc](javascript-unit-tests.md):
 
 ```sh
 ./frontend.sh
@@ -279,7 +279,7 @@ CFGOV_PROD_DB_LOCATION=http://(rest of the URL)
 ./refresh-data.sh /path/to/dump.sql.gz
 ```
 
-This automatically [(re)builds the Elasticsearch index](/search/#building-the-index),
+This automatically [(re)builds the Elasticsearch index](page-search.md#building-the-index),
 unless you run the `refresh-data.sh` script with the `--noindex` flag.
 
 ## Alternative setups

docs/javascript-unit-tests.md

@@ -143,7 +143,7 @@ the structure of the project JavaScript in
 
 When considering exactly where to place JavaScript in these directories,
 it might be helpful to review the documentation about
-[atomic components in consumerfinance.gov](../atomic-structure).
+[atomic components in consumerfinance.gov](atomic-structure.md).
 JavaScript corresponding to atomic elements should go into
 the appropriate subfolder for the type of element being implemented.
 In our case, `sample.js` and `sample-spec.js` don’t relate to atomic elements,
@@ -586,7 +586,7 @@ and assigns the component node to the `notificationElem` variable, and
     the tests would have to reconcile
     into a complete, finished chunk of markup.
     For now, just be aware of this when
-    [editing a Wagtail component that includes JavaScript](../editing-components/).
+    [editing a Wagtail component that includes JavaScript](editing-components.md).
 
 Further down, here are some of the tests that cover the `_setType` function
 (by way of the `setTypeAndContent` function that
@@ -642,4 +642,4 @@ Testing user interaction with simulated pointer events, keystrokes,
 or form submissions is best handled via browser tests, not unit tests.
 User interaction in a unit test could falsely pass
 if the component wasn’t visible on the page, for instance.
-[Read more about how we run browser tests with Cypress.](../functional-testing/)
+[Read more about how we run browser tests with Cypress.](functional-testing.md)

docs/migrations.md

@@ -105,7 +105,7 @@ and the time that your PR is ready for merging,
 you will have to update your branch as normal to be current with main
 and then re-create your migration.
 Also note that our
-[back-end tests that run in GitHub Actions](../github-actions/)
+[back-end tests that run in GitHub Actions](github-actions.md)
 will fail if a required schema migration is missing or if
 migrations are in conflict with one another.
 

docs/page-search.md

@@ -15,7 +15,7 @@ For page searches on consumerfinance.gov, we use Elasticsearch and the [django-o
 
 ## Indexing
 
-For any of our Django apps that need to implement search for their Django models or [Wagtail page types](../wagtail-pages/), we include a `documents.py` file that defines the Elasticsearch documents that will [map the model or page to the Elasticsearch index](https://django-opensearch-dsl.readthedocs.io/en/latest/getting_started/#create-document-classes).
+For any of our Django apps that need to implement search for their Django models or [Wagtail page types](wagtail-pages.md), we include a `documents.py` file that defines the Elasticsearch documents that will [map the model or page to the Elasticsearch index](https://django-opensearch-dsl.readthedocs.io/en/latest/getting_started/#create-document-classes).
 
 The `Document` class includes three things:
 

docs/python-unit-tests.md

@@ -35,9 +35,9 @@ for additional details on its functionality.
 ## Prerequisites
 
 If you have set up
-[a standalone installation of consumerfinance.gov](/installation/#install-system-level-requirements),
+[a standalone installation of consumerfinance.gov](installation.md#install-system-level-requirements),
 you'll need to
-[activate your virtual environment](/running-virtualenv/#3-launch-site)
+[activate your virtual environment](running-virtualenv.md#3-launch-site)
 before running the tests:
 
 ```sh
@@ -53,7 +53,7 @@ pip install tox
 ```
 
 If you have set up
-[a Docker-based installation of consumerfinance.gov](/installation/#docker-based-installation),
+[a Docker-based installation of consumerfinance.gov](installation.md#docker-based-installation),
 you can run the tests there by
 [accessing the Python container's shell](http://localhost:8888/running-docker/#access-a-containers-shell):
 
@@ -188,7 +188,7 @@ TEST_RUNNER=core.testutils.runners.StdoutCapturingTestRunner tox -e unittest
 ```
 
 This test runner is enabled when tests are run automatically on
-[GitHub Actions](../github-actions/),
+[GitHub Actions](github-actions.md),
 but is not used by default when running tests locally.
 
 ## GovDelivery

docs/related-projects.md

@@ -48,7 +48,7 @@ contains the CFPB development guidelines used on these projects.
 Developers working on changes to satellite apps or other Python packages often
 want or need to test their work as part of the larger consumerfinance.gov project.
 
-The standard [installation](../installation/) process for consumerfinance.gov
+The standard [installation](installation.md) process for consumerfinance.gov
 includes whatever versions of these packages are specified in project
 [requirements files](https://github.com/cfpb/consumerfinance.gov/blob/main/requirements/libraries.txt).
 Developers may want to temporarily or permanently replace those with a local
@@ -104,13 +104,13 @@ requirements files:
 ```
 
 Re-running the full virtual environment
-[setup script](../installation/#run-the-setup-script)
+[setup script](installation.md#run-the-setup-script)
 will do the same thing.
 
 ### Using Docker
 
 Working on Python packages requires a different approach when running
-consumerfinance.gov locally with [its Docker setup](../running-docker/).
+consumerfinance.gov locally with [its Docker setup](running-docker.md).
 This is because while your local `consumerfinance.gov` directory is exposed to the
 container, sibling directories or other locations where you might clone
 other repositories are not.

docs/running-docker.md

@@ -1,7 +1,7 @@
 # Running in Docker
 
 First, follow
-[the Docker installation instructions](../installation/#docker-based-installation)
+[the Docker installation instructions](installation.md#docker-based-installation)
 to setup your Docker environment and create the project Docker containers.
 
 We use [`docker-compose`](https://docs.docker.com/compose/reference/overview/)
@@ -82,7 +82,7 @@ docker-compose up --build python
 
 ## Work on satellite apps
 
-See [“Using Docker” on the Related Projects page](../related-projects/#using-docker).
+See [“Using Docker” on the Related Projects page](related-projects.md#using-docker).
 
 ## Attach for debugging
 

docs/running-virtualenv.md

@@ -1,7 +1,7 @@
 # Running in a Virtual Environment
 
 First, follow
-[the standalone installation instructions](../installation/#stand-alone-installation)
+[the standalone installation instructions](installation.md#stand-alone-installation)
 to create your virtual environment, install required dependencies, and run
 the setup scripts.
 
@@ -137,7 +137,7 @@ yarn test                # Run both
 ### Reinstalling the virtual environment
 
 To remove an existing virtual environment for
-[a reinstall of consumerfinance.gov](../installation/#stand-alone-installation),
+[a reinstall of consumerfinance.gov](installation.md#stand-alone-installation),
 first deactivate the virtual environment if it is active:
 
 ```bash
@@ -151,5 +151,5 @@ rmvirtualenv consumerfinance.gov
 ```
 
 After this, you may follow
-[the installation instructions](installation/#stand-alone-installation)
+[the installation instructions](installation.md#stand-alone-installation)
 again.

mkdocs.yml

@@ -57,3 +57,8 @@ markdown_extensions:
   - tables
   - toc:
       permalink: '¶'
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn