@moritzrs/mdast-util-ofm-wikilink
Version:
mdast extension to support OFM wikilinks
218 lines (144 loc) • 6.32 kB
Markdown
# mdast-util-ofm-wikilink
[mdast](https://github.com/syntax-tree/mdast) extensions to parse and serialize Obsidian Flavored Markdown (OFM) [wikilinks](https://help.obsidian.md/Linking+notes+and+files/Internal+links) and embeddings.
## What is this?
This package contains two extensions to add support for OFM wikilink syntax to [`mdast`](https://github.com/syntax-tree/mdast).
These extensions plug into [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) (to support parsing wikilinks in markdown into a syntax tree) and [`mdast-util-to-markdown`](https://github.com/syntax-tree/mdast-util-to-markdown) (to support serializing wikilinks in syntax trees to markdown)
## When to use this
You can use these extension when you are working with `mdast-util-from-markdown` and `mdast-util-to-markdown` already.
When working with `mdast-util-from-markdown`, you must combine this package with [`micromark-extension-ofm-wikilink`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/micromark-extension-ofm-wikilink).
When you don't need a syntax tree, you can use [`micromark`](https://github.com/micromark/micromark) directly with `micromark-extension-ofm-wikilink`.
When you are working with syntax trees and want all of OFM, use [`mdast-util-ofm`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/mdast-util-ofm) instead.
All these packages are used in [`remark-ofm`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/remark-ofm), which focusses on making it easier to transform content by abstracting these internal away.
## Install
This package is ESM only. In Node.js (version 18+), install with `npm`:
```sh
npm install @moritzrs/mdast-util-ofm-wikilink
```
## Use
```js
import { fromMarkdown } from "mdast-util-from-markdown";
import { toMarkdown } from "mdast-util-to-markdown";
import { ofmWikilink } from "@moritzrs/micromark-extension-ofm-wikilink";
import { ofmWikilinkFromMarkdown, ofmWikilinkToMarkdown } from "@moritzrs/mdast-util-ofm-wikilink";
const tree = fromMarkdown("This is a [[link]].", {
extensions: [ofmWikilink()],
mdastExtensions: [ofmWikilinkFromMarkdown()],
});
console.log(tree);
const out = toMarkdown(tree, { extensions: [ofmWikilinkToMarkdown()] });
console.log(out);
```
Yields
```js
{
type: "root",
children: [
{
type: "paragraph",
children: [
{ type: "text", value: "This is a " },
{ type: "ofmWikilink", value: "link", url: "link", hash: "" },
{ type: "text", value: "." },
],
},
]
}
```
```md
This is a [[link]].
```
## API
This package exports the identifiers `ofmWikilinkFromMarkdown` and `ofmWikilinkToMarkdown`.
There is no default export.
### `ofmWikilinkFromMarkdown()`
Creates an extension for `mdast-util-from-markdown` to enable OFM wikilink in markdown.
###### Parameters
- `none`
###### Returns
Extension for `mdast-util-from-markdown` that can be passed in `extensions`, to enable OFM wikilink syntax ([`FromMarkdownExtension`](https://github.com/syntax-tree/mdast-util-from-markdown#extension)).
### `ofmWikilinkToMarkdown()`
Creates an extension for `mdast-util-to-markdown` to enable OFM wikilink in markdown.
###### Parameters
- `none`
###### Returns
Extension for `mdast-util-to-markdown` that can be passed in `extensions`, to support OFM wikilinks when serializing to markdown ([`ToMarkdownExtension`](https://github.com/syntax-tree/mdast-util-to-markdown#options)).
## Syntax
See [Syntax in `micromark-extension-ofm-wikilink`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/micromark-extension-ofm-wikilink#syntax).
## Syntax tree
The following interfaces are added to [mdast](https://github.com/syntax-tree/mdast) by this utility.
### Nodes
#### `OfmWikilink`
```idl
interface OfmWikilink <: Literal {
type: "ofmWikilink";
url: string;
hash: string;
value: string;
}
```
**OfmWikilink** represents an internal link.
**OfmWikilink** can be used where phrasing content is expected.
For example, the following markdown:
```markdown
[[link]]
```
Yields:
```js
{
type: "ofmWikilink",
url: "link",
hash: "",
value: "link",
}
```
#### `OfmWikiEmbedding`
```idl
interface OfmWikiEmbedding <: Literal {
type: "ofmWikilink";
url: string;
hash: string;
value: string;
}
```
**OfmWikiEmbedding** represents an embedded internal file.
**OfmWikiEmbedding** can be used where phrasing content is expected.
For example, the following markdown:
```markdown
![[link]]
```
Yields:
```js
{
type: "ofmWikiembedding"
url: "link",
hash: "",
value: "link",
}
```
### Content Model
#### `PhrasingContent` (OFM wikilink)
```idl
type PhrasingContent = OfmWikilink | OfmWikiEmbedding | PhrasingContent;
```
## Types
This package is fully typed with [TypeScript](https://www.typescriptlang.org/).
It does not export additional types.
The `OfmWikilink` and `OfmWikiEmbedding` types of the mdast node are exposed from `@types/mdast`.
## Compatibility
This package was tested to work with node version `18` and later.
## Related
- [`remark-ofm`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/remark-ofm) - remark plugin to support OFM
- [`mdast-util-ofm`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/mdast-util-ofm) - mdast extension to parse and serialize OFM
- [`micromark-extension-ofm-wikilink`](https://github.com/MoritzRS/obsidian-ext/tree/main/packages/micromark-extension-ofm-wikilink) - micromark extension to parse OFM wikilinks
## Contribute
I don't know if i can check PRs in a timely manner, but feel free to open PRs or issues.
If participation is high I will need to add a code of conduct and contribution guidelines.
## Disclaimer
This package is not affiliated with Obsidian.md or the developers of Obsidian.md.
## License
[MIT](https://github.com/MoritzRS/obsidian-ext/blob/main/LICENSE.md) © Moritz R. Schulz