acaos / mkdocs-browsersync

MkDocs + BrowserSync Docker

MkDocs + BrowserSync

Due to recent changes in MkDocs version 1.1.1, it is now less convenient to run MkDocs within a Docker for local development. In addition, the maintainer of MkDocs has stated that the libraries used to support serving and live reloading are poorly supported and may break in the future.

This repository attempts to offer an alternative solution, combining MkDocs, BrowserSync, and Gulp into a single Docker container which will watch a volume, automatically rebuild on changes, and then refresh attached browsers. The documentation is built and then rsynced to the final location to allow for a clean build that does not delete actively-served files while the build is in progress.

Usage

Basic usage (from the directory with your mkdocs.yml):

docker run --rm -p 8080:8080 -v $(pwd):/docs -it acaos/mkdocs-browsersync:latest

If you are using the excellent git-revision-date plugin and your .git directory is above your mkdocs.yml, you may need to specify the working directory as well (the example below assumes project/mkdocs.yml):

docker run --rm -p 8080:8080 -v $(pwd):/docs -w /docs/project -it acaos/mkdocs-browsersync:latest

Configuration

The only additional configuration available is that a MKDOCS_IGNORE environment variable may be passed which specifies a space-separated list of globs to ignore when watching.

Future Development

• Inspect mkdocs.yml and build a better list of directories to watch rather than watching the entire working directory.
• Allow more configuration of BrowserSync.
• Add a sample docker-compose.yml for use with Docker Compose.
• Add examples of more advanced usage (e.g. plugin integration, additional Gulp build steps).
• Add examples for non-Dockerized usage.