Note

#11ty #gruber

I've been playing around with streamlining documentation by pulling JSDoc comments straight into an #11ty website. I'll try and write it up once I get it to somewhere I'm a bit happier with.

For example, this page is partially generated based on the comments directly in the JavaScript code

https://github.com/robb-j/gruber/blob/main/postgres/postgres-migrator.ts

It's pretty cool, and hopefully makes the documentation so much closer to edit when the code itself changes, Though I think there needs to be more curatability in it.

Some screenshots so it's easier to understand:

TypeScript code reading:

/**
* A record in a postgres database containing information about a migration that has been run.
*
* ```js
* const record = {
* name: '001-add-users-table.js',
* created: new Date()
* }
* ```
*/
export interface PostgresMigrationRecord {
name: string;
created: Date;
} — A screenshot of the TypeScript code

a HTML page with the contents:

PostgresMigrationRecord (type)

A record in a postgres database containing information about a migration that has been run.

Then there is an inline code example — A screenshot of a HTML page describing the type PostgresMigrationRecord

https://gruber.r0b.io/postgres/

metadata

Open on GiHub

{
  "mastodon_status": [
    "https://social.lol/@r0b/114937421367820047",
    "https://social.lol/@r0b/114937432839964140"
  ],
  "external": [
    "https://gruber.r0b.io/postgres/"
  ]
}