Github Wiki to Mkdocs - HerbFargus/Raspberry-Pi-Scripts GitHub Wiki

Github wikis are written in markdown by default but aren't the prettiest interface for documentation. Since Content Management Systems (CMS) are too bloated for simple wikis, we need something simpler: enter static page generators. There are many different kinds but since we are already working in github with markdown, we can use mkdocs.

The most thorough professional approarch IMO is to use Sphinx: a tool for writing documentation that uses ReStructured Text. It is more complex than Markdown but allows for more detailed documentation. When integrated and hosted on readthedocs it allows for control over version releases, export to pdf, html, epub, etc. and has integrated webhooks to pull and build from a github repo anytime commits are pushed to the master.

There is some functionality to convert md files to rst with sphinx, but it is very picky. you could also convert with pandoc perhaps, but either way, md to rst conversion will at some point require some manual changes which may not be efficacious if you have hundreds of pages to convert.

Mkdocs uses md natively, so its a much simpler solution. There are some limitations with the readthedocs theme with mkdocs (e.g. no toggleable headings, no epub, html exports, no versions etc.) There are other themes like the Material theme that have some dropdowns and some extra customisability.

Now that I've explained my reasoning, this guide will detail how to convert a github wiki to mkdocs using the material theme hosted on github pages.

Install Dependencies

Assuming you are on a linux pc: install python and pip (should be installed with python by default)

sudo apt-get install python3 python3-pip libyaml-dev
pip install --upgrade pip

Install Mkdocs

pip install mkdocs

Create Github Repository

First create a github repository on github.com and clone to local repository

git clone https://github.com/HerbFargus/docs.git

Mkdocs Project

mkdocs new docs

Download Github Submodule

cd docs
git submodule add https://github.com/RetroPie/RetroPie-Setup.wiki.git retropie.wiki

The idea with using submodules is to be able to update your documentation anytime the github wiki is updated, one caveat with using a github wiki as your source is that mkdocs requires an index.md page which is the Home.md page on a github wiki.

Mkdocs by default will look for docs in the docs folder but can be changed by specifying a docs folder in the mkdocs.yml config file.

There are a few approaches to keeping our wiki up to date while needing to edit the Home.md file:

• We can maintain our submodule folder and our docs folder, we can copy submodule folder to docs folder, while renaming Home.md to index.md, and then on any wiki updates, update submodule, wipe docs folder, copy submodule contents and rename Home.md

e.g.

rm -R docs/
cp -R retropie.wiki/ docs/
cd docs/
mv Home.md index.md

• We can create a redirect from index.md to Home.md
• We can use the submodule folder as our docs folder and rename Home.md to index.md but will require a rename back to maintain parity with the wiki repo.

Install Material Theme

pip install mkdocs-material

Test Docs Repo:

mkdocs build
mkdocs serve

access your docs page by going to http://127.0.0.1:8000/

Deploy on Github Pages

mkdocs gh-deploy

Material Theme Customisations

TODO:

Adding a Logo:

mkdir images

save image to images/logo.svg

in mkdocs.yml

extra:
  logo: 'images/logo.png'

Custom CSS to size and position logo

create a file stylesheets/extras.css

in mkdocs.yml

extra_css:
  - 'stylesheets/extra.css'

.md-header-nav__button.md-logo img {
    display: block;
    height: 50px;
    width: 50px;
}

.md-header-nav__button.md-logo {
    margin: 0rem;
    padding: 0rem;
}

.md-nav__button img {
    width: 50px;
    height: 50px;
}

Change table heading colour to Black:

.md-typeset table:not([class]) th:not([align]){text-align:left}.md-typeset table:not([class]) th{min-width:10rem;padding:1.2rem 1.6rem;background-color:rgba(0, 0, 0, 1);color:#fff;vertical-align:top}

Colour Palettes

  palette:
    primary: 'grey'
    accent: 'red'

Github Nav

in mkdocs.yml

repo_name: 'RetroPie-Setup'
repo_url: 'https://github.com/RetroPie/RetroPie-Setup'

Add social links and copyright

  social:
    - type: 'github'
      link: 'https://github.com/RetroPie'
    - type: 'twitter'
      link: 'https://twitter.com/retropieproject'

copyright: 'Copyright © 2017 The RetroPie Project'

Final mkdocs.yml

site_name: RetroPie Docs
theme: material
extra:
  logo: 'images/logo.svg'
  palette:
    primary: 'red'
    accent: 'red'
  social:
    - type: 'github'
      link: 'https://github.com/RetroPie'
    - type: 'twitter'
      link: 'https://twitter.com/retropieproject'
extra_css:
  - 'stylesheets/extra.css'
repo_name: 'RetroPie-Setup'
repo_url: 'https://github.com/RetroPie/RetroPie-Setup'

markdown_extensions:
  - pymdownx.arithmatex
  - pymdownx.betterem(smart_enable=all)
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist(custom_checkbox=true)
  - pymdownx.tilde

copyright: 'Copyright © 2017 The RetroPie Project'
      
pages:
- Home: index.md
- First Installation: First-Installation.md
- Getting Started: 
    - Arcade Quick Start: Managing-ROMs.md
    - Transferring Roms: Transferring-Roms.md
    - Scraper: Scraper.md
    - Themes: Themes.md
    - Runcommand: Runcommand.md
    - Updating RetroPie: Updating-RetroPie.md
    - SSH: SSH.md
    - Wifi: Wifi.md
- Emulators:
    - 3do: 3do.md
    - Amiga: Amiga.md
    - Amstrad CPC: Amstrad-CPC.md
    - Apple II: Apple-II.md
    - Atari 2600: Atari-2600.md
    - Atari 7800: Atari-7800.md
    - Atari 800 and 5200: Atari-800-and-5200.md
    - Atari Jaguar: Atari-Jaguar.md
    - Atari Lynx: Atari-Lynx.md
    - Atari ST-STE-TT-Falcon: Atari-ST-STE-TT-Falcon.md
    - Coco: Coco.md
    - Colecovision: Colecovision.md
    - Commodore 64: Commodore-64.md
    - Daphne: Daphne.md
    - Dragon: Dragon.md
    - Dreamcast: Dreamcast.md
    - FinalBurn Alpha: FinalBurn-Alpha.md
    - Game Boy Advance: Game-Boy-Advance.md
    - Game Boy Color: Game-Boy-Color.md
    - Game Boy: Game-Boy.md
    - GameCube: GameCube.md
    - Game Gear: Game-Gear.md
    - Game & Watch: Game-&-Watch.md
    - GemRB: GemRB.md
    - Genesis/Megadrive: Genesis-Megadrive.md
    - Intellivision: Intellivision.md
    - Love: Love.md
    - lr-fbalpha: lr-fbalpha.md
    - lr-mame2003: lr-mame2003.md
    - Macintosh: Macintosh.md
    - MAME: MAME.md
    - Master System: Master-System.md
    - MESS: MESS.md
    - MSX: MSX.md
    - Neo Geo: Neo-Geo.md
    - Neo Geo Pocket Color: Neo-Geo-Pocket-Color.md
    - Neo Geo Pocket: Neo-Geo-Pocket.md
    - Nintendo 64: Nintendo-64.md
    - Nintendo DS: Nintendo-DS.md
    - Nintendo Entertainment System: Nintendo-Entertainment-System.md
    - OpenBOR: OpenBOR.md
    - Oric: Oric.md
    - PC Engine: PC-Engine.md
    - PC: PC.md
    - Playstation 1: Playstation-1.md
    - Playstation 2: Playstation-2.md
    - PSP: PSP.md
    - Sam Coupe: Sam-Coupe.md
    - Saturn: Saturn.md
    - ScummVM: ScummVM.md
    - Sega 32X: Sega-32X.md
    - Sega CD: Sega-CD.md
    - SG 1000: SG-1000.md
    - Super Nintendo Entertainment System: Super-Nintendo-Entertainment-System.md
    - TI99: TI99.md
    - TRS-80: TRS-80.md
    - Vectrex: Vectrex.md
    - VideoPac / Odyssey 2: VideoPac-Odyssey-2.md
    - Virtual Boy: Virtual-Boy.md
    - Wii: Wii.md
    - Wonderswan Color: Wonderswan-Color.md
    - WonderSwan: WonderSwan.md
    - Zmachine: Zmachine.md
    - ZX Spectrum: ZX-Spectrum.md
- Ports: 
    - Adventure Game Studio: Adventure-Game-Studio.md
    - Cannonball: Cannonball.md
    - CaveStory: CaveStory.md
    - Commander Keen: Commander-Keen.md
    - Descent: Descent.md
    - Dinothawr: Dinothawr.md
    - Doom: Doom.md
    - Duke Nukem 3D: Duke-Nukem-3D.md
    - GameMaker Games: GameMaker-Games.md
    - KODI: KODI.md
    - Limelight: Limelight.md
    - Lincity: Lincity.md
    - Marathon: Marathon.md
    - Micropolis: Micropolis.md
    - Minecraft: Minecraft.md
    - OpenTTD: OpenTTD.md
    - OpenTyrian: OpenTyrian.md
    - Ports: Ports.md
    - Quake: Quake.md
    - ResidualVM: ResidualVM.md
    - SDLPoP: SDLPoP.md
    - Solarus: Solarus.md
    - Stratagus: Stratagus.md
    - Super Mario War: Super-Mario-War.md
    - SuperTux: SuperTux.md
    - The Ur Quan Masters: The-Ur-Quan-Masters.md
    - Wolfenstein 3D: Wolfenstein-3D.md
    - Xrick: Xrick.md
- Controllers:
    - Bluetooth: Setting-up-a-Bluetooth-controller.md
    - 8bitdo: Setting-up-an-8bitdo-Bluetooth-controller.md
    - N64: Setting-up-an-N64-controller.md
    - PS3: Setting-up-a-PS3-controller.md
    - PS4: Setting-up-a-PS4-controller.md
    - Ouya: Setting-up-a-Wireless-Ouya-Controller.md
    - XBox 360: Setting-up-the-XBox360-controller.md
    - Logitech: Logitech-controllers.md
    - Xiaomi Gamepad: Xiaomi-Gamepad.md
    - Xin-Mo: Xin-Mo-Controller.md
    - Spinners and Trackballs: Spinners-and-Trackballs.md
    - Mobile Gamepad: Mobile-Gamepad.md
    - Virtual Gamepad: Virtual-Gamepad.md
    - Wii U Pro: Setting-up-Wii-U-Pro-controller.md
    - Wiimotes with classic controllers: Wiimotes-with-classic-controllers.md
    - GPIO Modules: GPIO-Modules.md
- Advanced Configuration:
    - BIOS: BIOS.md
    - Changelogs: Changelogs.md
    - Configuration Editor: Configuration-Editor.md
    - Mapping a Controller for Intellivision: Mapping-a-Controller-for-Intellivision.md
    - Memory Split: Memory-Split.md
    - Optimization for Nintendo 64: Optimization-for-Nintendo-64.md
    - Overclocking: Overclocking.md
    - Running ROMs from a Network Share: Running-ROMs-from-a-Network-Share.md
    - Running ROMs from a USB drive: Running-ROMs-from-a-USB-drive.md
    - Splashscreen: Splashscreen.md
    - Supported Systems: Supported-Systems.md
    - Take and Scrape Your Own Screenshots: Take-and-Scrape-Your-Own-Screenshots.md
    - Universal Controller Calibration & Mapping Using xboxdrv: Universal-Controller-Calibration-&-Mapping-Using-xboxdrv.md
- RetroArch:
    - RetroArch: RetroArch.md
    - RetroArch Configuration: RetroArch-Configuration.md
    - RetroAchievements: RetroAchievements.md
    - Netplay: Netplay.md
    - Shaders and Smoothing: Shaders-and-Smoothing.md
    - Smaller RetroArch Screen: Smaller-RetroArch-Screen.md
- EmulationStation:
    - EmulationStation: EmulationStation.md
    - Child friendly EmulationStation: Child-friendly-EmulationStation.md
    - Creating Your Own EmulationStation Theme: Creating-Your-Own-EmulationStation-Theme.md
- Platforms:
    - Raspbian: Manual-Installation.md
    - Ubuntu: RetroPie-Ubuntu-16.04-LTS-x86-Flavor.md
    - Odroid: Odroid.md
    - Arch Linux: RetroPie-Arch-Linux-Flavor.md
    - OSMC: RetroPie-install-for-OSMC-with-external-memory-USB-Drive.md
- Troubleshooting:
    - FAQ: FAQ.md
    - Sound Issues: Sound-Issues.md
    - Speed Issues: Speed-Issues.md
    - Video Issues: Video-Issues.md
- Developers:
    - Building RetroPie Archives: Building-RetroPie-Archives.md
    - Convert RetroPie SD Card Image to NOOBS Image: Convert-RetroPie-SD-Card-Image-to-NOOBS-Image.md
    - Shell Style Guide: Shell-Style-Guide.md

• Nav for HomePage, Github, Forum?