[API change] Obsidian-Flavored Markdown extensions, including comments syntax, full file transclusion, heading transclusion, block transclusion

Author: kepano

MANUAL.txt

@@ -269,6 +269,7 @@ header when requesting a document from a URL:
     - `mdoc` ([mdoc] manual page markup)
     - `muse` ([Muse])
     - `native` (native Haskell)
+    - `obsidian` ([Obsidian-Flavored Markdown])
     - `odt` ([OpenDocument text document][ODT])
     - `opml` ([OPML])
     - `org` ([Emacs Org mode])
@@ -503,6 +504,7 @@ header when requesting a document from a URL:
 [Jira]: https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all
 [txt2tags]: https://txt2tags.org
 [EPUB]: http://idpf.org/epub
+[Obsidian-Flavored Markdown]: https://help.obsidian.md/obsidian-flavored-markdown
 [OPML]: http://dev.opml.org/spec2.html
 [OpenDocument XML]: https://www.oasis-open.org/2021/06/16/opendocument-v1-3-oasis-standard-published/
 [ODT]: https://en.wikipedia.org/wiki/OpenDocument
@@ -6004,11 +6006,18 @@ or image itself, if these differ.
 
 ### Extension: `mark` ###
 
-To highlight out a section of text, begin and end it with
+To highlight a section of text, begin and end it with
 with `==`. Thus, for example,
 
     This ==is deleted text.==
 
+### Extension: `comments` ###
+
+To comment out a section of text, begin and end it
+with `%%`. Thus, for example,
+
+    This %%is a comment.%%
+
 ### Extension: `attributes` ###
 
 Allows attributes to be attached to any inline or block-level
@@ -6155,15 +6164,16 @@ simply skipped (as opposed to being parsed as paragraphs).
 
 ### Extension: `alerts` ###
 
-Supports [GitHub-style Markdown alerts], like
+Supports [GitHub-style Markdown alerts] and [Obsidian callouts], like
 
     > [!TIP]
     > Helpful advice for doing things better or more easily.
 
+  [Obsidian callouts]: https://help.obsidian.md/callouts
   [GitHub-style Markdown alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
 
 Note: This extension currently only works with commonmark:
-`commonmark`, `gfm`, `commonmark_x`.
+`commonmark`, `gfm`, `commonmark_x`, `obsidian`.
 
 ### Extension: `autolink_bare_uris` ###
 
@@ -6213,6 +6223,38 @@ or
 
     Oxygen is O~2.
 
+### Extension: `wikilink_transclusions` ###
+
+Follows [Obsidan-style transclusions] using wikilink syntax to embed one file in another. For example to transclude the file "Title":
+
+    ![[Title]]
+
+[Obsidan-style transclusions]: https://help.obsidian.md/embeds
+
+### Extension: `wilikink_heading_transclusions` ###
+
+Follows the [Obsidan-style heading transclusions] syntax. For example to transclude a heading within the file "Title":
+
+    ![[Title#Heading]]
+
+[Obsidan-style heading transclusions]: https://help.obsidian.md/links#Link+to+a+heading+in+a+note
+
+### Extension: `wilikink_block_transclusions` ###
+
+Follows the [Obsidan-style block transclusions] syntax. For example to transclude block ID ^ref within the file "Title":
+
+    ![[Title#^ref]]
+
+[Obsidan-style block transclusions]: https://help.obsidian.md/links#Link+to+a+block+in+a+note
+
+### Extension: `block_ids` ###
+
+Follows the [Obsidan-style block identifiers] syntax. For example add `^ref` at the end of a paragraph:
+
+    Text ^ref
+
+[Obsidan-style block identifiers]: https://help.obsidian.md/links#Link+to+a+block+in+a+note
+
 ### Extension: `wikilinks_title_after_pipe` ###
 
 Pandoc supports multiple Markdown wikilink syntaxes, regardless of
@@ -6240,6 +6282,7 @@ variants are supported:
 - `markdown_strict` (Markdown.pl)
 - `commonmark` (CommonMark)
 - `gfm` (Github-Flavored Markdown)
+- `obsidian` (Obsidian-Flavored Markdown)
 - `commonmark_x` (CommonMark with many pandoc extensions)
 
 To see which extensions are supported for a given format,

src/Text.Pandoc/Parsing.hs

@@ -57,8 +57,10 @@ data Extension =
     | Ext_backtick_code_blocks    -- ^ GitHub style ``` code blocks
     | Ext_blank_before_blockquote -- ^ Require blank line before a blockquote
     | Ext_blank_before_header     -- ^ Require blank line before a header
+    | Ext_block_ids           -- ^ Block identifiers, used by Obsidian
     | Ext_bracketed_spans         -- ^ Bracketed spans with attributes
     | Ext_citations           -- ^ Pandoc/citeproc citations
+    | Ext_comments            -- ^ Percent wrapped %%comments%%
     | Ext_definition_lists    -- ^ Definition lists as in pandoc, mmd, php
     | Ext_east_asian_line_breaks  -- ^ Newlines in paragraphs are ignored between
                                   --   East Asian wide characters. Note: this extension
@@ -141,6 +143,9 @@ data Extension =
                                      -- [[target|title]]
     | Ext_wikilinks_title_before_pipe  -- ^ Support wikilinks of style
                                        -- [[title|target]]
+    | Ext_wikilink_transclusions          -- ^ Wikilink transclusion e.g. ![[title]]
+    | Ext_wikilink_heading_transclusions  -- ^ Wikilink heading transclusion e.g. ![[title#heading]] in Obsidian
+    | Ext_wikilink_block_transclusions    -- ^ Wikilink block transclusions, e.g. ![[title#^id]] in Obsidian
     | Ext_xrefs_name          -- ^ Use xrefs with names
     | Ext_xrefs_number        -- ^ Use xrefs with numbers
     | Ext_yaml_metadata_block -- ^ YAML metadata block
@@ -405,6 +410,26 @@ getDefaultExtensions "gfm"             = extensionsFromList
   , Ext_tex_math_gfm
   , Ext_alerts
   ]
+getDefaultExtensions "obsidian"          = extensionsFromList
+  [ Ext_alerts
+  , Ext_autolink_bare_uris
+  , Ext_block_ids
+  , Ext_comments
+  , Ext_footnotes
+  , Ext_hard_line_breaks
+  , Ext_mark
+  , Ext_pipe_tables
+  , Ext_raw_html
+  , Ext_rebase_relative_paths
+  , Ext_strikeout
+  , Ext_task_lists
+  , Ext_tex_math_dollars
+  , Ext_wikilinks_title_after_pipe
+  , Ext_wikilink_transclusions
+  , Ext_wikilink_block_transclusions
+  , Ext_wikilink_heading_transclusions
+  , Ext_yaml_metadata_block
+  ]
 getDefaultExtensions "commonmark"      = extensionsFromList
                                           [Ext_raw_html]
 getDefaultExtensions "commonmark_x"    = extensionsFromList
@@ -525,6 +550,27 @@ getAllExtensions f = universalExtensions <> getAll f
   getAll "markdown_mmd"      = allMarkdownExtensions
   getAll "markdown_github"   = allMarkdownExtensions
   getAll "markdown"          = allMarkdownExtensions
+  getAll "obsidian"          = allMarkdownExtensions <> extensionsFromList
+    [ Ext_ascii_identifiers
+    , Ext_alerts
+    , Ext_autolink_bare_uris
+    , Ext_block_ids
+    , Ext_comments
+    , Ext_footnotes
+    , Ext_hard_line_breaks
+    , Ext_mark
+    , Ext_pipe_tables
+    , Ext_raw_html
+    , Ext_rebase_relative_paths
+    , Ext_strikeout
+    , Ext_task_lists
+    , Ext_tex_math_dollars
+    , Ext_wikilink_block_transclusions
+    , Ext_wikilink_heading_transclusions
+    , Ext_wikilink_transclusions
+    , Ext_wikilinks_title_after_pipe
+    , Ext_yaml_metadata_block
+    ]
   getAll "ipynb"             = allMarkdownExtensions <> extensionsFromList
     [ Ext_raw_markdown ]
   getAll "docx"            = autoIdExtensions <> extensionsFromList

src/Text/Pandoc/Extensions.hs

@@ -77,6 +77,7 @@ data ParserState = ParserState
   , stateContainers      :: [Text]        -- ^ parent include files
   , stateLogMessages     :: [LogMessage]  -- ^ log messages
   , stateMarkdownAttribute :: Bool        -- ^ True if in markdown=1 context
+  , stateLastBlockId       :: Maybe Text
   }
 
 instance Default ParserState where
@@ -166,6 +167,7 @@ defaultParserState = ParserState
   , stateContainers      = []
   , stateLogMessages     = []
   , stateMarkdownAttribute = False
+  , stateLastBlockId     = Nothing
   }
 
 type NoteTable = [(Text, Text)]

src/Text/Pandoc/Parsing/State.hs

@@ -141,6 +141,7 @@ readers = [("native"       , TextReader readNative)
           ,("creole"       , TextReader readCreole)
           ,("dokuwiki"     , TextReader readDokuWiki)
           ,("gfm"          , TextReader readCommonMark)
+          ,("obsidian"     , TextReader readMarkdown)
           ,("rst"          , TextReader readRST)
           ,("mediawiki"    , TextReader readMediaWiki)
           ,("vimwiki"      , TextReader readVimwiki)