npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@gasket/plugin-docs

v7.0.6

Published

Centralize doc files from plugins and modules

Downloads

1,090

Readme

@gasket/plugin-docs

The plugin enables the docs command, which centralizes doc files for the app's plugins, presets, and supporting modules.

Installation

npm i @gasket/plugin-docs

Update your gasket file plugin configuration:

// gasket.js

+ import pluginDocs from '@gasket/plugin-docs';

 export default makeGasket({
  plugins: [
+   pluginDocs
  ]
});

Configuration

To be set in under docs in the gasket.js.

  • outputDir - (string) Name of the directory, relative to the app's package, where doc files will be collected to. Default is .docs.

Commands

docs command

The docs command, inspired by cargo doc from the Rust language, allows app developers to generate documentation for their Gasket projects. Only those presets and plugins that are configured for a project, will be used to determine what documentation is available.

When running this command, markdown and other files will gathered from installed node modules and collated to the output directory when they can be viewed together.

Lifecycles

docsSetup

The docs command will assemble configuration for plugins and modules, based on available metadata, enabled by the @gasket/plugin-metadata.

By default, the files that are collated include a package's README.md and any files that exist under a docs directory. Additionally, if any metadata defines link, these files will be collected, too.

The docsSetup lifecycle allows plugin developers to tune the docsConfig that is compile for their plugin. Files or file globs can be set, and links changed as needed. Any lifecycle hooks should return a docsSetup object. The defaults are an available option to reference.

Example setup

/**
 * @typedef {import('@gasket/plugin-docs').DocsSetup} DocsSetup
 */

export default {
  name: 'example',
  hooks: {
    /**
    * Tune the docsConfig that is compiled for a plugin
    *
    * @param {Gasket} gasket The Gasket API
    * @param {Object} defaults The default docs setup config
    * @returns {DocsSetup}
    */
    async docsSetup(gasket, { defaults = {} }) {
      return {
        ...defaults,
        link: 'OTHER.md',
        files: [
          'API.md',
          'docs/**/*.md'
        ],
        transforms: [{
          test: /\.md$/,
          handler: content => content.replace('something', 'nothing')
        }],
        // collate docs for any supporting modules
        modules: {
          '@some/module': {
            link: 'README.md'
          },
          'another-module': {
            link: 'README.md#go-here',
            files: ['html/**/*.html'],
            transforms: [{
               test: /\.html$/,
               handler: content => content.replace(/everything/g, 'nothing')
             }]
          }
        }
      }
    }
  }
}

Transforms

Transforms can also be added in the docsSetup lifecycle. These are plugins to adjust content for files that match the transform's test RegExp. By default, these will only affect docs collected the plugin's package. If the transform should be able affect all collected docs, the global property should be set to true.

Additional data is available to handlers to help with transformations which can be read about in the docsTransformHandler API.

Modules

Beside docs for the plugin itself, docsSetup for supporting modules can also be described. For modules from metadata, if a docsSetup is found, the files described will be collected, and link for the generated index go to the link specified in the docsSetup, instead of the module's homepage.

Alternatively, modules can described their own setup in their package.json by defining a gasket.docsSetup property. However, Being JSON, transforms or other setup functions cannot be described this way:

{
  "name": "example",
  "version": "1.2.3",
  "gasket": {
    "docsSetup": {
      "link": "OTHER.md#go-here",
      "files": [
        "more-docs/**/*.*"
      ]
    }
  }
}

docsView

Allows a plugin to provide a view of the docs for the user.

Example viewer

import view from 'example-markdown-viewer';

export default {
  name: 'example',
  hooks: {
    async docsView(gasket, docsConfigSet) {
      const { docsRoot } = docsConfigSet;

      await view(docsRoot);
    }
  }
}

The @gasket/plugin-docusaurus hooks this lifecycle, to render the docs using Docusaurus.

docsGenerate

Allows a plugin to add documentation that has to be programmatically generated.

An example graph

import { promises as fsPromises } from 'fs';

const { writeFile } = fsPromises;

export default {
  name: 'questions',
  hooks: {
    async docsGenerate(gasket, docsConfigSet) {
      await writeFile('FAQ.md', 'Just shoot me a call at (605) 475-6968');

      return {
        name: 'FAQ',
        description: 'Frequently Asked Questions',
        link: '/FAQ.md',
        targetRoot: docsConfigSet.docsRoot
      };
    }
  }
}

Usage

Presets

Presets can also set up custom docs. This is done by defining a docsSetup property object on the module, which will be used to establish the docsConfig for the preset.

// gasket-preset-example.js
export default {
  name: 'gasket-preset-example',
  docsSetup: {
    link: 'OTHER.md#go-here',
    files: ['more-docs/**/*.*'],
  }
}

How it works

The docs command will gather info about plugins and modules from their metadata and docsSetup, and will assemble a docsConfig for each. These configs are are organized by type in a docsConfigSet, which is then used to copy files to the outputDir, and perform any transforms as needed. An index is generated in markdown from docsConfigSet which serves as the entry in the doc files. If a plugin is installed that hooks the docsView lifecycle, it can serve the content in a more viewable fashion for the user.

License

MIT