Building an interlinked Github wiki from markdown topics
I use markdown wherever possible since it is a very simple and clean syntax to work with and is easy to read as-is. One of the areas that I’ve wanted to adopt markdown for a while is for documentation but somehow without compromising on the high quality linking that I have between topics.
With DITA topics are bound into the distributable materials using book maps. The book map essentially adds structure to topic files and sets out topics that are somehow related to one another. The DITA tooling can then use this information to automatically generate all the good stuff like table of contents, breadcrumbs, next/previous page links, child topic listings and related topic listings.
So it seemed somewhat logical to adopt a similar format for the markdown topic files; except using YAML instead of XML. The same YAML book map could be used to render output HTML pages using a template engine like nunjucks if desired; but for the time being outputting Github wiki style markdown is all that is needed.
Previously the DITA topics had URL friendly slug names to identify them. Since Github wiki actually encodes the topic title into the filename it made sense to adopt the same approach for naming the input topics. Whilst this naming convention has the disadvantage that certain symbols cannot be used in titles, it ensures that topics are easy to find and that the naming of source and output files is consistent.
I developed a CLI tool using node.js which parses a YAML encoded book map file to produce linking between topics using Github wiki style links. The tool also converts the links of embedded images from regular markdown syntax into the Github wiki syntax.
For anyone interested in using this tool, checkout its repository on Github: https://github.com/rotorz/github-wiki-from-markdown-book
Examples:
rotorz/unity3d-tile-system
Source: https://github.com/rotorz/unity3d-tile-system/tree/master/docs
Output: https://github.com/rotorz/unity3d-tile-system/wiki
rotorz/unity3d-reorderable-list
Source: https://github.com/rotorz/unity3d-reorderable-list/tree/master/docs
Output: https://github.com/rotorz/unity3d-reorderable-list/wiki