nonplain-md-backlinker

nonplain-md-backlinker

Generate backlinks for nonplain files.

What this package does

Groups of related markdown files often link to one another. This is especially true for groups of files that contain notes (e.g. VimWiki) or documentation.

Links between files reflect conceptual relationships between those files, but links are uni-directional by default (they only go forward, not backward).

The concept: make it easy to generate backlinks for individual files in a nonplain Files instance.

Usage

backlinker(files [, options]);

The backlinker function exported by this package will automatically generate backlinks for all files in a Files instance and inject them into each File's metadata as backlinks.

To generate backlinks for a group of files that link to each other, load those files into a nonplain Files instance and then pass that instance to the backlinker function.

Example:

const Files = require("nonplain").default;
const backlinker = require("nonplain-md-backlinker").default;

const files = new Files().load('/path/to/dir/**/*.md');

backlinker(files);

console.log(files.collect());

// Output:
//
// [
//     {
//         "body": "This is the body of\nthe first file",
//         "metadata": {
//             "backlinks": [
//                 {
//                     "file": {
//                         "root": "/",
//                         "dir": "/path/to/dir",
//                         "base": "file2.md",
//                         "ext": ".md",
//                         "name": "file2"
//                     },
//                     "title": "My file 2"
//                 }
//             ],
//             "file": {
//                 "root": "/",
//                 "dir": "/path/to/dir",
//                 "base": "file1.md",
//                 "ext": ".md",
//                 "name": "file1"
//             },
//             "title": "My file 1"
//         }
//     },
//     {
//         "body": "This is the body of\nthe second file",
//         "metadata": {
//             "backlinks": [
//                 {
//                     "file": {
//                         "root": "/",
//                         "dir": "/path/to/dir",
//                         "base": "file1.md",
//                         "ext": ".md",
//                         "name": "file1"
//                     },
//                     "title": "My file 1"
//                 }
//             ],
//             "file": {
//                 "root": "/",
//                 "dir": "/path/to/dir",
//                 "base": "file2.md",
//                 "ext": ".md",
//                 "name": "file2"
//             },
//             "title": "My file 2",
//         }
//     }
// ]

API

• files: Files instance - An instance of nonplain.js' Files class.
• options:
  • keyFn: function ((directory, path) => fileKey) - Customize the function used to identify each file so that its backlinks can be identified. By default, the absolute filepath (minus extension) is used.
  • metadataProperty (default: 'backlinks'): string - Customize the property on the metadata object to assign the backlinks array to.

Related work

• Core nonplain library for JS: nonplain.js
• Tools for markdown links in nonplain files: nonplain-md-link.js

Contributing

If your use-case requires specific functionality from this library, please contact me and we'll see what we can do together. Thanks!