How should plugin docs be published?

This is a question for both plugin authors and those who use Caddy with plugins.

The new website will allow plugin authors to deploy and update plugins on their own – no need to wait on me to update things. This is already finished locally, and working well. But I haven’t figured out what to do about docs. (Meaning, pages like https://caddyserver.com/docs/git)

Right now, docs are updated by sending in a pull request, then I have to merge it, then I have to re-deploy the site at some point. This flow doesn’t get along with with automated deploys because it’s hard to keep things in sync.

My suggestion:
How about if plugin authors publish docs themselves? It could be the readme on their repository or they could link to a homepage for the plugin. The Caddy website will still link to those docs – maybe even show them in an iframe (ewww, I know, just an idea though) – so you could still find what you need from the Caddy site.

I thought about a standardized way of having plugin authors publish docs that fit neatly into the Caddy website but the variety of plugins is too great – for example, the CoreDNS plugin could have several pages, even its own “sub-site” of sorts – and enforcing consistency can be a struggle because nobody likes writing HTML.

I want to keep the site and the whole thing really simple and autonomous. I think my idea will allow for that, it just loses some consistency. (Standard Caddy directives and functionality will still have consistent, high-quality, easy-to-read documentation with examples, don’t worry.) What are your thoughts?

1 Like

A few thoughts:

  1. I am a strong believer in keeping the docs in the same repo as the code. It allows code changes and the accompanying doc changes to be included in the same PRs. That method is much more likely to stay in sync than if you have seperate docs.

  2. As much as possible, the docs on caddyserver.com should be for the same version of the plugin that the build server is currently serving.

Are the build server and caddyserver.com on the same host? I am assuming so.

My proposal would be this:

  1. Each plugin repo includes docs as a single, simple markdown file. Could be readme.md, or something else, like docs.md.

  2. When registering a plugin in the dev portal, you define which file in the repo to use as docs.

  3. When the build server pulls a new version of a plugin, it copies the doc file into the caddyserver.com folder so that it can be served, likely with some shared template applied. You can add some front matter from the dev portal info to fill out the “external repo” banner on the top of the page, and some stuff like that.

1 Like

Enabling directories of docs could be done by requiring a docs.md file by default aka single page doc, which is published on caddyserver.com.

For plugins (coredns) with multiple pages one could just provide a directory docs. All files would get pulled in and served under the plugin directory on caddyserver.com.

default:
$plugin/docs.md → caddyserver.com/$plugin/

multi page:
$plugin/docs/index.md → caddyserver.com/$plugin/
$plugin/docs/details.md → caddyserver.com/$plugin/details/

1 Like

I’m sorry I don’t have any input on implementation, but I do feel that if you distribute a plugin from the main website, you should have the docs for it on the same website. Each version of the plugin and the docs for that version of the plugin should go hand in hand.

1 Like

This is good feedback so far, thanks.

Embedding these markdown files into the Caddy website would hardly be easy, though. Sure, I can apply a common style sheet and hope for the best, but consistency would still be an issue. (We can give a template, but there are going to be several different types of plugins…) and the owner would be responsible for navigation/linking as well.

I agree on both these points. I could leave it up to the owner to make sure that when they do a new deploy of the plugin, their docs are also up to date at that time. Your proposal seems the same as @stp’s but his allows for multi-page docs.

One issue I do have with embedding plugin docs directly is the security implications…

So it’s not enough to just link to the docs?

Pulling in the docs to the main site will be very complicated and risky, unless we can find a really simple, safe way to do it.

I mean, I think it would be, if you were just linking to the plugin, too. Isn’t the Caddy website going to be hosting the plugins, though?

What kind of process is involved in the authors updating the plugins, exactly? Isn’t that a similar risk? There’s very little an .md file could do, except maybe be vandalised by its own author, right?

1 Like

Possible attacks I can think of:

  1. Vandalism, Porn, or other inappropriate content on their own plugin page.
  2. Malicious javascript inside the markdown.

Number 2 may be solvable by some judicious regex, but I think it really comes down to needing some degree of trust. Was your plan really to give anyone who uploads a plugin a page on caddyserver.com? I would suggest vetting each plugin that gets included in the official registry, and then trusting the author.

Perhaps an additional page could list all uploaded plugins and link out to the repos. Maybe with a “now leaving caddyserver.com” type message.

1 Like

Maybe some real life examples of similar things and ideas to take away:

  • nginx 3rd party modules - basic link page. Hard to be discontent with, but there is a wide variation in quality of the various readmes.

  • HAProxy - no central list at all. googling finds me some things that look interesting, but it is super frustrating to not have a central directory.

  • factorio mods. Each mod has its own page with content that is obviously provided by the author.
    Perhaps a separate plugins page would make sense, so they do not risk getting confused with “official” plugins.

  • minecraft mods- a free-for-all forum is a horrible format for listing and distributing mods.

  • telegraf side nav links to markdown docs. All in same repo, but the effect is similar to what you describe. My issue is that leaving the main site kinda breaks my will to explore. Especially if I switch tabs or something and forget where the main listing was.

Overall the current caddy look and feel looks the most seamless to me. May not be super scalable once too many plugins get added. A secondary listing might be nice though. It should be pretty clear that it is user submitted content. I do like the feel of having them in the main site with the same theme.

Perhaps some moderation system? I know matt is pretty active and would certainly check changes quick. A simple “recent changes” admin view with a verify/remove and 2-3 trusted mods who can respond quickly to abuse would likely be sufficient. Unless you have really dedicated trolls.

2 Likes

It’s complicated. :wink: Technically, GitHub (or whatever git hosting service) hosts the plugin, the Caddy website just does builds. It just maintains a glorious cache of source code so it can do faster builds than running go get every time like most CI systems. The Caddy website is just an easy way of getting a certain Caddy build, it doesn’t itself host anything other than the core Caddy docs. Which is kind of why, as I discuss this more now, I think the plugin docs should also be separate.

Updating plugins isn’t risky AFAIK. But hosting docs… well, Craig touched on this already before I could get around to it.

I’ve given this some thought, too, when I started the task.

I kind of consider these the same type of risk: unwanted content. I can’t disable HTML parsing in Markdown since it would be impossible to format/color syntax examples properly without HTML (and restricting to a specific subset of HTML is tedious).

This brings up another good point though. If I display something on the official Caddy website at the caddyserver dot com domain name, it looks like I (or the project) endorse/sponsor it even if it’s 3rd party. I know I can say “This is third party, I’m not responsible” but I feel like it’s still a liability and people would say “Yeah but it’s on your site”. Whether it’s something malicious, low quality, or offensive, doesn’t really matter – I wouldn’t want it on the Caddy site.

Now, not hosting the docs doesn’t solve this problem either; you could put unwanted text in the description or name of the plugin, for example, but at least this is limited to just plain text. There are other attacks you could do against the build server – you could DDoS the site, for instance. At some point I just have to trust people to have some integrity.

On the flip-side, embedding content on the Caddy site doesn’t mean that it’s going to be consistent, or high-quality, or up-to-date either. I’m not sure how to enforce that without tedious, manual reviews. So it’s still up to the plugin developer to just do a good job. But I think so far everyone has. :slight_smile:

And for now, I don’t have a reason not to trust this community. I think we’re all here trying to make the Web a little bit better, a little bit safer. I see no need to enforce content moderation and delay things by manual reviews unless it becomes a problem.

I’ve gone beyond what you were originally talking about in the discussion but I wanted to jot these notes down anyway.

@captncraig – excellent comparison of some various models used by other projects. I’m not exactly sure yet which way the Caddy website will go – definitely not the way of Minecraft forums or HAProxy. I think we need more than simply side-nav links like telegraf has.

We can probably have a Plugins section of the docs where plugins are listed by type, alphabetically by name. Each plugin can have a page that is generated from metadata the database has about it: name, source repository, author, release date and version, description, and even examples, but then a link to the full docs off-site.

I think we could format examples for each plugin by having a one-liner description, then a textarea where they can input code (Caddyfile, or command line args, whatever is appropriate for their plugin type) and we can make it so plugin authors can publish any number of examples that are displayed on the website. This way, you don’t have to leave the Caddy site to use plugins unless you want a more in-depth look. But if you can get up and running by examples, why not?

1 Like

So, given the discussion up to now, how about this for plugin docs:

  • We store metadata as provided by the plugin’s source code (we do some static analysis directly on the code to get name and type of the plugin) and the developer. Name, type, description, release date, version, author, etc.
  • We also store examples as provided by the developer: a list of description-example pairs, that we can show directly on our site so people can get up and running quickly without leaving it.
  • We provide a page for each plugin with all the information we have about it, including featuring the description and examples.
  • We link to the full plugin docs which are stored off-site if people want to dive deeper.

The Download page will also list all plugins and their descriptions, and maybe we can highlight some plugins on the Features page too.

Sound good?

2 Likes

Sounds great!

Not directly related, but how will you decide which version of a plugin to build with? Are you planning to just always build with master?

What if the author specified a specific commit to use? Then updates would be more explicit.

Also, what if caddy makes breaking changes to the plug-in API again? When every plug-in had to update for .9, it created some timing issues. You needed the old version as well as one ready to go for the new caddy.

Nope.

The author will provide a branch, commit, or tag to deploy such that the build server can do git checkout <version> – so anything you can put into git checkout you can use as a release point.

The website will, for now, just build the latest release. But the build worker is capable of building any commit, tag, or branch; the developer portal (website backend) will keep track of releases and tell the build worker which one to make.

Oh, GitHub webhooks are also in the works. May not be immediately available but the groundwork is there. With these, you could deploy with a bush to a branch or a new GH release.

I’ve designed the system such that Caddy deploys are never blocked if plugins fail to build with it. If I can find a clever way to notify plugin authors that their plugin just broke against the latest Caddy deploy (hopefully it won’t involve parsing go build or go test output), then they’ll get automatic notifications.

It won’t be perfect at first. Plugins that are broken due to a Caddy update will probably still appear on the download page, but the builds will fail. I think I can at least notify plugin authors saying, “Hey, just so you know, a build that contained your plugin failed at this timestamp with this configuration: OS, arch, etc…”

Right now I just wanna get something up and running. :slight_smile: