Awesome
wikirefs
<p align="center"> <img src="./wikirefs.svg" width="300" height="300"/> </p>A collection of utilities to parse, process, and edit [[wikirefs]]
.
šø Weave a semantic web in your š WikiBonsai digital garden.
Install
Install with npm:
npm install wikirefs
Use
import * as wikirefs from 'wikirefs';
let res = wikirefs.scan('[[wikilink]]');
Syntax
See ./spec
for syntax spec (esp. the README.md
).
Function API
Function utilities for editting [[wikirefs]]
.
See ./src/lib/func
for more on functions.
mkdnToWiki(content: string, opts?: ConvertOpts): string
In the given content
string, convert [markdown](links)
to [[wikirefs]]
and ![markdown](img-embeds)
to ![[wikiembed-images]]
. File extensions are preserved for media.
Options:
opts.kind: 'wikiref' | 'wikilink' | 'wikiembed'
: target specific wikiref constructs for conversion (attr
s are implicitly included in link
s).
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.
renameFileName(oldFileName: string, newFileName: string, content: string): string
For all references in a given content
string which point to an oldFileName
and rename them to the newFileName
; ignores escaped instances.
Parameters
oldFileName: string
The old filename string to be removed.
newFileName: string
The new filename string to be added.
content: string
The content string to make the file rename.
retypeRefType(oldRefType: string, newRefType: string, content: string): string
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.
Parameters
oldRefType: string
The old reftype string to be removed.
newRefType: string
The new reftype string to be added.
content: string
The content string to make the retype (rename).
retypeAttrType(oldAttrType: string, newAttrType: string, content: string): string
For all attribute types in a given content
string which match the given oldAttrType
, rename them to newAttrType
; ignores escaped instances.
Parameters
oldAttrType: string
The old attrtype string to be removed.
newAttrType: string
The new attrtype string to be added.
content: string
The content string to make the retype (rename).
retypeLinkType(oldLinkType: string, newLinkType: string, content: string): string
For all link types in a given content
string which match the given oldLinkType
, rename them to be newLinkType
; ignores escaped instances.
Parameters
oldLinkType: string
The old linktype string to be removed.
newLinkType: string
The new linktype string to be added.
content: string
The content string to make the retype (rename).
scan(content: string, opts?: ScanOpts): (WikiAttrResult | WikiLinkResult | WikiEmbedResult)[]
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.
wikiToMkdn(content: string, opts?: ConvertOpts): string
Convert [[wikirefs]]
to [markdown](links)
in a given content
string.
In the given content
string, convert [[wikirefs]]
to [markdown](links)
and ![[wikiembed-images]]
to ![markdown](img-embeds)
. 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 (attr
s are implicitly included in link
s).
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 API
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.
RGX.WIKI.ATTR
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']
RGX.WIKI.LINK
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'
RGX.WIKI.EMBED
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'
A Note On Terminology
'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'