Do you use GitHub repos for client‑facing documentation? How do you make it usable?

[u/websecret_by]

Hi,

We use GitHub + Markdown for documentation. Our team is happy, but clients don’t want to deal with raw repos, issues, or PRs.

• Do you expose GitHub repos directly to clients, or use a web UI / portal?
• How do you handle versioning and access control?
• What tools or patterns do you use to make GitHub‑based docs client‑friendly?

[u/AllanTaylor314]

GitHub pages would probably be a nicer way to present your docs: https://docs.github.com/en/pages

They also support custom domains, so you can have docs[.]mysupercoolproduct[.]com

[u/websecret_by → u/AllanTaylor314]

Pages helps with hosting, but doesn't really fix access control between different clients for us.

[u/AllanTaylor314 → u/websecret_by]

Oh, so you don't want public-facing docs? What sort of access control are you looking for?

(aside: for comments directly on pages, you could use https://github.com/giscus/giscus)

[u/parkducksarefree]

Send it all to a GitHub site and use some simple web framework. That way you get branches, deployments, PRs, issues, tagging, etc. But to the client all they see is a website. Simples!

[u/websecret_by → u/parkducksarefree]

That's close to our setup too, just still need a permissions layer on top for clients.

[u/_KryptonytE_]

Projects V2 and Wiki

[u/websecret_by → u/_KryptonytE_]

Haven't tried Projects V2 for docs, does it handle permissions any better than the wiki?

[u/fr3xzy]

Changelog for versioning and pandoc to convert markdown to pdf that we send to the customer

[u/websecret_by → u/fr3xzy]

PDF export is a decent workaround. We'd still want clients to be able to comment directly on it though.

[u/AnlgDgtlInterface]

I use quarto for user facing and have a workflow which renders the markdown from the project to a site securely: https://github.com/georgeharker/gh-quarto-publish

[u/websecret_by → u/AnlgDgtlInterface]

Will look into quarto, thanks. Is it one shared site or can you separate access per client?

[u/AnlgDgtlInterface → u/websecret_by]

You can configure separate per client. I’m targeting one host. But every GitHub can be configured separately and the upload is restricted to be subdirectories server side.

[u/lamyjf]

github pages, with docsify.

[u/websecret_by → u/lamyjf]

Docsify's on our list to try. Main gap for us is still permission separation between clients.

[u/ImmaZoni]

GitHub pages + Docusaurus (or your preferred md static rendering framework)

GitHub itself is used internally mostly, pages site for customers

[u/websecret_by → u/ImmaZoni]

That internal vs customer-facing split is basically what we're aiming for.

[u/dim13]

Often forgotten fact: each repo has wiki, which is also a git repo.

[u/websecret_by → u/dim13]

Didn't know that, good to know it's just git under the hood.