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

docusaurus-outline-generator

v1.0.3

Published

Docusaurus documentation outline generator

Downloads

6

Readme

docusaurus-outline-generator

Generate topic files and navigation structure for Docusaurus. It generates Markdown files and sidebars.json file from an outline object.

Installation

Install docusaurus-outline-generator globally:

npm install docusaurus-outline-generator -g

After installing it globally, the docsog command is available.

Usage

In your scripts:


const docsog = require("docusaurus-outline-generator")

// create outline object
let docProj = {
    "project": "Sample documentation title",
    "topics": [
        {
            "title": "Getting started",
            "slug": "doc1", // as first topic, use this slug
            "topics": [
                "Installation",
                "Usage",
                {
                    "title": "Topic with children",
                    "topics": [
                        "Child topic #1",
                        "Child topic #2"
                    ],
                    // Add several headers in this topic
                    "headers": [
                        "Adding sub-topics to a topic",
                        "Sub-topics of a sub-topic"
                    ]
                }
                "Updates"
            ]
        }
    ]
}

let options = {
    "topicTitleCase": true,
    "headerTitleCase": false
}

let topics = docProj.topics;

docsog.generate(topics, options);

CLI Commands

docsog provides two sub-commands: init and generate.

Usage: docsog [options] [command]

Options:
  -V, --version                output the version number
  -h, --help                   output usage information

Commands:
  init                         initialize docusaurus outline generator
  generate [options] [source]  generate topic files in docs and navigation in sidebars.json

init CLI sub-command

Run the init sub-command to initialize the folders and files the generate sub-command will use. Typically, you need to run init only once.

docsog init

This command creates template files in the templates folder, the docsog-config.json and docsog-outline.json files. The docsog-config.json contains configuration information, and the docsog-outline.json is the default outline source file. This files contains a demo outline. You can edit it with your preferred documentation outline. You can also create a different outline file and use it in generate sub-command.

generate CLI sub-command

Options for generate sub-command:

Usage: docsog generate [options] [source]

generate topic files in docs and navigation in sidebars.json

Options:
  -r, --remove                remove existing .md files in docs folder
  -d, --docspath <path>       path where documentation documents will be generated (default: "./docs")
  -t, --templatespath <path>  path to templates used during generation (default: "./templates")
  -w, --websitepath <path>    path where sidebars.json will be generated (default: "./website")
  -c, --config <file>         filename or full path to generation configuration file (default: "docsog-config.json")
  -h, --help                  output usage information

Generating Docusaurus Documentation with docsog

Prerequisites

  1. Docusaurus installed globally

Using docsog to generate documentation

  1. Create a documentation folder
mkdir documentation
chdir documentation
  1. Initialize docusaurus
docusaurus-init
  1. Initialize docsog
docsog init

This creates the topic.handlebars aad header.handlebars in the templates folder, and docsog-config.json and docsog-outline.json, which is a startup outline document. In this example, you will make no changes to this outline file. You can however, edit it to create your own outline, or create another outline file.

  1. Generate documentation based on outline file.
docsog generate

This will generate documentation files in .docs folder and will overide the website/sidebars.json file. sidebars.json contains the documentation navigation structure (see Navigation).

  1. View generated documentation outline

You will change to website folder and start the docusaurus preview server -- details at Docusaurus.

cd website
npm start

The browser will open at http://localhost:3000. Click Docs in the top navigation bar to see the documentation.