Improve add-ons documentation

[adelevie]

I say all this with love and the hope that the project can continue to improve and thrive.

As a new user, I find the documentation surrounding the add-ons ecosystem to be confusing, and ultimately unhelpful. The add-ons present to me the most compelling use cases for Caddy. But if add-ons are not simple and intuitive, then the overall value proposition for Caddy diminishes. At least for me, so take that for what it's worth.

The current state of add-ons documentation:

I followed the wonderful tutorial "Let's Encrypt in (literally) 90 seconds". Now that I have Caddy running, I check out the docs to see what else I can do.

Oh look, a Git integration!

Ok, so I'll go to the GitHub repo to learn how to install this:

The README has no installation instructions. Ok, I'll stop ctrl-f'ing and actually read the README. Ok, nothing much, but at the bottom there is this link to BUILDING.md

I'm not much of a build from source kind of person, but what choice do I have?

So this note is more helpful. If I don't want to build from source to install an add-on, I need this thing called Caddyext. It turns out Caddyext is a bit much (for me, at least for now). Anyways, after all that (and a little more Googling), I learned that to get add-ons, you need to do at least one of the following:

• to select them in the download GUI at download time
• select them as CLI arguments in the CLI downloader/installer
• install golang and use caddyext.

These are all fine options, but there is no easy-to-find, central place where this information is communicated.

I suggest there be a section in the Caddy docs called "Add-ons" explaining this. Anyways, if you agree, I'm happy to take a first stab at this.

[mholt]

Add-ons were an afterthought, actually, but they turned out to be one of Caddy's most popular and powerful features. But because we implemented them so quickly to support some demand, we didn't think through documentation and a lot of details at the time.

Users of Caddy can find most of what they need in the Caddy docs on the website: https://caddyserver.com/docs. Caddy developers can find most of what they need in the wiki: https://github.com/mholt/caddy/wiki - including how to build and deploy add-ons.

It seems like the main issue you're highlighting is about how to get add-ons. Perhaps we could simply append to the text in the green box to say, "Select this feature on the download page to get it."

[captncraig]

As a first pass, I do think adding better instructions to that box is a good idea. Something like

"This addon is not included in the caddy core. You can download a custom binary that includes it on our [download page]"

[humboldtux]

Some interesting Wikis to take ideas from https://github.com/showcases/projects-with-great-wikis

[hacdias]

Hey all!

I have to improve the documentation of my plugin caddy-hugo but this is what I think: the documentation on caddyserber.com should be more end user directed while the info on GitHub should be directed to developers. How should I divide the information between repo's readme and caddy website?

[abiosoft]

I personally would prefer caddyserver to read the markdown on the project pages directly.

[hacdias]

Awesome idea. Why not doing that? @mholt

[humboldtux]

And something like:

caddy --examples gogs

To read from https://github.com/caddyserver/examples and test some example conf?

[mholt]

@hacdias

I have to improve the documentation of my plugin caddy-hugo but this is what I think: the documentation on caddyserber.com should be more end user directed while the info on GitHub should be directed to developers. How should I divide the information between repo's readme and caddy website?

I agree completely. So in the repo's readme, put instructions for developers, and on the website, instructions for end users. (Maybe a line at the top of the readme for end users who wind up there by accident, pointing them to the download page and/or the docs on the website.)

@abiosoft

I personally would prefer caddyserver to read the markdown on the project pages directly.

I would too, but this presents a couple problems:

• Syncing the latest changes
• Staying consistent for all directives. It's important that the docs have a consistent formatting, layout, and structure so they're easy to read.

@humboldtux That's an interesting idea; perhaps a tutorial add-on or something.

[abiosoft]

We can have compulsory format defined maybe in a separate file caddyreadme.md.

I don't have the time luxury yet but its something I will like to look into later.

[captncraig]

I made a proposal in buildsrv for something like this. My latest directive I submitted has a markdown format, although code samples are not yet highlighting in pure md. Those still need to be raw html, although I have an idea for that still. Would be really nice to keep a md file in my own repo and have something (buildsrv maybe) sync it to caddyserver.com when it updates the code versions that get built.

[mholt]

I've added a sentence in the green box on the docs explaining how to get add-ons. The whole process of deploying add-ons will be improved in the future. Thanks for the feedback!