Operation Make the Wiki Pretty!

herb_fargus

So I've been busy at work seeing if we can find a solution to improve the aesthetics of the wiki. This is what I've come up with so far:

https://retropie.github.io/RetroPie-Docs/

This was my list of requirements when making this:

Has to maintain parity with the wiki i.e. we will maintain two copies of the wiki:
- The github wiki where users can continue to edit wiki pages
- The read only pretty version that will be for public consumption

The idea is to use submodules where anytime there are updates to the wiki, we can automatically rebuild the pretty wiki.

The platform I've chosen to use is mkdocs with the Material Theme hosted on Github Pages

I had thought about using Sphinx with the ReadTheDocs Theme hosted with ReadTheDocs as it would have had automatic webhooks for rebuilding, versions, etc. but it requires ReStructured text rather than Markdown like the github wiki uses, so I decided to stick with mkdocs as its an easier migration

I also chose the material theme because it allows for greater flexibility with table of contents dropdowns and fits the layout of the forum and retropie website better.

So! that being said I am looking for some more feedback on how it can be improved.

a few known issues:

The search is a tad laggy, not sure if thats the theme, mkdocs, or github pages. there are 155 pages of docs so that probably doesnt help
Some wiki pages are a little wonky on the markdown and will need some cleanup.

lilbud

how about making the top bar red instead of black.

BuZz

Looks really good! Nice one :-)

herb_fargus

@lilbud I played with the colours a bit and tried red but it looked wonky with the red retropie logo. If (when?) we add a link to the home page and forum it will be a bit more seamless between the web pages with the current colour scheme.

BuZz

@herb_fargus I like the scheme. Matches site nicely!

mattrixk

@herb_fargus: It looks good, but I've noticed something. When you have 2 levels of dot-points on the old wiki (like this), it shows up as a single line of dot-points like this on the new pretty one.

herb_fargus

@mattrixk I didn't realise that, I believe it is due to mkdocs using python markdown whereas the github wiki obviously uses github flavoured markdown (btw this is why many people recommend ReStructured Text for documentation instead of a non standardised markdown) for reference https://github.com/waylan/Python-Markdown/issues/3

I'll see if there are some parser extensions or settings in the .yml that I can add that might address the markdown nuances.

herb_fargus

@mattrixk so this is one of those things where we may need to update some wiki pages.

I've tested it and I'm pretty sure 4 spaces instead of 2 works see the following:

- Level 1
    - Level2

Level 1
- Level2

mattrixk

@herb_fargus Okay, great. I'll have a look at it tomorrow during my lunch break (won't have the chance tonight, I'm probably going to crash out as soon as I get home... and it's only Monday).

herb_fargus

It's not pressing by any means. this will take a while to get into a publishable state, thanks for the feedback

mattrixk

@herb_fargus: I just made a quick change to that page (just adding the 2 extra spaces to those first list items), but it didn't make a change to the new pretty version. Do I need to do anything to "push" the change, or is it just a matter of waiting?

herb_fargus

@mattrixk I have to update the submodule (which clones the latest version of the retropie wiki) and then rebuild the site and push the changes to the docs repository

I'll probably make a module at some point to automate the process.

mattrixk

@herb_fargus Ahh okay. No worries. As I said, I probably won't get the chance to update that page until tomorrow or the day after, so no rush. (also, it's not a major problem, but I'm glad there is a simple solution.)

herb_fargus

I've deployed the latest and can confirm the nested lists are working with the 4 spaces.

I wrote up quick workflow on deploying the docs (mostly for personal reference) likely can be improved

https://github.com/RetroPie/RetroPie-Docs/wiki/Updating-the-Docs

hooperre

Edit: Nvm. Thought it was live. Still looks great haha.

BuZz

@hooperre the wiki is now converted and available from the docs link at the top of the screen here. Herb did a great job. It's still being improved but the documentation is now more accessible than it was via GitHub.

backstander

@herb_fargus
I might have trouble explaining this but...

When you're trying to point someone to a selection on one of the Wiki pages, it uses the # sign + the name of that header (without any spaces/special characters and all in lowercase) like for example:
https://github.com/RetroPie/RetroPie-Setup/wiki/First-Installation#installation

For me to get that link I click on that "Installation" header and it gives me that address so I can post it for someone on the forum.

Now the Docs, that # sign thing works but I can't click on that "Installation" header to easily give me this address:
https://retropie.github.io/RetroPie-Docs/First-Installation/#installation

I don't know anything about mkdocs but is this something that can be added or is it not available like github has it?

herb_fargus

@backstander I believe that's specific to github. Isn't clicking on the TOC on the right the same thing though?

backstander

Isn't clicking on the TOC on the right the same thing though?

Yes, I didn't realize that was clickable ;-)
Thanks @herb_fargus

mrbwa1

Does anyone have an opinion ofn having the FAQ at the Top Level instead of under Troubleshooting. I have spent too many years in support and folks don't seem to look at Troubleshooting, but will look at an FAQ.

Not a big deal if it's current place is where it should be, just thinking out loud.