Obsidian reader extensions for comments and wikilink transclusions

[kepano]

Add Obsidian-Flavored Markdown #9883 using Markdown extensions.

Extensions

• comments: Parses %%text%% as comments (removed from output)
• wikilink_transclusions: Parses ![[Title]] for full file transclusion
• wikilink_heading_transclusions: Parses ![[Title#Heading]] for heading transclusions
• wikilink_block_transclusions: Parses ![[Title#^id]] for block transclusions
• block_ids: Parses ^id at paragraph end, wraps paragraph in Div with that ID

Uses insertIncludedFile for transclusion.

Includes tests and manual updates.

[jgm]

Transclusion should be possible. See insertIncludedFile from Text.Pandoc.Parsing.
And look at the RST reader's treatment of include directives for an example of its use.

[kepano]

@jgm I think this is in a good place for your review now.

Some notes:

1. I revised how wikilink images (e.g. ![[image.jpg]]) are parsed because the implementation of Image wikilinks for export in Obsidian #8853 via 09de84f seemed to be originally driven by Obsidian's syntax. In Obsidian, the ![[link]] wikilink syntax can be used to transclude any type of file (not just images), as well as headings and blocks within Markdown files. I consolidated all of these into a new transclusion parser (which could alternatively be called "include" or "embed" if you prefer).
2. I ended up building on top of the Markdown reader instead of the Commonmark reader. Hopefully this gives flexibility to other apps that support Obsidian's syntax but not other Commonmark extensions.

[jgm]

Can you rebase this into one commit, or a few logically coherent commits? All API changes should be clearly described and marked as such [API change] in the commit messages, so we won't miss them in the changelog.

[kepano]

Can you rebase this into one commit, or a few logically coherent commits? All API changes should be clearly described and marked as such [API change] in the commit messages, so we won't miss them in the changelog.

Done!

[jgm]

Re block_transclusions, heading_transclusions: are these really transclusions? From the docs, it looks like they just produce links.

[jgm]

Does block_ids also handle the case where the id is on a line by itself before a block? And the case where it is meant to apply to a a line inside a block?

[pidgeon777]

Hello, thanks for working on it. What about Obsidian callouts? Do you think those are doable also?

[kepano]

@jgm Thanks for the update. I saw a notification from you about other requested changes on #9883 but it seems you removed that comment. Is there something else you want me to work on?

Re block_transclusions, heading_transclusions: are these really transclusions? From the docs, it looks like they just produce links.

They are indeed transclusions, not links. The content within the source block or heading is transcluded into the document. See also this documentation page about embeds. In Obsidian-Flavored Markdown adding an exclamation mark ! before a wikilink changes it to a transclusion (AKA embed), e.g. [[link]] or ![[transclusion]], the additional modifiers #^ and # provide access to the block or heading.

Does block_ids also handle the case where the id is on a line by itself before a block? And the case where it is meant to apply to a a line inside a block?

I'll check and add tests for this.

Hello, thanks for working on it. What about Obsidian callouts? Do you think those are doable also?

Callouts are already handled by the alerts extension — the GitHub syntax was inspired by Obsidian.

[tobiasvl]

@kepano Should transclusions perhaps add a class to the transcluded content?

Obsidian detects transcluded content and adds classes (such as "markdown-embed-content" if the embed is a heading or Markdown block), and uses that to display it differently (like a specially styled blockquote, with a link icon that leads to the embedded content), but in this implementation there's no way to differentiate regular content from transcluded content - it's all just one flat Pandoc document.

So if one were to export an Obsidian note with a transclusion in it to PDF/TeX or HTML using this extension, the information about the fact that this is a transclusion is lost, and the result can't be styled to look like the Obsidian note.