Switch to MkDocs for documentation

[lisaross]

Resolves #1332
(I think)

Lots of files and configurations changed but I've done my best to document how and what was done.

Some highlights:

• moved files into structure that is more audience specific (ie. developer vs user, as well as making more multilang friendly when the time comes)
• mkdocs runs it all, with material theme bringing features like search
• theme uses material for function but modded to create similar look/feel to existing .net
• switched out markdown note engine from html to admonition and refactored documentation
• functionality for theme override in place with instructions in readme
• tested docs to ensure links aren't broken

Still to do

• not sure how you want to deploy - left it in the README for you to decide and we can update the docs as needed
• mkdocs doesn't have a great system in place for redirection, in the event that we want to point someone to the new link should they land on an old one. Depending on how we deploy, we can either use server side redirection using .htaccess for example, or we can create files in old location that manually redirect to new. I would say we should open a new issue for redirection and go from there though.

Some notes

• this is actually my first pull request ever, so please be kind if I've screwed something up. 💃
• if you have any questions about how something works please let me know
• realized after the fact that this should have been tagged 'improvement' rather than 'feature' I think. Sorry.
• wasn't sure if you have any automated tests in place for this - if so, please point me in the right direction. If not, I'd love to work with someone to see about making them.
• don't hesitate to punt it back to me if it's a disaster. I only just started using git, for example, so if my commits aren't to standard I'd love coaching on that (or anything, for that matter)

---

@borekb 🏁 notes:

This is an awesome PR and a nice refresh of our docs, thanks @lisaross! Highlights from my point of view are:

• Static site hosted on GitHub Pages instead of a custom Node.js app that was bothersome to run and maintain.
• Developer documentation is now part of the docs as well.
• Much easier contributions via GitHub pull requests – there's an edit button on each page.
• We use a standard documentation system, MkDocs, instead of a custom one.

New site:

Original site:

[borekb]

@lisaross Thanks for the visual fixes in c4bae26, it's much better now.

I've also merged in master which now contains a major update of dev-setup.md from PR #1329.

This evening, I should find some time to look at this PR again, work on the smaller remaining issues and hopefully get it prepared for merge.

[lisaross]

Nice! I have to fix up the footer today and I think that’ll be a good commit to merge. Stay tuned :) if there’s anything else I can do please let me know. I’m super excited to have been able to help!

[lisaross]

Gah! I just merged something into master without meaning to I think... please rewind if needed, @borekb

Edit: oh good. I think I just gave myself an unneeded heart attack LMAO

[borekb]

Yeah, everything is alright :) Actually, GitHub would prevent any accidental push to master so you'll safe.

[lisaross]

Ya I realized that after I typed. Of course you wouldn't let someone with a single pull request push to master lmao. That last commit was just adding your socnets to the footer - I was going to mod the whole footer file to make it look like .net, but realized that was probably enough and kept it simple. If you want me to make further mods just make me a list and I'll work on it tomorrow. Otherwise, I think the styling is ok for now? Or did I miss something?

[borekb]

I was going to mod the whole footer file to make it look like .net, but realized that was probably enough and kept it simple.

Yep, I actually like the current footer very much – keeps the style of previous docs but is more useful / modern.

Otherwise, I think the styling is ok for now? Or did I miss something?

Generally, I think it looks awesome, just the contrast of the search box is sometimes not great, e.g., on hover. Do you want to look into that? I could also experiment with it a bit.

[borekb]

I'm looking at the styles, for example, setting the theme.palette.primary value to a hex value doesn't seem to have any effect. Give me a few moments to review this, thanks.

[borekb]

I've done some slight visual fixes in 070f528, I'm happy with it now.

Still to-do (plan to do this tonight):

• logo.png is too small for mobile view with sidebar opened - it's pixelated. Plus, upload to CDN. d720e6a
• Sort out favicon. d720e6a
• H5 is too big d1bde7a
• Review content d898e02
• Lint Markdown files manually ee49284

[borekb]

Hi @lisaross, sorry for the delay, I think I'll find time today evening to have a look at the GitHub Pages deployment (just document the manual process in README) and then I'd be happy to merge this PR. Is that fine with you? Anything else you would like to look at? Thanks.

[lisaross]

oh my goodness, don't apologize! 😄Let's do it! I didn't get a chance to look at the search styles, but we can probably do a minor after the PR is merged, yes? Thanks for including me in this process btw. I love that I've been able to contribute.

[borekb]

Thanks. I'll probably write a quick blog post about the new docs and would like to credit you, do you have a Twitter profile or something that you'd prefer me to use? Your contribution has been awesome!

[lisaross]

WOW! THANKS! My twitter profile is @iamlisaross but I've updated my github profile to display info instead if that's easier/better. 👍 https://github.com/lisaross

[borekb]

🎉 the docs site is now updated and runs on GitHub Pages: https://docs.versionpress.net/

I'll make some final notes in this PR later tonight and merge.