indiekit
indiekit copied to clipboard
getindiekit
Improve documentation for `postTemplate` and `properties`
Is your feature request related to a problem?
Providing type files can help with plugin development.
Describe the solution you’d like
Indiekit has JSDoc comments, but does not generate type files.
Type files can be generated by tsc and exported via package.json exports or types / typesVersions field.
Describe alternatives you’ve considered
No response
Additional context
No response
I don’t want to go down the road of converting this project to TypeScript (a language whose spread is akin to a virus IMHO), but if providing types can be a fairly non-intrusive task that builds files and includes them in the published packages, certainly worth investigating!
Are types useful from a plug-in development perspective? How would they help, precisely?
You don't need to convert your project to TypeScript. tsc can generate variable files from JSDoc.
The most intuitive bit is postTemplate, which has to deal with an object called properties, which I can only guess at by reading existing plugins.
You don’t need to convert your project to TypeScript.
tsccan generate variable files from JSDoc.
Sorry, I wasn’t clear; I assumed this was the case, was more thinking of this being a step on the slippery slope towards doing so!
Part of the reason for using JSDoc (and more recently adding .jsconfig.json to enable type checking), is to have all the benefits of TypeScript without introducing the complexity, namely compilation and code inscrutability. If the JSDoc documentation can benefit others building plug-ins, then I’m all for it!
If you wanted to submit a PR, then I’d happily review it and include types in the next release 😀 Otherwise, it might be a while until I look into this.
Also worth mentioning that, while most properties can be defined, these can be anything sent by a Micropub client. So for example, Indiekit doesn't have support for watch-of, which clients like Sparkles send for movie posts.
If you wanted to submit a PR, then I’d happily review it and include types in the next release 😀 Otherwise, it might be a while until I look into this.
Unfortunately, as I'm not very familiar with tsc (and the fact that I use TypeScript in almost every project), I'm afraid there's nothing I can do about it.
Okay, no worries. If only for my own reference, this seems to be a good overview of how to enable this: https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2
Been looking at this again. While I can configure TypeScript to output definition files from JSDoc, the files generated mostly contain gibberish, even by TypeScript standards. It’s also a lot of files to be distributing without really understanding what they contain or achieve.
I could manually write some definition files, but that’s a lot of time/effort, and without an automated workflow, likely to fall out of sync.
Whenever I delve into the world of Typescript, all I find is bugs and issues, most of which are hard to workaround if only using JSDoc to document types.
Perhaps there are other options for publishing types (I’ve experimented with JSDoc parsers before, with varying success). And as to properties on postTemplate, I fear it would ultimately come down to being marked as any (these are mf2 properties for given post types, which are documented elsewhere and in part depend on community usage/adoption).
Going to close this issue. Feel free to open if you have any other ideas for how documentation for Indiekit can be improved for plugin authors.
@paulrobertlloyd
I know this is closed, but hopefully I can add a tiny bit of useful color here as someone trying to stand up IndieKit.
My own website uses custom SSG tooling that I built a long time ago and sort of keep limping along. None of IndieKit's default post templates (for jekyll/Hugo/etc) work out of the box for me, so I set off to build my own.
This was made harder by the lack of a concrete type declaration for the postTemplate method. What exactly do the properties sent to this method contain? I looked at the Jekyll example to get an initial sense, but it took a little console.log-ing to get to the point where I had everything connected the way I wanted for my own blog tooling. (The doc comments suggest that these are "JF2 properties" but I haven't dug enough to find out what that means, or if a definition exists elsewhere.)
Where IndieKit interfaces with another software developer, and that software developer is expected to write some javascript, types might be very handy — both for initial development, and for assurance when upgrading IndieKit that assumptions about the shape of those types still hold.
Barring full adoption of TypeScript, JSDoc comments with more complete types (beyond just properties is an object) might be a good middle ground that avoids new tooling for IndieKit while giving modern editors a leg up in type inference. (I have less familiarity with the capabilities/limitations there, alas.)
Hi @davepeck, thanks for confirmation that this is an area where the documentation can be improved. Good information to have. A few small things to note:
None of IndieKit's default post templates (for jekyll/Hugo/etc) work out of the box for me, so I set off to build my own.
I’ve made a few changes to those presets that will be released in the next beta release. Currently those presets dictate which properties can be sent to a post template, and these assumptions have been removed in #680 and #685.
If you take a look at the Jekyll preset now, for example, you’ll see that while it still accepts a properties object, apart from changing keys to known Jekyll equivalents (i.e. title → name, date → published), the post template does little else. Not sure if this helps for your particular use case, but worth noting.
What exactly do the properties sent to this method contain?
That short answer is: pretty much anything! For example, a simple note post may provide the following properties:
{
type: "entry",
content: {
text: "Hello, world",
html: "<p>Hello, world</p>"
},
published: "2024-02-26T21:00:00Z"
}
while a more complex post might contain the following:
{
type: "entry",
content: {
text: "Haunted by the soundtrack from *All of Us Strangers*.",
html: "<p>Haunted by the soundtrack from <em>All of Us Strangers</em>.</p>"
},
"jam-of": {
type: "cite",
url: "https://music.apple.com/gb/album/the-power-of-love/1365569059?i=1365570236",
name: "The Power of Love",
author: "Frankie Goes to Hollywood"
},
published: "2024-02-26T21:00:00Z",
"post-status": "published",
category: ["soundtracks"]
}
It really does depend on the post type and the content being published and I’m not sure how types would be able to tell you much beyond Object!
The doc comments suggest that these are "JF2 properties" but I haven't dug enough to find out what that means, or if a definition exists elsewhere.
Gah! I’ve fallen into the trap I’ve been trying to avoid with this project, which is too not assume knowledge of the in-and-outs of various IndieWeb protocols, standards and conventions. Clearly this is proving easier said than done. 😔
In short, JF2 is a serialisation of mf2 (Microformats), which in turn is a serialisation of Microformats that can be added to HTML. Or put another way, a standard way to represent common post properties, designed in a way that can be easily processed and stored.
Do you have any suggestions how I could improve the documentation to explain how JF2 properties are structured, stored and saved out to templates?
JSDoc comments with more complete types (beyond just properties is an object) might be a good middle ground that avoids new tooling for IndieKit
If you look throughout the rest of the code base, this is what I’ve tried to do, although doubtless it could be improved. I’ve not documented any custom interfaces, but open to the idea of doing so, especially where it is useful to users and plugin developers.
In short, JF2 is a serialisation of mf2 (Microformats), which in turn is a serialisation of Microformats that can be added to HTML
Ah, excellent -- I knew I'd run across JF2 before in my Indie Web wanderings but couldn't put my finger on it. Even just including a link in the right place (thanks!) is super helpful from a documentation perspective.
It really does depend on the post type and the content being published and I’m not sure how types would be able to tell you much beyond Object!
Yeah, no doubt a challenge. There are probably a core set of types that are in common enough use to be valuable as a baseline. As post types get more exotic/custom it seems less useful, I suppose.
You're right that great documentation would go a long way. Where different post types are concerned, simply writing that documentation may make the typing situation a little clearer.
In any case, thanks for all the awesome work you've done here; I'm still enjoying poking the tires. (And for your work on the IndieWeb wiki too -- very nice design updates.)
Made quite a number of updates to the documentation accompanying the release of v1.0.0 Beta 8. Hopefully these address some of the issues raised here.