The Microservices Playbook is a Jekyll-based documentation template that packages a pragmatic, opinionated guide to adopting microservices, with all content written in Markdown and rendered as a static HTML site.
What is The Microservices Playbook?
The Microservices Playbook is a documentation site built with Jekyll, a static site generator, and written entirely in Markdown. It provides a structured playbook for teams adopting microservices, covering pragmatic and opinionated guidance. The content lives in the _playbook directory, and the site is built by running jekyll build in the main directory. It originated as a clone of the datawire/playbook repository and is labeled "NRM Containerization Playbook" in its repository metadata.
Key Features
- Markdown-based content — All playbook chapters are authored in Markdown inside the
_playbookdirectory, making contributions and version control straightforward. - Jekyll static site generation — The site is built with Jekyll; running
jekyll buildgenerates the static HTML output for hosting anywhere. - Local development workflow — Running
gem install && jekyll servestarts a local server at http://localhost:4000/playbook/ for live preview during editing. - Lifecycle: Experimental — The repository carries an Experimental lifecycle badge, signaling the playbook is in an early, evolving stage.
- Playbook-centric structure — The repository topics include documentation, jekyll-theme, nrm, playbook, and playbooks, confirming its purpose as a themed documentation site for operational runbooks.
Who is it for?
- Software architects — Use the playbook to structure guidance on microservices adoption for their organization, editing the Markdown chapters to match their own context.
- Platform engineering teams — Adapt the Jekyll site as an internal documentation hub for containerization and microservices best practices.
- Technical writers — Leverage the Markdown-based workflow to maintain consistent, version-controlled operational documentation.
What can you do with The Microservices Playbook?
- Publish a microservices adoption guide — Write chapters in Markdown and generate a static HTML site that can be deployed to any web server or CDN.
- Customize the Jekyll theme — Modify the theme's layout and styling to match your organization's branding.
- Run a local preview — Use
jekyll serveto view edits in real time at localhost:4000/playbook during the writing process.
How does The Microservices Playbook work?
To use the playbook, clone the repository, install Jekyll with gem install, then run jekyll serve for local development. Content is added or edited as Markdown files in the _playbook directory, and jekyll build produces the final static HTML site for deployment.
