Skip to content

Working on the Docs

This page is about working with the DDEV documentation. See the Writing Style Guide for stylistic guidance.

Fix Docs Using Web Browser

The documentation is built and checked automatically with various GitHub Actions workflows. While it may help to check your work locally for more involved PRs, you can more quickly make suggestions using GitHub in a browser:

  1. Click the pencil in the upper right. That will take you to the the right page on GitHub.
  2. Click the pencil button on GitHub and follow the instructions to create your change.
  3. Save your changes and follow the prompts to create a PR.
  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.
  5. Once the PR has run its checks, you'll see in the checks that there's a docs/readthedocs.org:ddev check with a link to the docs with your change in them. Follow the link to review what your change actually looks like: _docs__moodle_quickstart_by_ibrah3m_·_Pull_Request__4286_·_drud_ddev
  6. Take a look at the "Check docs" check to make sure that there were no linting or spellcheck errors.

Fork / Clone the DDEV Repository

To start making changes you’ll need a local copy of the DDEV documentation, so fork the DDEV repository which includes the documentation.

After forking the repository, you can clone it to your local machine.

Make Changes

Now that you’ve got a local copy, you can make your changes.

Action Path
Documentation ./docs/content/users/*
./docs/content/developers/*
MkDocs configuration ./mkdocs.yml
Front end ./docs/content/assets/extra.css
./docs/content/assets/extra.js

Preview Changes

Preview your changes locally by running make mkdocs-serve.

This will launch a web server on port 8000 and automatically refresh pages as they’re edited.

No need to install MkDocs locally!

It’s easiest to install install MkDocs locally, 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 documenation. If you don’t have make installed on your system, you can directly run the command it would have instead:

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;

Check Markdown for Errors

Run make markdownlint before you publish changes to quickly check your files for errors or inconsistencies.

markdownlint-cli required!

The make markdownlint command requires you to have markdownlint-cli installed, which you can do by executing npm install -g markdownlint-cli

Check for Spelling Errors

Run make pyspelling to check for spelling errors. Output will be brief if all goes well:

➜  make pyspelling
pyspelling:
Spelling check passed :)

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.

pyspelling and aspell required!

It’s probably best to install packages locally before attempting to run make pyspelling:

sudo -H pip3 install pyspelling pymdown-extensions
sudo apt-get install aspell

Publish Changes

If all looks good, it’s time to commit your changes and make a pull request back into the official DDEV repository.

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.


Last update: October 18, 2022