MkDocs + gfm-toc Docker

Docker image for MkDocs and gfm-toc.

Support

• MkDocs
• Material for MkDocs
• PlantUML Markdown
• gfm-toc

Why gfm-toc

I use MkDocs on Monorepo so I want to use Table of Contents for whole documents. I haven't used MkDocs for a while, so I don't know what plugins there are.

Usage

Use buildoc.sh to build site easily!

$ bash buildoc.sh input-dir output-dir
# or
$ bash buildoc.sh input-dir output-dir ../mkdocs.yml
# then
$ tree output-dir

By manual

1. Put mkdocs.yml in working directory.
2. Put all documents and resources into $PWD/docs directory

And then, we can run mkdocs using this Docker image and get all built result from $PWD/site.

docker run \
  -u ${UID} \
  -v $PWD:/opt \
  registry.infra.music-flo.io/test/mkdocs-gfm-toc \
  build

Please run Docker on UID user for grant same permission to result files in site directory.

Directory structure

.
├── mkdocs.yml
├── docs
│   └── README.md
└── site
    ├── index.html
    └── ...

Configuration

First, copy mkdocs.example.yml to mkdocs.yml and give some information such as site_name and repo_url.

Document gathering

If the target repository isn't large, it's good to use it as is. However, if you want to run docker with only documents and resources, use the following command: It copies only markdown files and png files to the specified directory.

find . \( -name "*.md" -o -name "*.png" \) -exec cp --parents {} "${TARGET_DIR}/docs" \;

License

MIT