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

dokapi

v2.0.9

Published

A Markdown-based Website generator with advanced features

Downloads

14

Readme

Dokapi

A Markdown-based Website generator with awesome features. Usage:

>npm install -g dokapi
>dokapi -i my/input/folder -o my/output/folder

Options:

  • -i or --input: path of input folder.
  • -o or --output: path to output folder.
  • -t or --type: type of desired output (site or page, default: site).
  • -w or --watch: keep running and dynamicly regenerate output when input changes (watches input folder for changes).
  • -c or --create-missing: automatically create missing referenced markdown files.
  • -r or --refresh-project: force to re-download in code project used to extract code comments (cached by default)

Features

Configuration file: dokapi.json

All paths are relative to the folder in which dokapi.json is located.

Example:

{
  "name": "My Project Name",
  "project": "[email protected]:MyOrganisation/my-project.git#my-branch",
  "variables": {
    "my.variable.1": "foo",
    "my.var.2": "bar baz"
  },
  "assets": "media",
  "numbering": true,
  "externalLinksToBlank": true,
  "siteTemplate": "site-template.html",
  "pageTemplate": "page-template.html",
  "main": {
    "content": "main.md"
  },
  "index": [
    {
      "name": "Getting started",
      "children": [
        {"name": "Downloading", "key": "download", "content": "getting-started/download.md"},
        {"name": "Installing", "key": "install", "content": "getting-started/install.md"}
      ]
    },
    {
      "name": "Audit trail",
      "content": "audit-trail.md"
    }
  ]
}
  • name (required): Name of the project (used as title of main entry);
  • variables (required): A map of variable definitions;
  • assets (required): Relative path to assets directory (used for CSS etc.), will be copied as-is;
  • siteTemplate (required): Path to HTML template used for type = "site" (multi-page);
  • pageTemplate (required): Path to HTML template used for type = "page" (single-page);
  • main (required): Description of main site entry;
  • main.content (required): Path to markdown file of main entry;
  • previousLink (default: "Previous"): Text used in link to previous entry (when type = "site");
  • nextLink (default: "Next"): Text used in link to next entry (when type = "site") ;
  • main.name (default: "Introduction"): Name of main entry in site-menu;
  • project: GitHub-style URL or relative path to source-code project;
  • skipProjectVariables: (default: false): Prevent project variables (in @dokapi comments) from being extracted;
  • numbering: Whether to use ordered (<ol>) or unordered (<ul>) tags when generating the site-menu;
  • externalLinksToBlank: Whether to open external links in a new tab;
  • index: Content structure
  • index.*.name (required): Name of the entry;
  • index.*.key: Key of the entry (when left out, will use lowercase name with all special chars replaced by hyphens);
  • index.*.content (optional if the entry has children): Path to markdown file with content of the entry;
  • index.*.hidden: Whether to hide this entry (and its potential children entries) from the site-menu (internal links to this entry will work);
  • index.*.children: Children entries to current entry;
  • index.*.children.*.name (required): Name of the entry;
  • index.*.children.*.key: Key of the entry (when left out, will use lowercase name with all special chars replaced by hyphens);
  • index.*.children.*.content (required): Path to markdown file with content of the entry;

Using variables

Defining variables in dokapi.json

"variables": {
  "version": "1.2.3"
}

will replace all {{version}} tags in all Markdown files and HTML templates.

Defining variable in your code

Declare a source project in the configuration file like this:

"project": "[email protected]:Linkurious/Dokapi.git#main"

Dokapi will extract all specially formatted comments from the code:

/**
 * @dokapi my.variable.name
 *
 * This is how to use the API:
 * ```js
 * // a code example
 * var a = 123;
 * bar b = myFunction(a, 0.5);
 * ```
 */

Using variables in markdown

All variables will be available for injection:

# Documentation about my API
This API is awesome.
{{my.variable.name}}

Special variables

Automatically defined variables:

  • entry.key: Key of the current entry (as defined in JSON file);
  • entry.title: Title of the current entry (as defined in JSON file);
  • entry.root.path: Relative path to root site directory for current entry;
  • entry.menu: Inf the entry has children, list with links to children entries;

With type = "site":

  • entry.previous: HTML link to previous entry (text can be set using config.previousLink);
  • entry.next: HTML link to next entry (text can be set using config.nextLink);
  • entry.html.body: (in HTML template only), HTML of current entry;
  • menu: (in HTML template only) HTML of current menu;

With type = "page":

  • body: (in HTML template only) HTML for all combined entries;

If you reference a code project, the following variables will be extracted from package.json:

  • package.name;
  • package.description;
  • package.version;
  • package.license;

Injecting code files in your markdown content

Keep code and text separated by leaving your code examples in files separate from your markdown file. Inject the content of a code file in your Markdown file with this easy syntax:

  • {{file:file.js}} for a <code> block;
  • {{editfile:file.js}} for a <textarea> block.

Paths are relative to the markdown file containing the reference.

Variable in injected code files are interpolated.

Sanity checks

Dokapi checks for everything that could go wrong with your documentation.

  • Checks for broken internal links;
  • Checks for missing images;
  • Checks for potentially illegal image file names (enforce safe chars and no spaces);
  • Checks for internal link collisions (multiple entries with same key);
  • Checks for broken variable references (used but not defined, defined bot not used);
  • Checks for unused code-block variables (defined in code but not used in site);
  • Checks for unused markdown files (not referenced in structure);
  • Checks for missing injected files ({{file:missing_file.js}} and {{editfile:missing_file.js}});

Input watcher

Use the -w flag to re-generate the site dynamically when anything in the input folder changes. Example:

>dokapi -i my/input/folder -o my/output/folder -w

Watched folder changed...
 * Generated in 1.00s :)

Okapis are awesome

picture of an okapi