website sketch prototype

[clux]

since we have a domain, and i already had some experience porting large linked markdown pages together with mkdocs and mkdocs-material, i have made this prototype page for kube-rs for fun:

(the repo is marked internal, but the site is public to anyone with the link - which is probably ok for now. not shared it outside here)

material-mkdocs

used material-mkdocs because i have experience using it before and it's pretty easy. it also tells you when you have missing links during mkdocs serve or during ci builds, so it can be useful for some of this.

there might be other systems, but this is what i know, and it is highly customizable and very popular (browse their project page that also is using it)

syncing

it currently takes a grab-bag of markdown files from other repos, and does not make a lot of effort into making the headers consistent, but this could easily be done.

cross-linking

i made a folder for crates that showcases how the things cross-link together (basically, with recommended vscode extensions, you can ctrl-click the wiki-links and they open a new document, and they are much easier to create than having to remember the path yourself - this is using foam)

toc

material mkdocs is highly configurable w.r.t. how it generates its navigation, via tabs or nested nav bars like i have used here.

WDYT?

cc @kube-rs/maintainers

leaving this here for a while to get some feedback, happy to sketch at this some more, it should not be too much work to get this to look decent. the harder bits of course is writing more docs, ensuring consistency of docs between repos (how? move or sync?), writing a good landing page, and somehow finding a balance between manual docs and docs that can be checked by rustdoc...

(rustdoc; originally gave up on running rustdoc on README.md in kube-rs root repo - so not sure how best to proceed here, the readme is currently copied as the quick-start guide)

[clux]

oh, and btw, this is heavily inspired by thanos.io which have similar documentation asks from CNCF/best practices badge.

[nightkr]

One upside of mdbook is that it can automatically test any Rust examples, just like rustdoc does. I can't seem to find anything similar for mkdocs.

[nightkr]

Either way, this seems like a vast improvement over just linking to the GitHub repository.

[clux]

One upside of mdbook is that it can automatically test any Rust examples, just like rustdoc does. I can't seem to find anything similar for mkdocs.

Ah, interesting. I could have a go trying similar things with mdbook tomorrow to see if it's more useful. 🤔

[clux]

Alright, I've goofed around a bit with mdbook it's not as good. It does have the benefit of providing runnable (playground) rust snippets and the ability to hide imports from the example snippets, but that's the only real benefit AFAIKT. Design, customizability, markdown cross-linking, navigation, media queries, headers, footers, social links, stuff that makes the website feel more like a website and not just a markdown dump is all better with mkdocs-material.

I would have considered mdbook more still if we could actually use it the doc testing properly though. But this 3 year old open issue is the nail in the coffin for me for trying to use it: rust-lang/mdBook#706. Without it, tests won't work, and runnable snippets won't work.

[nightkr]

Oof, yeah that test issue seems pretty bad. :/

[clux]

Given the general thumbs-up here, I'm going to move ahead with this original setup and spend some time on the weekend trying to make it as nice as possible. Will make a follow-up issue on potential future doc-testing, plus a thing on DNS setups.