RFC: Putting code, tests and docs of plugins next to each other

[not-my-profile]

The files making up a plugin are currently scattered across three different locations:

• plugins/ in the lume repository contains the actual code, e.g. plugins/katex.ts
• tests/ in the lume repository contains the test code, e.g. tests/katex.test.ts
• plugins/ in the lume.land repository contains the documentation, e.g. plugins/katex.md

I think it would make sense to instead put all these files next to each other in this repository, e.g. we could have:

• plugins/katex/katex.ts
• plugins/katex/katex.test.ts
• plugins/katex/README.md

The reasoning being that if you update the code, you likely also should update the tests and the documentation as well and that's easier to do when the files are all next to each other. Putting them next to each other also makes it easier to spot discrepancies. (Especially having the .md files in another repository makes contributing to plugins more difficult since you'd often need two PRs.)

[oscarotero]

Yeah, it makes sense but I can see some drawbacks:

• From users POV, it requires to repeat the plugin name in the imported url. It's clearer to import it from lume/plugins/katext.ts thank lume/plugins/katext/katext.ts.
• It's a breaking change: all sites built with Lume would break
• Tests are not only TypeScript files (like katex.test.ts) but they need assets (stored in /tests/assets) and they generate snapshots (stored in /tests/__snapshots__).
• Some plugins need other plugins to work. For example, Tailwind requires Postcss, or SourceMap is used by other plugins like Postcss, Esbuild, SASS, etc.
• We must to figure out a way to import the plugins documentation in the lume.land site if they are in different repositories.