mirror of
https://github.com/foambubble/foam.git
synced 2026-01-14 16:38:04 -05:00
37 lines
2.0 KiB
Markdown
37 lines
2.0 KiB
Markdown
# Link Reference Definitions
|
|
|
|
## Introduction
|
|
|
|
When you use `[[wiki-links]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension will automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is done to make the content of the file compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wiki-links]]`.
|
|
|
|
## Example
|
|
|
|
The following example:
|
|
```md
|
|
- [[wiki-links]]
|
|
- [[github-pages]]
|
|
```
|
|
...generates the following link reference definitions to the bottom of the file:
|
|
```md
|
|
[wiki-links]: wiki-links "Wiki Links"
|
|
[github-pages]: github-pages "Github Pages"
|
|
```
|
|
You can open the [raw markdown](https://raw.githubusercontent.com/foambubble/foam/master/foam-file-format.md) to see them at the bottom of this file
|
|
|
|
## Specification
|
|
|
|
The three components of a link reference definition are `[link-label]: link-target "Link Title"`
|
|
|
|
- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wiki-link]]` notation
|
|
- **link destination** The target of the matched link
|
|
- Right now we generate link destinations without file extension. This is a choice, see [discussion here](https://foambubble.github.io/foam/wiki-links#why-dont-wiki-links-work-on-github).
|
|
- **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
|
|
|
|
See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
|
|
|
|
|
|
[//begin]: # "Autogenerated link references for markdown compatibility"
|
|
[wiki-links]: wiki-links "Wiki Links"
|
|
[roadmap]: roadmap "Roadmap"
|
|
[link-reference-definition-improvements]: link-reference-definition-improvements "Link Reference Definition Improvements"
|
|
[//end]: # "Autogenerated link references" |