@linkurious/dokapi

A Markdown-based Website generator with advanced features

use 'dokapi' instead
Last updated a year ago by davidrapin .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @linkurious/dokapi 
SYNC missed versions from official npm registry.

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": "git@github.com: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": "git@github.com: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

Current Tags

  • 1.1.0                                ...           latest (a year ago)

1 Versions

  • 1.1.0 [deprecated]           ...           a year ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (9)
Dev Dependencies (7)
Dependents (0)
None

Copyright 2014 - 2017 © taobao.org |