[HankB99]

Not speaking for the GP. I use MkDocs and keep my personal notes. The only weak spot for me is that I haven't fully grokked search and as my notes grow, it can be harder to find things. I alternate between figuring out how search and how to bolt on some other search utility.

MkDocs includes a utility to publish to Github pages but I keep my notes on a self hosted Gitea server and serve using "python -m http".

[squidfunk]

Author of Material for MkDocs here. We're currently working on re-architecting the entire search engine and rewriting it from scratch. We're currently based on lunr.js, which is unmaintained as of 2020 and has more or less run its course. We've learned a lot what matters in respect to efficient and user friendly documentation search, and can't wait to give the first version into the hands of our users. I'm convinced that the next iteration of search we'll be releasing will solve many of the shortcomings that our current implementation has. Of course, it will work on the client side as it does now, no server needed, but there will be other options as well, e.g. for when your search index is in the megabytes and too big to ship to clients.

[HankB99]

Many thanks for your efforts here. I'll be looking into Material for MkDocs (the next time I can't find something. ;) )

[nvm0n2]

Take a look at mkdocs-material, it's not just a theme, it adds some local-side search as well. Still with fully static pages.

[dnsmichi]

The search works great. I'm using MkDocs with Material as my personal handbook because of the simplicity -- for example, I usually remember great articles in conversations but always forget their location. Since I started writing my newsletter https://opsindev.news/ including an MkDocs web archive, I can share interesting URLs way faster :) Or let folks discover it by themselves, using the search.

Configuration in https://gitlab.com/dnsmichi/opsindev.news/-/blob/main/mkdocs...

Material for MkDocs also has an insiders build, accessible through sponsorship. https://squidfunk.github.io/mkdocs-material/insiders/ These features add more value to MkDocs -- I initially joined to get GDPR-compliant cookie banners and stayed to support a great project.

[wredue]

Is this a fully collaborative tooling with self linking?

Having hundreds of out of date, and insecure word documents is a dismal affair when you get a call in the middle of the night.

For issue resolution, documents steps are moving right in to the ticketing system for linkage to incidents. That’s fine.

For general documentation though. It doesn’t belong in the ticketing system and what a pain in my ass.

[HankB99]

If I understand your question, it's a lot simpler than that. (Simpler as in not that functional.) It represents the directory structure as cascading menus.

I edit using VS Code and it provides help with linking from one document to another, including navigating to the file and even linking second level ('##') headings. MkDocs can report broken links when it builds the site.

Collaboration could be through sharing a Git repo. Perhaps other other ways I can't think of at this moment. Any way you could collaborate editing text files should work.

[gwright]

Has anyone identified an easy/feasible way to add SSO authentication to github pages?

[kosikond]

OTOH couldn't it be done with Cloudflare Zero Trust ?

Have the GH Pages (sub)domain proxied with CF, protect the URL with Zero Trust, for SSO itself there are several IdP available [0]. First 50 users are not billed.

[0]https://developers.cloudflare.com/cloudflare-one/identity/id...

[TheNewsIsHere]

I haven’t tried doing this, although I’ve thought of it to solve a similar problem, which I ultimately solved by not bothering and just letting GitHub render the docs. (Purely internal technical use cases, so not an issue.)

I haven’t experimented, but my first attack would be to query the GH Pages service directly and specify the host header. Bypass Cloudflare entirely.

GitHub Pages supports SSO with the enterprise cloud plan, of course.

[spondylosaurus]

https://www.twilio.com/blog/keep-internal-docs-secure-okta-n...

This is one, although you'll need to use Netlify instead of GitHub Pages proper.

[kriberg]

We use azure ad for authn to our github organization. That also covers github pages generated from those repos.

[gwright]

I assume that means that every person accessing the pages also needs a github account? I don't mind a requirement for a github account for anyone contributing to the repo but I would like authenticated access for viewing the pages that doesn't require a Github account.