Build plugins docs during the website build#42
Conversation
_build/copy-plugins.mjs
Outdated
| } | ||
|
|
||
| let name = path.parse(file.name).name; | ||
| // Don't copy the plugin source files |
There was a problem hiding this comment.
What if instead of excluding files based on heuristics we only include README.md and demo.*?
There was a problem hiding this comment.
My first attempt was exactly what you proposed. However, later, I realized that plugin docs might depend on other files, such as external stylesheets, scripts, images, data files, etc., and we don't know what names they might have. The only thing we can be sure of, though, is that we don't want to copy the plugin source files whose names happen to end with the plugin ID. So, I decided to follow that route.
There was a problem hiding this comment.
They shouldn't though. And if they do, they can always include them via HTML in README.md. I think it's okay to restrict what plugins can do in their docs a bit if it leads to a more predictable structure and less clutter in the source repo.
There was a problem hiding this comment.
Oh, okay then. I'll fix it
| import * as filters from "./filters.js"; | ||
|
|
||
| import components from "prismjs/src/components.json" with { type: "json" }; | ||
| import components from "../node_modules/prismjs/src/components.json" with { type: "json" }; |
There was a problem hiding this comment.
Why do we need to do this? I would expect 11ty's regular collections to work just fine if we apply good tags etc (which we can do at the directory level).
There was a problem hiding this comment.
We still depend on this when building a list of supported languages on the main page and a list of languages and themes that might be included in a bundle on the Download page.
I'm planning to ditch it in the following PRs. I didn't want to work on this in this PR since it seems orthogonal.
There was a problem hiding this comment.
Sounds good. And yes, we can eventually ditch it. For plugins, we already have their readmes that should contain all their metadata as 11ty data. For languages, that would be too heavyweight, so we could follow a mixed approach: Declare their metadata at the top of the file using a doc comment (that is then picked up by our build process), and have MD files for those that want to declare more details. Then, our build tool produces MD files for the rest. These pages should also host the examples for each language, which are currently a separate app with questionable UX where you select the languages you want to see examples of via checkboxes (which seems clever, but is not how anyone looks for examples of certain languages, so it just becomes a hassle)
|
I think we are ready for another iteration. |
| /plugins/:plugin/index.html /plugins/:plugin/index.html 200 | ||
| /plugins/:plugin/demo.html /plugins/:plugin/demo.html 200 | ||
| /plugins/:plugin/demo.js /plugins/:plugin/demo.js 200 | ||
| /plugins/:plugin/demo.css /plugins/:plugin/demo.css 200 |
There was a problem hiding this comment.
I'm confused, these seem to be redirecting to themselves?
There was a problem hiding this comment.
No wonder. This looks weird, I agree. The following redirect rule also covers these cases, but we don't want to redirect those files (they live in the website repo). Due to limitations of the _redirects files, this is the only (and most straightforward) way to achieve our goal.
ChatGPT says we can try Netlify Edge functions for this. I haven't tried it yet, but I will probably do so in the next iteration.
* Add copy script * Adjust the build process * Add `_redirects` * Fix plugin URLs
2 participants
First iteration.
Depends on PrismJS/prism#3930