{"id":20098369,"url":"https://github.com/wikibonsai/wikirefs","last_synced_at":"2025-07-16T18:33:17.050Z","repository":{"id":94779491,"uuid":"608227874","full_name":"wikibonsai/wikirefs","owner":"wikibonsai","description":"A collection of utilities to parse, process, and edit [[wikirefs]] (aka backlinks, bidirectional links, internal links, etc.).","archived":false,"fork":false,"pushed_at":"2025-04-11T15:04:12.000Z","size":367,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-24T23:03:50.266Z","etag":null,"topics":["backlink","bidirectional-link","internal-link","wikibonsai","wikilink","wikiref"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/wikirefs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wikibonsai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-01T15:29:22.000Z","updated_at":"2025-04-11T15:04:16.000Z","dependencies_parsed_at":"2024-07-17T22:02:30.847Z","dependency_job_id":"bca3f43d-5e46-4ba5-aac1-546719303bc2","html_url":"https://github.com/wikibonsai/wikirefs","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"51b0b01bfe5d9c3af1d83d862745836c1bfa9167"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fwikirefs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fwikirefs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fwikirefs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fwikirefs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wikibonsai","download_url":"https://codeload.github.com/wikibonsai/wikirefs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252629199,"owners_count":21779165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backlink","bidirectional-link","internal-link","wikibonsai","wikilink","wikiref"],"created_at":"2024-11-13T17:03:16.899Z","updated_at":"2025-05-06T05:32:03.854Z","avatar_url":"https://github.com/wikibonsai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wikirefs\n\n[![A WikiBonsai Project](https://img.shields.io/badge/%F0%9F%8E%8B-A%20WikiBonsai%20Project-brightgreen)](https://github.com/wikibonsai/wikibonsai)\n[![NPM package](https://img.shields.io/npm/v/wikirefs)](https://npmjs.org/package/wikirefs)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./wikirefs.svg\" width=\"300\" height=\"300\"/\u003e\n\u003c/p\u003e\n\nA collection of utilities to parse, process, and edit `[[wikirefs]]`.\n\n🕸 Weave a semantic web in your [🎋 WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.\n\n## Install\n\nInstall with [npm](https://docs.npmjs.com/cli/v9/commands/npm-install):\n\n```\nnpm install wikirefs\n```\n\n## Use\n\n```js\nimport * as wikirefs from 'wikirefs';\n\nlet res = wikirefs.scan('[[wikilink]]');\n```\n\n## Syntax\n\nSee [`./spec`](https://github.com/wikibonsai/wikirefs/tree/main/spec) for syntax spec (esp. the `README.md`).\n\n## Function API\n\nFunction utilities for editting `[[wikirefs]]`.\n\nSee [`./src/lib/func`](https://github.com/wikibonsai/wikirefs/tree/main/src/lib/func/) for more on functions.\n\n### `mkdnToWiki(content: string, opts?: ConvertOpts): string`\n\nIn the given `content` string, convert `[markdown](links)` to `[[wikirefs]]` and `![markdown](img-embeds)` to `![[wikiembed-images]]`. File extensions are preserved for media.\n\nOptions:\n\n`opts.kind: 'wikiref' | 'wikilink' | 'wikiembed'`: target specific wikiref constructs for conversion (`attr`s are implicitly included in `link`s).\n\n`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).\n\n`opts.uriToFnameHash: Record\u003cstring, string\u003e`: a hash table explicitly defining what uri maps to what filename.\n\n### `renameFileName(oldFileName: string, newFileName: string, content: string): string`\n\nFor all references in a given `content` string which point to an `oldFileName` and rename them to the `newFileName`; ignores escaped instances.\n\n#### Parameters\n\n##### `oldFileName: string`\n\nThe old filename string to be removed.\n\n##### `newFileName: string`\n\nThe new filename string to be added.\n\n##### `content: string`\n\nThe content string to make the file rename.\n\n### `retypeRefType(oldRefType: string, newRefType: string, content: string): string`\n\nFor all reference types in a given `content` string which match the given `oldRefType`, rename them to `newRefType`; ignores escaped instances.\n\nSince 'reftypes' contain 'attrtypes' (wikiattr) and 'linktypes' (wikilink), this function will preform the operations of both `retypeAttrType()` and `retypeLinkType()` below.\n\n#### Parameters\n\n##### `oldRefType: string`\n\nThe old reftype string to be removed.\n\n##### `newRefType: string`\n\nThe new reftype string to be added.\n\n##### `content: string`\n\nThe content string to make the retype (rename).\n\n### `retypeAttrType(oldAttrType: string, newAttrType: string, content: string): string`\n\nFor all attribute types in a given `content` string which match the given `oldAttrType`, rename them to `newAttrType`; ignores escaped instances.\n\n#### Parameters\n\n##### `oldAttrType: string`\n\nThe old attrtype string to be removed.\n\n##### `newAttrType: string`\n\nThe new attrtype string to be added.\n\n##### `content: string`\n\nThe content string to make the retype (rename).\n\n### `retypeLinkType(oldLinkType: string, newLinkType: string, content: string): string`\n\nFor all link types in a given `content` string which match the given `oldLinkType`, rename them to be `newLinkType`; ignores escaped instances.\n\n#### Parameters\n\n##### `oldLinkType: string`\n\nThe old linktype string to be removed.\n\n##### `newLinkType: string`\n\nThe new linktype string to be added.\n\n##### `content: string`\n\nThe content string to make the retype (rename).\n\n### `scan(content: string, opts?: ScanOpts): (WikiAttrResult | WikiLinkResult | WikiEmbedResult)[]`\n\nScan 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.\n\nResult formats:\n\n```js\nScanResult {\n  kind: string;  // kind of wikiref\n  text: string;  // match text\n  start: number; // match start position in content string\n}\nWikiAttrResult extends ScanResult {\n  type: [string, number] | [];\n  filenames: [string, number][];\n  listFormat: string;\n}\nWikiLinkResult extends ScanResult {\n  type: [string, number] | [];\n  filename: [string, number];\n  label: [string, number] | [];\n}\nWikiEmbedResult extends ScanResult {\n  filename: [string, number];\n  media: string;\n}\n```\n\nOptions:\n\n`opts.filename: string`: a specific filename to be targetted -- non-target-filename wiki constructs will be ignored.\n\n`opts.kind: string`: specific kinds of wiki constructs may be targetted; valid options are `'wikiattr'`, `'wikilink'`, and `'wikiembed'`.\n\n`opts.skipEsc: boolean`: whether or not to skip escaped wiki construct instances; set to `true` by default.\n\n### `wikiToMkdn(content: string, opts?: ConvertOpts): string`\n\nConvert `[[wikirefs]]` to `[markdown](links)` in a given `content` string.\n\nIn 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.\n\nOptions:\n\n`opts.kind: 'wikiref' | 'wikilink' | 'wikiembed'`: target specific wikiref constructs for conversion (`attr`s are implicitly included in `link`s).\n\n`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.\n\n`opts.ext: boolean`: whether or not to include file extension in uri.\n\n`opts.fnameToUriHash: Record\u003cstring, string\u003e`: a hash table explicitly defining what filename maps to what uri.\n\n### Regex API\n\nRegex 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.\n\nSee [`regex.ts`](https://github.com/wikibonsai/wikirefs/blob/main/src/lib/var/regex.ts) for more regex utilities.\n\n### `RGX.WIKI.ATTR`\n\nNote: Since javascript/typescript regex does not support the [`\\G` anchor](https://ruby-doc.org/core-2.5.1/Regexp.html#class-Regexp-label-Anchors), filenames should be extracted from list items in the full match string. `wikirefs.RGX.WIKI.BASE` is a convenience regex for this purpose.\n\n```js\n// mkdn + comma separated formats both supported\nimport * as wikirefs from 'wikirefs';\n\n////\n// single / comma-list...\n\nconst match = wikirefs.RGX.WIKI.ATTR.exec(`\n:attrtype::[[wikilink1]],[[wikilink2]]\n`);\n\nconst matchText    : string = match[0]; // ':attrtype::[[wikilink1]],[[wikilink2]]\\n'\nconst attrTypeText : string = match[1]; // 'attrtype'\n\n// no '\\G' so extract filenames manually\nlet fnameMatch: RegExpExecArray;\nlet filenames: string[] = [];           // ['wikilink1', 'wikilink2']\nconst fnameRegex = new RegExp(wikirefs.RGX.WIKI.BASE, 'g');\ndo {\n  fnameMatch = fnameRegex.exec(matchText);\n  if (fnameMatch) {\n    filenames.push(fnameMatch[1]);\n  }\n} while (fnameMatch);\n\nconsole.log(attrTypeText, filenames) // prints: 'attrtype', ['wikilink1', 'wikilink2']\n\n////\n// mkdn-list...\n\nconst match = wikirefs.RGX.WIKI.ATTR.exec(\n`:attrtype::\n- [[wikilink1]]\n- [[wikilink2]]\n`);\n\nconst matchText    : string = match[0]; // ':attrtype::\\n- [[wikilink1]]\\n- [[wikilink2]]\\n'\nconst attrTypeText : string = match[1]; // 'attrtype'\n\n// no '\\G' so extract filenames manually\nlet fnameMatch: RegExpExecArray;\nlet filenames: string[] = [];           // ['wikilink1', 'wikilink2']\nconst fnameRegex = new RegExp(wikirefs.RGX.WIKI.BASE, 'g');\ndo {\n  fnameMatch = fnameRegex.exec(matchText);\n  if (fnameMatch) {\n    filenames.push(fnameMatch[1]);\n  }\n} while (fnameMatch);\n\nconsole.log(attrTypeText, filenames) // prints: 'attrtype', ['wikilink1', 'wikilink2']\n\n```\n\n### `RGX.WIKI.LINK`\n\nNote: 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.\n\n```js\nimport * as wikirefs from 'wikirefs';\n\nconst match = wikirefs.RGX.WIKI.LINK.exec(':linktype::[[wikilink|label]]');\n\nconst matchText    : string = match[0]; // ':linktype::[[wikilink|label]]'\nconst linkTypeText : string = match[1]; // 'linktype'\nconst fileNameText : string = match[2]; // 'wikilink'\nconst labelText    : string = match[3]; // 'label'\n```\n\n### `RGX.WIKI.EMBED`\n\n```js\nimport * as wikirefs from 'wikirefs';\n\nconst match = wikirefs.RGX.WIKI.EMBED.exec('![[wikiembed]]');\n\nconst matchText    : string = match[0]; // '![[wikiembed]]'\nconst fileNameText : string = match[1]; // 'wikiembed'\n```\n\n## A Note On Terminology\n\n```\n'wikitext'  : refers to the characters in a wikilink\n              that describe the link.\n'wikistring': refers to all characters in a wikilink,\n              which includes the wikitext and the \n              special characters of the wikilink.\n\n 'wikitext'\n      👇\n  • \u003c--\u003e •\n[[wikilink]]\n• \u003c------\u003e •\n      👆\n'wikistring'\n\n\n      'wikitext'\n    👇          👇\n • \u003c-\u003e •    • \u003c--\u003e •\n:reftype::[[wikilink]]\n• \u003c----------------\u003e •\n          👆\n      'wikistring'\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikibonsai%2Fwikirefs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwikibonsai%2Fwikirefs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikibonsai%2Fwikirefs/lists"}