As a software engineer I love to work with source code that comes with Unit Tests and a well written documentation. Markdown is surely a good way to write your documents. But sometimes it comes in handy to have a shiny PDF to store offline, send via email or print in high resolution. For those cases Docbook (co-founder O’Reilly Media) is a good solution because it supports different output formats like pdf, epub or html. My project livingfire-docbook shows a easy way to get started with Docbook and alter this example for your own needs. The software can also covert Markdown to Docbook using pandoc and combine multiple Markdown files like a GitLab Wiki into one PDF. In addtion to that you can write UML diagrams in PlantUML and have them rendered into pictures in your book.
# download project files git clone https://firstname.lastname@example.org/phoen1x/livingfire-docbook.git cd livingfire-docbook # start livingfire-docbook docker-compose up -d # convert docbook to pdf docker-compose exec docbook /book/convertBook.sh xdg-open book/target/docbkx/pdf/book.pdf # write Markdown or import wiki cd tmp/wiki git init git remote add origin https://gitlab.com/phoen1x/livingfire-docbook.wiki.git git pull rm -rf .git cd ../.. # convert plantuml to images - http://plantuml.com/ docker-compose exec docbook /book/convertPlantuml.sh # convert markdown to docbook docker-compose exec docbook /book/convertWiki2Docbook.sh xdg-open book/target/docbkx/pdf/book.pdf # stop livingfire-docbook and get PDF docker-compose down cat book/target/docbkx/pdf/book.pdf > book.pdf
book |-- pom.xml `-- src `-- main `-- documentation `-- docbook | |-- book.xml | |-- template_chapter.xml | `-- chapters | |-- chapter_1.xml | |-- chapter_2.xml | |-- chapter_n.xml | `-- media | |-- cover.png | `-- logo.png |-- fonts |-- xsd `-- xslt `-- docbook.xsl
Probably everything you ever need to write a book is within the livingfire-docbook/ book/src/main/documentation/docbook directory. Here you can find the book.xml and a templates for your own content. To tweak the style of your book alter docbook.xsl and pom.xml.
You can use a Markdown Wiki like Gollumn to create your docbook chapters and then further refine the document using these links:
The project is also capable of converting PlantUML
@startuml Bob -> Alice : Hello Alice Alice -> Bob : Hello Bob @enduml
into an image
@startuml Script -> Markdown: get file content Script -> Script : text multiline grep for Plantuml CONTENT loop CONTENT found Script -> Script : generate hash from CONTENT -- 693d9a0698aff95c Script -> 693d9a0698aff95c.puml: save CONTENT to 693d9a0698aff95c.puml Script -> Markdown: replace CONTENT with ![uml](693d9a0698aff95c.png) end Script -> Plantuml: convert media/*.puml to media/*.png Plantuml -> 693d9a0698aff95c.puml: get Plantuml -> 693d9a0698aff95c.png: create @enduml
More information on Plantuml can be found at the PlantUML website.
The source code of my converter can be found here.
To manually convert Markdown you need to install pandoc
# apt-get install pandoc pandoc --chapters -t docbook --output page.xml page.md
# install Java -- https://java.com/en/download/ git clone https://email@example.com/phoen1x/livingfire-docbook.git cd livingfire-docbook # Linux ./mvnw clean site xdg-open target/docbkx/pdf/book.pdf # Windows mvnw.cmd clean site # Open target/docbkx/pdf/book.pdf in file browser