Documentation is essential to any project and that is why GitHub repositories come with access to a wiki. According to Wikipedia, a wiki is ” an online hypertext publication collaboratively edited and managed by its own audience, using a web browser”. A GitHub wiki provides a collaborative space for your team to document the project.
GitHub wikis are written in Markdown language and are edited in the browser, making them very accessible. However, there may be times you want to share this documentation with others outside of your team. If your repository is private, so is your wiki, which makes sharing documentation difficult.
One option you might have is to painstakingly reformat the content in a Word document, which is rather time-consuming. The second option would be to simply print the browser page but that usually isn’t aesthetically pleasing. So, with that I thought, surely there is a way to export GitHub wiki pages to PDF, after all, there are simply markdown files, so it shouldn’t be too hard.
Locally Cloning a GitHub Wiki
The first step to converting a GitHub wiki into a pdf is to download a local clone of your wiki. At the very bottom of the wiki page should be a Clone this wiki locally URL. Simply click the copy button to copy the URL.
You could use any Git tool to clone the wiki locally, however, I’m not fond of using terminal tools. While GitHub Desktop would be a good alternative it turns out that GitHub Desktop has a known issue with GitHub Wikis and therefore can not import them. The best solution is to use VS Code especially since we will be using VS Code to convert the wiki files to pdf.
- Open VS Code on your desktop and choose Clone Git Repository
- A drop down box will appear a the top of the screen, paste the clone wiki URL in the box.
Exporting PDFs
Now that you have local copy of the GitHub wiki we will need to install a handy little extension to convert the Markdown files to a PDF.
-
- With your documentation open in VS Code, choose View > Extensions
- In the Extension panel on the left of screen search for the extension Markdown PDF by yzane. Then press the install button.
[Note that in the image below there is no install button, because the extension has already been installed. ]
- Once installed, from the Explorer window in VS Code select the wiki page you want to export as a pdf.
- Press the F1 key to open the Command Pallet and type Markdown PDF: Export (pdf)
That’s it! Once you run the command you will see a new pdf file in the Explorer window.
After exporting each of the wiki pages, I used Acrobat to combine the PDF documents into one.
Other File Types
You might have noticed when you ran the command to Export to PDF the Markdown to PDF tool also allow you to export to other file types such as, HTML, JPG and PNG. This makes for a very handy extension to VS Code.
While this may be a one off use case I found if very helpful and thought that it might be of use to others as well.