gitbook-plugin-wikify

Wiki-like GitBook books

This package comes in two parts: a command-line tool to:

• Automatically populate SUMMARY.md with an index of all pages
• Generate directory index pages

and a GitBook plugin to:

• Insert breadcrumbs
• Check for broken links
• Check for orphaned pages

Usage

Add "wikify" to the list of plugins in your book.json:

{
    "plugins": ["wikify"],
    "pluginsConfig": {
        "wikify": {
            "lintOutput": "path/to/output.xml"
        }
    }
}

Then run gitbook install.

Building your book now requires two steps:

node_modules/.bin/gitbook-autoindex
gitbook build

You may want to add files that are automatically generated by the autoindexer to .gitignore; in which case, they should be un-ignored in .bookignore so that they're properly included in the book:

$ cat .gitignore
_index.md
SUMMARY.md

$ cat .bookignore
!_index.md
!SUMMARY.md

Directory Index

The automatically generated index page is pretty bare-bones. If you want to use your own index, create an index.md file under the directory and it will be copied as-is.

Any link to a directory will be rewritten as a link to <dir>/_index.md.

Breadcrumbs

Breadcrumbs will have this HTML structure:

<nav class="wikify-breadcrumbs">
  <a class="wikify-breadcrumbs-link" href="../">Top</a>
  <span class="wikify-breadcrumbs-sep"> &gt; </span>
  <a class="wikify-breadcrumbs-link" href="_index.html">network</a>
  <span class="wikify-breadcrumbs-sep"> &gt; </span>
  <span class="wikify-breadcrumbs-static">router.md</span>
</nav>

Broken Links

Broken links are reported in GitBook build's console output in TAP format.

ok links ok in copy.md
ok links ok in retro.md
not ok link broken in README.md -> errors.md, benchmark.org, tooling.md

Orphaned Pages

Orphaned pages are reported in the lintOutput file, if specified, in jslint's XML format.

<?xml version="1.0" encoding="utf-8"?>
<jslint>
  <file name="learning.md">
    <issue line="1" char="1" evidence="learning.md" reason="weak discoverability: no page links to this page" />
  </file>
</jslint>