Hacker News Reader

Comment by gwright | Hacker News Reader

Could you share what markdown/git tooling you've identified?

Sure. We're focusing first on converting everything to plain Markdown and using a Git repo to manage the content. Writers can use whatever Markdown tool they prefer for this. (I'm using Obsidian and others are iA Writer.) I have yet to decide on the docs publishing tool, but I'm testing Astro, Vitepress, and Markdoc for publishing. I'm leaning towards Astro since it's very flexible, easy to add small bits of interactivity via MDX, and has a nice collection of themes. VitePress is also very nice, super fast, and very easy to publish. Since only the developers and tech writers need to collaborate on the docs, we're following a docs-as-code approach — using GitHub issues, comments, and pull requests.

Here's some info about Astro for folks like me who didn't know about it before:

"Markdown is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files that can also include frontmatter YAML to define custom metadata such as a title, description, and tags."

https://docs.astro.build/en/guides/markdown-content/

You should take a look at foam. It's a toolchain for notes and such, similar to obsidian, but open source. It's main interface is a vscode plugin, but has HTML generators and such, as well as just being markdown, so you can use Pandoc or anything else to make HTML out of it

I wish people would link software they recommend, because it saves me a lot of confusion when they are semi obscure. I believe this is the software you are referring to? (I'm using obsidian but don't like that it's not opensource and don't like logseq, except for their journals feature so I'm actually quite interested in checking out foam) https://foambubble.github.io/foam/

Yeah that's it. Sorry for not linking it, I originally wrote that comment on mobile

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".

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.

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.

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.

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.

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

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.

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...

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.

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

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.

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.

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

For something quick and easy consider https://github.com/gollum/gollum#markups which powers Github Wikis.

Note that multi-user auth is NOT supported out of the box however.

Obsidian is a pretty good solution for this in my experience

Obsidian does not support collaboration.

It's a fantastic tool but strictly singleplayer.

I used it with a team of 10 folks at my previous job. Everyone worked in a common git repo, and with some smart usage of .gitignore, we were all able to collaborate quite effortlessly, even going so far as to push videos, images, etc to the repo with git-lfs to make the documentation rich and available. It can certainly be multiplayer with a modicum of effort.

Wouldn't be feasible for most of our users but nice to know...

Obsidian has a feature called "Shared vaults" which teams use to collaborate. You can also use a shared Git repo, or other cloud/network storage (e.g. Dropbox)

https://help.obsidian.md/Obsidian+Sync/Share+remote+vaults

Reply on news.ycombinator.com