@uzufly/starlight-lit-doc v0.1.1

@uzufly/starlight-lit-doc

Starlight plugin to generate documentation from Lit components using the CEM analyzer project.

This package is part of the Uzufly documentation system (see the main readme to obtain more information).

Current state

Given a set of globs and a destination folder. The plugin:

1. produces a manifest for each item found at the resolved glob paths.
2. selects all custom elements from the manifest.
3. produces a markdown file per custom element with support for an optional @example tag (files are written in the destination folder)
4. adds the destination folder content to starlight's sidebar content
5. exposes a watch option which reruns the process when a source file change is detected

Usage

Install the plugin in a Astro project containing the Starlight integration.

$ npm i @uzufly/starlight-lit-doc 

Add the plugin to the starlight configuration and specify the configuration options. For example:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import uzuCemAnalyser from '@uzufly/starlight-lit-doc';

// https://astro.build/config
export default defineConfig({
  integrations:[
    starlight({
      title: "starlight-lit-doc demo",
      plugins: [uzuCemAnalyser({
        globs:["../custom-elements-sample/**/*.js"],
        destination: "elements",
        watch: true
      })]
    }),
  ],
});

This example generates documentation for all the expanded paths defined in the globs key.
It will write the generated files in the src/content/docs/elements folder (destination key). Since the watch key is present and true, any changes to the files defined by the glob set will trigger a regeneration of the documentation.

A formal description of the config format:

interface CemAnalyzerPluginConfig
{
  globs: string[]     // a set of globs to be transformed
  destination: string // destination folder with respect to starlight's docs folder 
  watch?: boolean     // if present and true watch the set of globs for changes
}

See the demo folder for an example project using this plugin.

TODO

• find better (simpler) name -> @uzufly/lit-doc ?
• simplify type names
• use the contents of the @example tag as the basis for an interactive representation (playground feature).
• allow for some form of hierarchical structure in the destination folder. This would allow for supporting documenting different packages

Status

🚧 Alpha. Work-in-progress.

References

• custom element manifest schema

License

Distributed under the Apache-2.0 license.