af134cac8b
* [packages][m]: mv @flowershow/core package here * [packages/core][xs]: rename to @portaljs/core * [package.json][xs]: setup npm workspaces * [packages/core][xs]:replace deprecated rollup executor * [core/package.json][s]: fix mermaid versions * [core/tsconfig][xs]: rm extends * [core/jest.config][xs]: rm coverageDirectory * [core/package.json][xs]: install core-js * [packages.json][s]:use same version for all nrwl packages * [core/.eslintrc][xs]: adjust ignorePatterns * [core/project.json][xs]: rm publish targets * [packages][m]: mv @flowershow/remark-wiki-link here * [packages][m]: mv @flowershow/remark-wiki-link here * [packages][m]: mv @flowershow/remark-embed here * [remark-callouts/project.json][xs]: adjst test pattern * [package.json][s]: install missing deps * [remark-callouts][xs]: adjst fields in package.json * [remark-callouts][s]: rm pubish targets and adjst build executor * [remark-embed/jest.config][xs]: rm unknown option coverageDirectory * [remark-embed][xs]: rm publish targets * [remark-embed][s]: rename to @portaljs/remark-embed * [remark-wiki-link/eslintrc][xs]:adjst ignorePatterns * [package.json][xs]: install missing deps * [remark-wiki-link/test][xs]:specify format - also temporarily force any type on htmlExtension * [remark-wiki-link/README][xs]: replace @flowershow with @portaljs * [remark-wiki-link][xs]:rm old changelog * [remark-wiki-link][xs]: adjst package.json * [remark-wiki-link/project.json][xs]: rm publish targets * [core][s]: rm old changelog * [core/README][xs]:correct scope name * [remark-callouts/README][xs]: add @portaljs to pckg name * [remark-embed/README][xs]: add @portaljs to pckg name * [package-lock.json][xs]: refresh after rebasing on main
133 lines
5.0 KiB
Markdown
133 lines
5.0 KiB
Markdown
# remark-wiki-link
|
|
|
|
Parse and render wiki-style links in markdown especially Obsidian style links.
|
|
|
|
## What is this ?
|
|
|
|
Using obsidian, when we type in wiki link syntax for eg. `[[wiki_link]]` it would parse them as anchors.
|
|
|
|
## Features supported
|
|
|
|
- [x] Support `[[Internal link]]`
|
|
- [x] Support `[[Internal link|With custom text]]`
|
|
- [x] Support `[[Internal link#heading]]`
|
|
- [x] Support `[[Internal link#heading|With custom text]]`
|
|
- [x] Support `![[Document.pdf]]`
|
|
- [x] Support `![[Image.png]]`
|
|
|
|
* Supported image formats are jpg, jpeg, png, apng, webp, gif, svg, bmp, ico
|
|
* Unsupported image formats will display a raw wiki link string, e.g. `[[Image.xyz]]`.
|
|
|
|
Future support:
|
|
|
|
- [ ] Support `![[Audio.mp3]]`
|
|
- [ ] Support `![[Video.mp4]]`
|
|
- [ ] Support `![[Embed note]]`
|
|
- [ ] Support `![[Embed note#heading]]`
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @portaljs/remark-wiki-link
|
|
```
|
|
|
|
## Usage
|
|
|
|
```javascript
|
|
import unified from "unified";
|
|
import markdown from "remark-parse";
|
|
import wikiLinkPlugin from "@portaljs/remark-wiki-link";
|
|
|
|
const processor = unified().use(markdown).use(wikiLinkPlugin);
|
|
```
|
|
|
|
## Configuration options
|
|
|
|
### `pathFormat`
|
|
|
|
Type: `"raw" | "obisidan-absolute" | "obsidian-short"`
|
|
Default: `"raw"`
|
|
|
|
- `"raw"`: use this option for regular relative or absolute paths (or Obsidian relative paths), e.g. `[[../some/folder/file]]` or `[[[/some/folder/file]]]`,
|
|
- `"obsidian-absolute"`: use this option for Obsidian absolute paths, i.e. paths with no leading `/`, e.g. `[[some/folder/file]]`
|
|
- `"obsidian-short"`: use this option for Obsidian shortened paths, e.g. `[[file]]` to resolve them to absolute paths. Note that apart from setting this value, you will also need to pass a list of paths to files in your content folder, and pass it as `permalinks` option. You can generate this list yourself or use our util function `getPermalinks`. See below for more info.
|
|
|
|
> [!note]
|
|
> Wiki link format in Obsidian can be configured in Settings -> Files & Links -> New link format.
|
|
|
|
### `aliasDivider`
|
|
|
|
Type: single character string
|
|
Default: `"|"`
|
|
|
|
Alias divider character used in your wiki links. E.g. `[[/some/folder/file|Alias]]`
|
|
|
|
### `permalinks`
|
|
|
|
Type: `Array<string>`
|
|
Default: `[]`
|
|
|
|
A list of permalinks you want to match your wiki link paths with. Wiki links with matched permalinks will have `node.data.exists` property set to `true`. Wiki links with no matching permalinks will also have additional class `new` set.
|
|
|
|
### `wikiLinkResolver`
|
|
|
|
Type: `(name: string) => Array<string>`
|
|
Default: `(name: string) => name.replace(/\/index$/, "")` (simplified; see source code for full version)
|
|
|
|
A function that will take the wiki link target page (e.g. `"/some/folder/file"` in `[[/some/folder/file#Some Heading|Some Alias]]` wiki link) and return an array of pages to which the wiki link **can** be resolved (one of them will be used, depending on wheather `pemalinks` are passed, and if match is found).
|
|
|
|
If `permalinks` are passed, the resulting array will be matched against these permalinks to find the match. The matching pemalink will be used as node's `href` (or `src` for images).
|
|
|
|
If no matching permalink is found, the first item from the array returned by this function will be used as a node's `href` (or `src` for images). So, if you want to write a custom wiki link -> url
|
|
|
|
### `newClassName`
|
|
|
|
Type: `string`
|
|
Default: `"new"`
|
|
|
|
Class name added to nodes created for wiki links for which no matching permalink (passed in `permalinks` option) was found.
|
|
|
|
### `wikiLinkClassName`
|
|
|
|
Type: `string`
|
|
Default: `"internal"`
|
|
|
|
Class name added to all wiki link nodes.
|
|
|
|
### `hrefTemplate`
|
|
|
|
Type: `(permalink: string) => string`
|
|
Default: `(permalink: string) => permalink`
|
|
|
|
A function that will be used to convert a matched permalink of the wiki link to `href` (or `src` for images).
|
|
|
|
### `markdownFolder` ❌ (deprecated as of version 1.1.0)
|
|
|
|
A string that points to the content folder, that will be used to resolve Obsidian shortened wiki link path format.
|
|
|
|
Instead of using this option, use e.g. `getPermalinks` util function exported from this package to generate a list of permalinks from your content folder, and pass it explicitly as `permalinks` option.
|
|
|
|
## Generating list of permalinks from content folder with `getPermalinks`
|
|
|
|
If you're using shortened path format for your Obsidian wiki links, in order to resolve them correctly to paths they point to, you need to set `option.pathFormat: "obsidian-short"` but also provide the plugin with a list of permalinks that point to files in your content folder as `option.permalinks`. You can use your own script to generate this list or use our util function `getPermalinks` like so:
|
|
|
|
```javascript {4,6,11-12}
|
|
import unified from "unified";
|
|
import markdown from "remark-parse";
|
|
import wikiLinkPlugin from "@portaljs/remark-wiki-link";
|
|
import { getPermalinks } from "@portaljs/remark-wiki-link";
|
|
|
|
const permalinks = await getPermalinks("path-to-your-content-folder");
|
|
|
|
const processor = unified().use(markdown).use(wikiLinkPlugin, {
|
|
pathFormat: "obsidian-short",
|
|
permalinks,
|
|
});
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
pnpm nx test remark-wiki-link
|
|
```
|