github.com/ddev/ddev@v1.23.2-0.20240519125000-d824ffe36ff3/docs/content/developers/testing-docs.md (about)

     1  ---
     2  search:
     3    boost: .5
     4  ---
     5  # Working on the Docs
     6  
     7  This page is about working with the DDEV documentation. See the [Writing Style Guide](writing-style-guide.md) for stylistic guidance.
     8  
     9  ## Fix Docs Using Web Browser
    10  
    11  The documentation is built and checked automatically with various [GitHub Actions workflows](https://github.com/ddev/ddev/actions). While it may help to [check your work locally](#fork-or-clone-the-ddev-repository) for more involved PRs, you can more quickly make suggestions using GitHub in a browser:
    12  
    13  1. Click the pencil in the upper right. That will take you to the right page on GitHub.
    14  2. Click the pencil button on GitHub and follow the instructions to create your change.
    15  3. Save your changes and follow the prompts to create a PR.
    16  4. In the checks on your PR, click the “details” link by `docs/readthedocs.org:ddev` to browse the docs build created by your PR.
    17  5. Once the PR has run its checks, you’ll see an item labeled `docs/readthedocs.org:ddev`. Click “Details” to review a docs build that includes your changes:
    18      ![Documentation preview build link](../images/docs-build-link.png)
    19  6. Take a look at the [“Check docs” action](https://github.com/ddev/ddev/actions/workflows/docscheck.yml) to make sure there were no linting or spelling errors.
    20  
    21  ## Fork or Clone the DDEV Repository
    22  
    23  To start making changes you’ll need a local copy of the DDEV documentation, so [fork the DDEV repository](https://github.com/ddev/ddev/fork) which includes the documentation.
    24  
    25  After forking the repository, you can clone it to your local machine.
    26  
    27  ## Make Changes
    28  
    29  Now that you’ve got a local copy, you can make your changes.
    30  
    31  | Action               | Path                                                                    |
    32  |----------------------|-------------------------------------------------------------------------|
    33  | Documentation        | `./docs/content/users/*` <br> `./docs/content/developers/*`             |
    34  | MkDocs configuration | `./mkdocs.yml`                                                          |
    35  | Front end            | `./docs/content/assets/extra.css` <br> `./docs/content/assets/extra.js` |
    36  
    37  ## Preview Changes
    38  
    39  Preview your changes locally by running `make mkdocs-serve`.
    40  
    41  This will launch a web server on port 8000 and automatically refresh pages as they’re edited.
    42  
    43  !!!tip "No need to install MkDocs locally!"
    44      It’s easiest to [install MkDocs locally](https://www.mkdocs.org/user-guide/installation/), but you don’t have to. The `make mkdocs-serve` command will look for and use a local binary, otherwise using `make` to build and serve the documentation. If you don’t have `make` installed on your system, you can directly run the command it would have instead:
    45  
    46      ```
    47      TAG=$(arch)
    48      if [ "${TAG}" = "arm64" ]; then TAG="${TAG}v8-1.5.2"; else TAG=1.5.2; fi
    49      docker run -it -p 8000:8000 -v "${PWD}:/docs" -e "ADD_MODULES=mkdocs-material mkdocs-redirects mkdocs-minify-plugin mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin" -e "LIVE_RELOAD_SUPPORT=true" -e "FAST_MODE=true" -e "DOCS_DIRECTORY=./docs" "polinux/mkdocs:$TAG"
    50      ```
    51  
    52  !!!tip "Installing mkdocs locally on macOS"
    53      On macOS with recent versions of Homebrew use this technique to install mkdocs:
    54  
    55      ```bash
    56      brew install pipx
    57      export PIPX_BIN_DIR=/usr/local/bin
    58      pipx install mkdocs
    59      pipx runpip mkdocs install -r docs/mkdocs-pip-requirements
    60      pipx ensurepath
    61      ```
    62  
    63  ## Check Markdown for Errors
    64  
    65  Run `make markdownlint` before you publish changes to quickly check your files for errors or inconsistencies.
    66  
    67  !!!warning "`markdownlint-cli` required!"
    68      The `make markdownlint` command requires you to have `markdownlint-cli` installed, which you can do by executing `npm install -g markdownlint-cli`
    69  
    70  ## Check for Spelling Errors
    71  
    72  Run `make pyspelling` to check for spelling errors. Output will be brief if all goes well:
    73  
    74  ```
    75  ➜  make pyspelling
    76  pyspelling:
    77  Spelling check passed :)
    78  ```
    79  
    80  If you’ve added a correctly-spelled word that gets flagged, like “Symfony” for example, you’ll need to add it to `.spellcheckwordlist.txt` in the [root of DDEV’s repository](https://github.com/ddev/ddev/blob/master/.spellcheckwordlist.txt).
    81  
    82  !!!warning "`pyspelling` and `aspell` required!"
    83      It’s probably best to install packages locally before attempting to run `make pyspelling`:
    84  
    85      ```
    86      sudo -H pip3 install pyspelling pymdown-extensions
    87      sudo apt-get install aspell
    88      ```
    89  
    90  ## Publish Changes
    91  
    92  If all looks good, it’s time to commit your changes and make a pull request back into the official DDEV repository.
    93  
    94  When you make a pull request, several tasks and test actions will be run. One of those is a task named `docs/readthedocs.org:ddev`, which builds a version of the docs containing all the changes from your pull request. You can use that to confirm the final result is exactly what you’d expect.