DDEV Drupal contrib MkDocs add-on

A DDEV add-on for building and previewing MkDocs documentation in Drupal contrib module and theme projects.

Run DDEV from the extension root (where the .info.yml file lives). MkDocs uses the standard layout: mkdocs.yml at the project root and Markdown sources in docs/.

Getting started

For DDEV v1.23.5 or above:

ddev add-on get s-ayers/ddev-drupal-contrib-mkdocs

For earlier versions of DDEV:

ddev get s-ayers/ddev-drupal-contrib-mkdocs

Restart the project:

ddev restart

Project layout

After install (only missing files are created):

my_module/
├── mkdocs.yml          # MkDocs config (not overwritten if present)
├── docs/
│   └── index.md        # Home page (not overwritten if present)
└── .ddev/
    └── mkdocs/
        └── mkdocs.yml  # Add-on template copy

The add-on does not create a nested docs/docs/ directory. It never overwrites an existing mkdocs.yml or docs/index.md.

If you previously used a layout with docs/mkdocs.yml and content under docs/docs/, move mkdocs.yml to the project root and your Markdown files into docs/ manually.

Using MkDocs

The service uses MkDocs Material with PHP syntax highlighting suitable for Drupal code samples.

ddev mkdocs build

View the site at https://docs.<project_name>.ddev.site (HTTPS) or http://docs.<project_name>.ddev.site (HTTP), where <project_name> is your DDEV sitename. If DDEV uses alternate router ports because 80/443 are busy (see port conflict), append the port the same way as the main site, e.g. https://docs.<project_name>.ddev.site:33001. Run ddev describe for the authoritative URLs. The add-on registers docs.<sitename> in additional_hostnames on install.

The mkdocs service runs mkdocs serve with live reload. After you change Markdown under docs/, the site should rebuild and the browser should refresh. If it does not, run ddev logs -s mkdocs while saving a file; you should see a rebuild. On Docker Desktop for Mac, WATCHDOG_FORCE_POLLING=true is set to improve file watching across the bind mount.

Configuration

The MkDocs container mounts the project root ($DDEV_APPROOT), so mkdocs.yml and the docs/ folder resolve as MkDocs expects. Change the mount or working_dir in docker-compose.mkdocs.yaml only if you use a non-standard layout.

Further reading

• MkDocs getting started
• MkDocs user guide
• Material for MkDocs