How to convert GitHub Wiki into GitHub pages?

Question

I want my existing GitHub Wiki to be served as GitHub pages.

I tried copying all the .md files into /docs and setting that as the source for pages - but it breaks all the internal links.

So I see Read the [[documentation]] or [[Help|get help]]. rather than links.

What's the easiest way to host my wiki on GitHub pages?

Answer 1

You need to create manual Markdown links to each page.

[[documentation]] and [[Help|get help]] style links are wikilinks and generally only used in wikis. They are not part of the standard Markdown syntax and not supported by Jekyll (which GitHub Pages uses under the hood). Note that GitHub Wiki supports both styles, so you could edit your links before importing if you like.

Either way, you need to edit your links to manually point to the appropriate pages using the standard markdown syntax:

Read the [documentation](path/to/documentation/) or [Help](path/to/get_help.html)

Of course, you will need to adjust the above paths to point at the correct location. As an alternative, you may be able to use Jekyll permalinks, which could provide a shortcut for you to identify specific pages without specifying a full path.

Answer 2

Just received this direct from GitHub.

---

There is no easy answer I am afraid. You will need to script or manually change the wiki format URLs to proper markdown format.

We did just add relative links to GitHub Pages though:

https://github.com/blog/2290-relative-links-for-github-pages

Which should make things easier at least, as you won't need to fully qualify all the URLs.

So you can change:

Read the [[documentation]] or [[Help|get help]].

to

Read the [documentation](documentation.md) or [Help](get%20help.md).

Alternatively, you may be able to use pandoc and the script below to do the conversion for you:

https://github.com/philipashlock/mediawiki-to-markdown

But I haven't tested it myself so I can't guarantee it will work.

This could be useful feature though, so I will share it with the team in the hope of an easy converter in the future

Answer 3

There are tool to do it automatically. Have a look at github-wikito-converter.

Generate HTML & PDF documentation from Github wiki or any other markdown-based wiki.

Or limedocs-wiki-converter.