Effortless export from github wiki (?)

Question

I am collecting quite a lot of material in a GitHub wiki. I really like to use the wiki to cooperate with other people and IMHO the platform is really nice, I like it!

So, I would like to keep using the GH wiki to collect stuff, edit, save,etc but I also would like to export the content in order to create a pdf file that we can call "a manual". I would like to generate an updated version of the manual automatically everytime I want just running a couple of scripts, I can not put too much effort on this.

I guess it is possible to export the content somehow and the use pandoc (http://johnmacfarlane.net/pandoc/) to create the pdf maybe adding an index and a style file.

Another interesting idea could be publish a website once a month dumping content directly from the wiki.

I guess other people already did something like this but I did not find anynthing. Any idea?

Asocial

Answer 1

But... the Github wiki of a GitHub repo is a git repo in itself (introduced in August 2010).

You can clone it, push to it or pull from it.

Each wiki is a Git repository, so you're able to push and pull them like anything else.
Each wiki respects the same permissions as the source repository.
Just add ".wiki" to any repository name in the URL, and you're ready to go.

Or, as noted by htafoya in the comments, replace the .git part of the URL (if present) by .wiki.

That makes the "export" part of your question really trivial.

From there, you will find tons of script for converting markdown pages into pdf:

• a graddle task
• a makefile
• a python script
• ...

Aerophyte

Thank you! If it is possible to handle the wiki as a repo everything should be much easier. – Asocial

@Asocial Yes, not surprisingly, a lot of stuff at GitHub are... git repos ;) – Aerophyte

Gradle script does not work with latest Gradle. Here is a link to the fixed script: gist.github.com/alexeyismirnov/85cdf7b1e9aea4d3494b – Emmanuelemmeline

Not simply add ´.wiki´ but replace typical ´.git´ with ´.wiki.git´ – Bili

@Bili Thank you for the feedback, good point. I have included your comment in the answer for more visibility. – Aerophyte

Answer 2

I'm adding to this answer, in case it helps any new readers :) here's what I did:

I installed GitHub Desktop: https://desktop.github.com/

Then, on the wiki page in my repository, I clicked "Clone in Desktop"

This saved the wiki locally as a .md file (after following the steps on screen)

I then used http://www.markdowntopdf.com/ to convert it to pdf (Note: I renamed the files to remove characters that wouldn't work in a pdf file name before uploading to the website)

The end result was really nice.

Oeo

Using Desktop is not needed. It's basically the same as cloning the git repo of the wiki. You will end up multiple md files and not just one. – Wilkey

Answer 3

I found many of the solutions difficult to reproduce/get the right version/understand/fix/etc... So instead, I'll present a patchwork docker solution to effortlessly convert on Windows(using git bash)/MacOS/Linux in 5 "easy" commands

git clone {project_url}.wiki .

# Convert *.md to *.md.html using the actual github pipeline
docker run --rm -e DOCKER_USER_ID=`id -u` -e DOCKER_GROUP_ID=`id -u` \
            v "`pwd`:/src" -v "`pwd`:/out" andyneff/github-markdown-preview

# Fix hyperlinks, since wkhtmltopdf is stricter than github servers
docker run --rm -v `pwd`:/src -w /src perl \
    perl -p -i -e 's|(<a href=")([^/"#]+?)(#[^"]*)?(">.*?</a>)|\1\L\2\E.md.html\L\3\E\4|g'\
                  *.html

# Lowercase all filename so that hyperlink match
docker run --rm -v `pwd`:/src -w /src python \
    python -c 'import sys;import os; [os.rename(f, f.lower()) for f in sys.argv[1:]]' \
               *.md.html

#Convert html to pdf using QT webkit
docker run -it --rm -e DOCKER_USER_ID=`id -u` -e DOCKER_GROUP_ID=`id -u`\
           -v `pwd`:/work -w /work andyneff/wkhtmltopdf \
           wkhtmltopdf --encoding utf-8 --minimum-font-size 14 \
           --footer-left "[date]" --footer-right "[page] / [topage]" \
           --footer-font-size 10 \
           toc \
           *.html document.pdf

The perl is the main part that may fail without a better solution. Pandoc has a really good filter solution, but isn't using the github pipeline.

Bugs:

• Extra wide code blocks will be rendered with a scroll bar, and essentially cut off in the pdf. It would be best to make the code block not overflow, but you can add --user-style-sheet user.css to the wkhtmltopdf command (before toc/cover), and add to your user.css

  .markdown-body .highlight pre,
  .markdown-body pre{
    overflow:visible !important;
  }
  

• Some link in the final pdf are off by +1 page, some are not. Not sure what the pattern is. But anchors with ids (#) do not appear to have this problem

Enrica

Answer 4

Another option once you clone the wiki, especially if you are already using Atom is to use this Markdown to PDF package. Worked great for me.

Denisdenise

Answer 5

I found really annoying having to convert each markdown document separately (links between markdown documents are lost), so I ended up writting a simple C# program for my own use that does this in a single step: a) Download the last version of the wiki from Github, b) Convert it all the markdown documents merged as one pdf

You can download the binaries (Windows or any platform supporting Mono) from: https://github.com/borjafdezgauna/CoderDocTools/releases/latest

If, for example, you want to convert to PDF the SimionZoo repository by user simionsoft, you can:

MarkdownToPDF.exe user=simionsoft project=SimionZoo output-file=SimionZoo.pdf

Ashleeashleigh

Answer 6

I've accomplished precisely this when creating the portable documentation for Barcode Writer in Pure PostScript:

GitHub Wiki + Makefile + pandoc → PDF

The process is described in this blog post.

Correlation

Answer 7

This question has already been answered but wanted to add my quick experience here.

I didn't find it necessary to install the Desktop version of Github. You can clone by simply running the following from your commandline:

git clone [email protected]:<username>/<repository>.wiki.git

(Of course, replace username and repository as needed).

The cloned wiki outputted 72 markdown files. As has been previously said, there are numerous ways of converting these files do PDF, you can pick your own tool. However I will say that the easiest solution I encountered was to install Pandoc. I have macOS + homebrew, so a quick brew install pandoc was all I needed.

Some info on using pandoc here: https://mcmap.net/q/103503/-converting-multiple-markdown-files-with-links-to-pdf

Fairground

Answer 8

You can also try html_links_to_pdf!

It's a Python 3 script made just to convert a GitHub Wiki to pdf form, using the same styling that GitHub uses, but slightly cleaner.

Benzidine