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

@oscsa/jsquarto

v1.0.7

Published

Generate JS package API reference documentation using Markdown and Quarto. JSquarto is designed as an alternative to JSDoc

Downloads

5

Readme

Prerequisites

Before testing the tool locally, ensure you have the following prerequisites installed on your system:

Installation

To test the tool locally, follow these steps:

  1. Install the cli package from NPM:

    npm i -g @oscsa/jsquarto 
  2. Install Quarto, to do this refer to the official Quarto installation guide

  3. Install Babel quarto, refer to the official Babel Quarto installation guide

Usage

Once the dependencies are installed, you can navigate to the root directory of your project and follow the steps below:

  1. To generate the documentation run the following command

    jsq doc:generate source=<path to source files> 

    This will extract the JSDoc comments from the js files and write them to their corresponding Quarto Markdown files.

    If the source flag is not provided, the tool will set docs/source as default.

    The generated .qmd files can be found in the docs/output folder, you can change the output directory by providing the output flag.

  2. To preview the generated documentation run

    jsq doc:preview

    This will generate the documentation, preview with quarto and open a link to preview the docs

  3. The generated .qmd files can be found in the docs/output folder, you can change the output directory by providing the output flag.

    jsq doc:generate source=<path to source files> output=<path to output dir>
  4. To include tutorials in the generated documentation, provide the tutorials flag.

    jsq doc:generate source=<path to source files> tutorials=<path to tutorials directory>

Usage with Configuration File

Alternatively, you can leverage the config.json file to store your custom settings and avoid specifying them each time you run the JSquarto tool. By modifying the fields in the config.json file, you can customize the documentation generation process according to your requirements.

To use a configuration file follow the steps below:

  1. Initialize the configuration file using the command below:

    jsq config:init  

    This will create a config.json file in the .jsquarto directory within your project structure. You might have an already existing config file, for this case you can tell jsq to use this file instead by running;

    jsq config:set config=/path/to/your/directory
  2. Set the desired configuration settings in the config.json file according to your preferences. To set the source files directory run

    jsq config:set source=/path/to/your/source/files

    To set the tutorial files directory run

    jsq config:set tutorial=/path/to/your/tutorial/files

    To set the output directory run

    jsq config:set output=/path/to/your/output/directory

    To set the supported languages run

    jsq config:set languages=en,fr,es

    To include localized versions of the generated documentation run

    jsq config:set include_localized_versions=true

This will update the config.json file with the specified settings, which will be used by the JSquarto tool during the documentation generation process.

You can also manually edit the config.json file to modify the configuration settings according to your requirements.

Command summary

| Command | Description | | --- | --- | | jsq config:init | Initialize the configuration file | | jsq config:set | Set or update configuration settings | | jsq config:get | Get current configuration settings | | jsq doc:generate | Generate the documentation | | jsq doc:preview | Preview the generated documentation | | jsq doc:clean | Delete the existing docs | | jsq doc:serve | Serve html files in browser (if translation workflow is used. See) |

For more information on how to integrate translation tools like Crowdin with JSquarto, refer to the Crowdin Worflow guide.

For more details on using JSquarto and to see an example of the generated documentation, visit the JSQuarto documentation