A collection of utilities to parse, process, and edit [[wikirefs]].
🕸 Weave a semantic web in your 🎋 WikiBonsai digital garden.
Install with npm:
npm install wikirefs
import * as wikirefs from 'wikirefs';
let res = wikirefs.scan('[[wikilink]]');See ./spec for syntax spec (esp. the README.md).
Function utilities for editting [[wikirefs]].
See ./src/lib/func for more on functions.
In the given content string, convert [markdown](links) to [[wikirefs]] and  to ![[wikiembed-images]]. File extensions are preserved for media.
Options:
opts.kind: 'wikiref' | 'wikilink' | 'wikiembed': target specific wikiref constructs for conversion (attrs are implicitly included in links).
opts.format: 'filename' | 'relative' | 'absolute': how to format markdown link uris based on wikiref filenames: use a slugified filename, relative path, or absolute path of the file (paths rely on uriToFnameHash option to be provided).
opts.uriToFnameHash: Record<string, string>: a hash table explicitly defining what uri maps to what filename.
For all references in a given content string which point to an oldFileName and rename them to the newFileName; ignores escaped instances.
The old filename string to be removed.
The new filename string to be added.
The content string to make the file rename.
For all reference types in a given content string which match the given oldRefType, rename them to newRefType; ignores escaped instances.
Since 'reftypes' contain 'attrtypes' (wikiattr) and 'linktypes' (wikilink), this function will preform the operations of both retypeAttrType() and retypeLinkType() below.
The old reftype string to be removed.
The new reftype string to be added.
The content string to make the retype (rename).
For all attribute types in a given content string which match the given oldAttrType, rename them to newAttrType; ignores escaped instances.
The old attrtype string to be removed.
The new attrtype string to be added.
The content string to make the retype (rename).
For all link types in a given content string which match the given oldLinkType, rename them to be newLinkType; ignores escaped instances.
The old linktype string to be removed.
The new linktype string to be added.
The content string to make the retype (rename).
Scan a given content string and return an array of descriptions of all valid wikiref constructs. Result formats are listed below and are sorted by order of appearance in the content string based on theri start position.
Result formats:
ScanResult {
kind: string; // kind of wikiref
text: string; // match text
start: number; // match start position in content string
}
WikiAttrResult extends ScanResult {
type: [string, number] | [];
filenames: [string, number][];
listFormat: string;
}
WikiLinkResult extends ScanResult {
type: [string, number] | [];
filename: [string, number];
label: [string, number] | [];
}
WikiEmbedResult extends ScanResult {
filename: [string, number];
media: string;
}Options:
opts.filename: string: a specific filename to be targetted -- non-target-filename wiki constructs will be ignored.
opts.kind: string: specific kinds of wiki constructs may be targetted; valid options are 'wikiattr', 'wikilink', and 'wikiembed'.
opts.skipEsc: boolean: whether or not to skip escaped wiki construct instances; set to true by default.
Convert [[wikirefs]] to [markdown](links) in a given content string.
In the given content string, convert [[wikirefs]] to [markdown](links) and ![[wikiembed-images]] to . File extensions are preserved for media and may be optionally removed or left in-place for markdown files.
Options:
opts.kind: 'wikiref' | 'wikilink' | 'wikiembed': target specific wikiref constructs for conversion (attrs are implicitly included in links).
opts.format: 'filename' | 'relative' | 'absolute': how to format markdown link uris based on wikiref filenames: use a slugified filename, relative path, or absolute path of the file.
opts.ext: boolean: whether or not to include file extension in uri.
opts.fnameToUriHash: Record<string, string>: a hash table explicitly defining what filename maps to what uri.
Regex utilities for extracting wiki constructs from strings. All regexes are case insensitive and the g option may be added to find all instances of a wiki construct.
See regex.ts for more regex utilities.
Note: Since javascript/typescript regex does not support the \G anchor, filenames should be extracted from list items in the full match string. wikirefs.RGX.WIKI.BASE is a convenience regex for this purpose.
// mkdn + comma separated formats both supported
import * as wikirefs from 'wikirefs';
////
// single / comma-list...
const match = wikirefs.RGX.WIKI.ATTR.exec(`
:attrtype::[[wikilink1]],[[wikilink2]]
`);
const matchText : string = match[0]; // ':attrtype::[[wikilink1]],[[wikilink2]]\n'
const attrTypeText : string = match[1]; // 'attrtype'
// no '\G' so extract filenames manually
let fnameMatch: RegExpExecArray;
let filenames: string[] = []; // ['wikilink1', 'wikilink2']
const fnameRegex = new RegExp(wikirefs.RGX.WIKI.BASE, 'g');
do {
fnameMatch = fnameRegex.exec(matchText);
if (fnameMatch) {
filenames.push(fnameMatch[1]);
}
} while (fnameMatch);
console.log(attrTypeText, filenames) // prints: 'attrtype', ['wikilink1', 'wikilink2']
////
// mkdn-list...
const match = wikirefs.RGX.WIKI.ATTR.exec(
`:attrtype::
- [[wikilink1]]
- [[wikilink2]]
`);
const matchText : string = match[0]; // ':attrtype::\n- [[wikilink1]]\n- [[wikilink2]]\n'
const attrTypeText : string = match[1]; // 'attrtype'
// no '\G' so extract filenames manually
let fnameMatch: RegExpExecArray;
let filenames: string[] = []; // ['wikilink1', 'wikilink2']
const fnameRegex = new RegExp(wikirefs.RGX.WIKI.BASE, 'g');
do {
fnameMatch = fnameRegex.exec(matchText);
if (fnameMatch) {
filenames.push(fnameMatch[1]);
}
} while (fnameMatch);
console.log(attrTypeText, filenames) // prints: 'attrtype', ['wikilink1', 'wikilink2']Note: The wikilink regex results will include single wikiattr constructs that match successfully. To see if the result is actually a wikiattr, check that the match is followed by a newline.
import * as wikirefs from 'wikirefs';
const match = wikirefs.RGX.WIKI.LINK.exec(':linktype::[[wikilink|label]]');
const matchText : string = match[0]; // ':linktype::[[wikilink|label]]'
const linkTypeText : string = match[1]; // 'linktype'
const fileNameText : string = match[2]; // 'wikilink'
const labelText : string = match[3]; // 'label'import * as wikirefs from 'wikirefs';
const match = wikirefs.RGX.WIKI.EMBED.exec('![[wikiembed]]');
const matchText : string = match[0]; // '![[wikiembed]]'
const fileNameText : string = match[1]; // 'wikiembed''wikitext' : refers to the characters in a wikilink
that describe the link.
'wikistring': refers to all characters in a wikilink,
which includes the wikitext and the
special characters of the wikilink.
'wikitext'
👇
• <--> •
[[wikilink]]
• <------> •
👆
'wikistring'
'wikitext'
👇 👇
• <-> • • <--> •
:reftype::[[wikilink]]
• <----------------> •
👆
'wikistring'