Responsive and friendly Documentation page

[saintmalik]

Checklist

• Are you running the latest v2 release? The list of releases is here.
• Did you check the manual for your release? The v2 manual is here
• Did you perform a search about this feature? Here's the Github guide about searching.

What problem does this solve?

A clear and concise description of what problem this feature would solve. For example:

• It makes it easy for users to consume the guides about this open source project

Solution description

A detailed description of what you want to happen.

Having a docs.domain.com or domain.com/docs page is really great and gets very fast accessibility to users.

[meatballhat]

FYI fellow @urfave/cli and @urfave/maintainers folks, I squatted urfave.org (via dnsimple) with intent to experiment with docs hosting. If interested, I'm ready to do stuff like adding a .github repo and doing CNAME things or whatever is needed.

[saintmalik]

Sure, I am interested

[rliebz]

I've had some success with mkdocs and GitHub pages in the past. My criteria were being able to write plain markdown, having a simple build process I could replicate locally and in CI, having minimal configuration.

For reference:

• The docs: https://rliebz.github.io/tusk/
• The config
• The documentation (notably the README and contributing guide are symlinked to avoid duplication)
• The CI job (should be easy to do with GH actions, and support for GH pages is built in)
• mkdocs serve to get a local server going
• Contributing is just plain old markdown if you don't want to mess around with the mkdocs CLI

The executable you can get with pip or homebrew, and if you don't care about downloading a fancy not-built-in theme, that and a working python environment are the only dependencies.

I looked at a couple other tools a few years back when I set that up, and typically the things that pushed me away were complex configs or needing to check in HTML/Javascript/etc. to get a basic "hello world" up, whereas mkdocs was very tightly designed for the exact use case I had—having markdown and wanting a documentation page.

[saintmalik]

Yeah, mkdocs is also great and awesome, but have you checked docusaurus? its less complex and easy, little to no configurations and you can spin it up locally via cli too, and a simple docusaurus serve will get it up.

The easiness and nice design is a great thing to also consider.

[meatballhat]

@saintmalik Are you up for proposing something using docusaurus in a PR?

[dearchap]

I think mkdocs should be good enough. docusaurus is js which is not my cup of tea

[saintmalik]

@saintmalik Are you up for proposing something using docusaurus in a PR?

Yeah sure, am up

[saintmalik]

I think mkdocs should be good enough. docusaurus is js which is not my cup of tea

Yeah I understand,

If you don't like docusaurus because it's js based, it's okay, mkdocs is okay too

[meatballhat]

@saintmalik Are you available to take a look at #1392 ?

[saintmalik]

@saintmalik Are you available to take a look at #1392 ?

Yeah, on it