Generate awesome docs from Markdown files with Docker and bookdown.io

More and more projects uses bookdown.io to generate their documentation from Markdown files. This has several benefits. You can easily generate an awesome stylish documentation with syntax highlighting by using another template. It's even possible to create an own book based on the bookdown.io book or on every other Markdown file. It's not necessary to download the repository to generate the documentation. If you have your documentation in your repository, even separated by components, Developers will find it quicker. You have versioning of your documentation and the documentation is also up to date. These benefits and to generate documentation in seconds are very useful. In this blog post, I will show you some interesting insides powered by the Docker bookdown.io image to generate your own stylish documentation in seconds.

Please install Docker if not already done and navigate to a new empty directory.

Zend Framework documentation

Some Zend Framework components have already a bookdown.io documentation. Let's take a look at the Zend Service Manager component documentation. Simply run the following command. Docker will download a bookdown.io image with a beautiful template and generates the HTML documentation in the html folder.

$ docker run -it --rm -v $(pwd):/app sandrokeil/bookdown https://raw.githubusercontent.com/zendframework/zend-servicemanager/develop/doc/bookdown.json --target="/app"

After the process is finished, you can open the documentation by executing the following command. This command is the same for the other books too.

$ docker run -it --rm -p 8080:8080 -v $(pwd):/app php:7.0-cli php -S 0.0.0.0:8080 -t /app

Open your browser at http://localhost:8080 and visit the great documentation for Zend Service Manager. You can now navigate through the documentation and have mobile support and syntax highlighting. But that's not all.

See the new shiny Zend components like Zend\Expressive, Zend\Stratigility and Zend\Diactoros in one place? No problem, create your own bookdown.io book. Put the following content to an empty bookdown.json file.

{
  "title": "My awesome Zend docs",
  "content": [
    {"zendexpressive": "https://raw.githubusercontent.com/zendframework/zend-expressive/master/doc/bookdown.json"},
    {"zenddiactoros": "https://raw.githubusercontent.com/zendframework/zend-diactoros/master/doc/bookdown.json"},
    {"zendstratigility": "https://raw.githubusercontent.com/zendframework/zend-stratigility/master/doc/bookdown.json"}
  ],
  "target": "./html"
}

Execute the Docker bookdown.io image by running docker run -it --rm -v $(pwd):/app sandrokeil/bookdown bookdown.json. If the process has finished, you can open your browser or refresh the page, if your PHP Docker container is already running.

Create your individual book

You want a darker theme? I have a good news for you. You can choose between 16 styles and 13 syntax highlighting styles. For more information visit the bookdown-bootswatch-templates repository on GitHub. Your favourite project has Markdown files, but no bookdown.io book? Don't worry, because Markdown files are all you need. Here is an example for the DoctrineORMModule. Put the following lines to an empty bookdown.json file.

{
  "title": "Doctrine ORM Module",
  "content": [
    {"readme": "https://raw.githubusercontent.com/doctrine/DoctrineORMModule/master/README.md"},
    {"configuration": "https://raw.githubusercontent.com/doctrine/DoctrineORMModule/master/docs/configuration.md"},
    {"migrations": "https://raw.githubusercontent.com/doctrine/DoctrineORMModule/master/docs/migrations.md"},
    {"cache": "https://raw.githubusercontent.com/doctrine/DoctrineORMModule/master/docs/cache.md"},
    {"extras": "https://raw.githubusercontent.com/doctrine/DoctrineORMModule/master/docs/EXTRAS_ORM.md"},
    {"developertools": "https://raw.githubusercontent.com/doctrine/DoctrineORMModule/master/docs/developer-tools.md"}
  ],
  "target": "./html"
}

Ok, I promise you a darker theme. Here is the command. Simply set the environment variables for the Bootswatch template and Prism CSS.

$ docker run -it --rm -e CSS_BOOTSWATCH=darkly -e CSS_PRISM=twilight -v $(pwd):/app sandrokeil/bookdown bookdown.json

Conclusion

You have seen, it's quite easy to generate beautiful documentation of libraries and even to create your own documentation. The bookdown.io project is on an early stage and some nice features like image download are already merged in develop. Please feel free to contribute to this project. There are some open tasks.

bookdown.io is also available as a Composer PHP package and can be included in your own project. You can generate the documentation without Docker by running ./vendor/bin/bookdown [path to bookdown.json file], if you have installed the bookdown.io package via Composer. Take a look at the bookdown.io documentation for more details.

How do you generate your documentation? Please feel free to leave a comment.