5f755e4fa3
This makes gmnhg encode link destinations before rendering them into Gemtext according to RFC 3986. This particularly fixes spaces in links. Invalid URIs will skipped from rendering entirely. Fixes #49.
74 lines
3.3 KiB
Text
74 lines
3.3 KiB
Text
# Links
|
|
|
|
gmnhg supports links, images, and footnotes. These are extracted from paragraphs and other block elements recursively.
|
|
|
|
As there's no inline links in Gemtext, gmnhg instead renders links blocks after paragraphs. Links blocks are sorted by type: first footnotes, then images, then links, blocks of a distinct type separated by a single newline.
|
|
|
|
## Inline links & images
|
|
|
|
For inline Markdown links, the text inside the square brackets is used as link title: for instance, the link to Gemini specification along with a link to the current CommonMark spec will generate a block of two links.
|
|
|
|
=> https://gemini.circumlunar.space/docs/specification.gmi Gemini specification
|
|
=> https://spec.commonmark.org/0.30/ CommonMark spec
|
|
|
|
gomarkdown works with reference-style links as well. Unused reference links are ignored.
|
|
|
|
=> https://github.com/gomarkdown/markdown gomarkdown
|
|
|
|
xkcd #1853 serves quite well as an inline image example.
|
|
|
|
=> https://imgs.xkcd.com/comics/once_per_day.png xkcd #1853
|
|
|
|
Other container elements can contain inline links as well. For instance, this is an example of a link inside a blockquote:
|
|
|
|
> OTR has significant usability drawbacks for inter-client mobility.
|
|
> — XEP-0384
|
|
|
|
=> https://xmpp.org/extensions/xep-0384.html XEP-0384
|
|
|
|
Links will get encoded according to RFC 3986, like this sample link to nowhere. The other sample link to somewhere on GitHub will not get transformed: sample.
|
|
|
|
=> /URI%20with%20spaces link
|
|
=> https://github.com:443/request+with+characters%20 sample
|
|
|
|
## Footnotes
|
|
|
|
gmnhg supports footnotes, written like this[^1]. Footnotes can use any references, including alphanumeric ones[^2]; alphanumeric references will be replaced with numeric IDs on render.
|
|
|
|
[^1]: Footnotes can only consist of a single source line due to a quirk of gomarkdown.
|
|
[^2]: Footnotes can contain any kind of inline **formatting** paragraphs do. For instance, this is a link to GitHub.
|
|
|
|
=> https://github.com GitHub
|
|
|
|
This line looks like it would belong to footnote 1, but it actually doesn't, and is therefore treated as a new paragraph.
|
|
|
|
## Lists of links
|
|
|
|
gmnhg additionally supports a special kind of lists: lists consisting solely of links. For these, content rendering will be skipped entirely, and a links block will be rendered instead.
|
|
|
|
### Markdown lists
|
|
|
|
Links-only lists can be of any type, but they can only be of level 1. The two lists below will get rendered as links blocks:
|
|
|
|
=> https://gemini.circumlunar.space/docs/specification.gmi Gemini specification
|
|
=> https://github.com/tdemin/gmnhg gmnhg
|
|
|
|
=> https://gemini.circumlunar.space/docs/best-practices.gmi Best practices for Gemini implementers
|
|
=> https://gemini.circumlunar.space/docs/faq.gmi Project Gemini FAQ
|
|
|
|
The list below contains other meaningful text in its items, and will get rendered as a regular list:
|
|
|
|
* Gemini specification is a must-read for a Gemini developer.
|
|
|
|
=> https://gemini.circumlunar.space/docs/specification.gmi Gemini specification
|
|
|
|
### Series of links
|
|
|
|
A series of inline links in a single paragraph, if the paragraph contains no extra meaningful symbols (aside from spaces and newlines), will also get rendered as a single links block:
|
|
|
|
=> https://github.com/tdemin/gmnhg gmnhg
|
|
=> https://gemini.circumlunar.space/docs/specification.gmi Gemini specification
|
|
|
|
This also works for single-link paragraphs:
|
|
|
|
=> https://gemini.circumlunar.space/docs/specification.gmi Gemini specification
|