Add support for Reference Link definitions (#32)

* Addresses Github Issue #31, which is a feature request for supporting
  Reference Link format links.

Author: orbikm

README.md

@@ -13,6 +13,7 @@ with a variety of features:
 * File name linking (e.g. `[Text](file#anchor "title")`)
 * Absolute paths (e.g. `[Text](/link/to/file.md)`)
 * WikiLinks support (e.g. `[[Link#anchor|Link Title]]`)
+* Reference Link support (e.g. `[foo]: bar/ "Foo Title"`)
 
 # Install
 ```
@@ -30,6 +31,12 @@ plugins:
 
 # Release Log
 
+## Release 0.1.13
+Adds support for Reference Link parsing. This is to support certain Foam editors, which generate [Refeerence Links](https://spec.commonmark.org/0.29/#reference-link).
+
+Issues Addressed:
+  * GH Issue #31, `Add support for reference link definitions`. Allows compatibility with certain Foam editors which generate Reference Links.
+
 ## Release 0.1.12
 This is a bugfix release.
 
@@ -54,6 +61,7 @@ plugins:
     - ezlinks:
         warn_ambiguities: {true|false}
         wikilinks: {true|false}
+        reference_links: {true|false}
 ```
 ## warn_ambiguities
 Determines whether to warn when an abmiguous link is encountered. An ambiguous link is one that would have more than one possible targets. For example, if you had the following document setup:
@@ -95,6 +103,9 @@ Determines whether to scan for wikilinks or not (See [WikiLink Support](#wikilin
 > **NOTE**  
 >  This plugin feature does not function well when the 'wikilinks' markdown extension is enabled. This plugin's functionality should replace the need for enabling said extension.
 
+## reference_links
+Determins whether to scan for Reference Links or not (See [Reference Links](https://spec.commonmark.org/0.29/#reference-link), e.g. `[foo]: /bar "Foo Bar"`)
+
 # Features
 ## Filename Links
 Given a layout such as

mkdocs_ezlinks_plugin/plugin.py

@@ -8,6 +8,7 @@
 from .replacer import EzLinksReplacer
 from .scanners.md_link_scanner import MdLinkScanner
 from .scanners.wiki_link_scanner import WikiLinkScanner
+from .scanners.reference_link_scanner import ReferenceLinkScanner
 from .types import EzLinksOptions
 
 LOGGER = logging.getLogger(f"mkdocs.plugins.{__name__}")
@@ -17,7 +18,8 @@
 class EzLinksPlugin(mkdocs.plugins.BasePlugin):
     config_scheme = (
         ('wikilinks',  mkdocs.config.config_options.Type(bool, default=True)),
-        ('warn_ambiguities', mkdocs.config.config_options.Type(bool, default=False))
+        ('warn_ambiguities', mkdocs.config.config_options.Type(bool, default=False)),
+        ('reference_links', mkdocs.config.config_options.Type(bool, default=False))
     )
 
     def init(self, config):
@@ -32,6 +34,9 @@ def init(self, config):
         self.replacer.add_scanner(MdLinkScanner())
         if self.config['wikilinks']:
             self.replacer.add_scanner(WikiLinkScanner())
+        
+        if self.config['reference_links']:
+            self.replacer.add_scanner(ReferenceLinkScanner())
 
         # Compile the regex once
         self.replacer.compile()

mkdocs_ezlinks_plugin/scanners/reference_link_scanner.py

@@ -0,0 +1,43 @@
+from typing import Pattern, Match
+from .base_link_scanner import BaseLinkScanner
+from ..types import Link
+
+
+class ReferenceLinkScanner(BaseLinkScanner):
+    def pattern(self) -> Pattern:
+        # +--------------------------------------+
+        # | Reference Link Regex Capture Groups  |
+        # +--------------------------------------+
+        # | Example: [text]: url "title"         |
+        # |                                      |
+        # |  text: Required                      |
+        # |   url: Required                      |
+        # | title: Optional, up to one newline   |
+        # +--------------------------------------+
+        return r'''
+        (?:
+        \[
+            (?P<ref_text>[^\]]+)
+        \]
+        )\:\ 
+        (?!(?P<ref_protocol>[a-z][a-z0-9+\-.]*:\/\/))
+        (?P<ref_target>\/?[^\#\ \)(\r\n|\r|\n)]*)?
+        (?:\#(?P<ref_anchor> [^\(\ ]*)?)?
+        (?:(\r\n|\r|\n)?)?(?P<ref_title>\ ?\"[^(\r\n|\r|\n)\"]*\")?
+        '''
+
+    def match(self, match: Match) -> bool:
+        return bool(
+            match.groupdict().get('ref_text') and
+            match.groupdict().get('ref_target')
+        )
+
+    def extract(self, match: Match) -> bool:
+        groups = match.groupdict()
+        return Link(
+            image=False,
+            text=groups.get('ref_text') or '',
+            target=groups.get('ref_target') or '',
+            title=groups.get('ref_title') or '',
+            anchor=groups.get('ref_anchor') or ''
+        )

mkdocs_ezlinks_plugin/types.py

@@ -27,3 +27,4 @@ class EzLinksOptions:
     ''' Dataclass to hold typed options from the configuration. '''
     wikilinks: bool
     warn_ambiguities: bool
+    reference_links: bool

setup.py

@@ -8,13 +8,13 @@
 
 setup(
   name='mkdocs-ezlinks-plugin',
-  version='0.1.12',
+  version='0.1.13',
   description=description,
   long_description=long_description,
   long_description_content_type='text/markdown',
   keywords='mkdocs',
   url='https://github.com/orbikm/mkdocs-ezlinks-plugin',
-  download_url='https://github.com/orbikm/mkdocs-ezlinks-plugin/archive/v_0.1.12.tar.gz',
+  download_url='https://github.com/orbikm/mkdocs-ezlinks-plugin/archive/v_0.1.13.tar.gz',
   author='Mick Orbik',
   author_email='mick.orbik@gmail.com',
   license='MIT',

test/docs/reference-links/reference-links-test.md

@@ -0,0 +1,15 @@
+<!-- Basic, proper reference link -->
+[Link Text]: my-section "Link Title"
+
+<!-- Link with extension -->
+[Link Text]: my-section.md "Link Title"
+
+<!-- Link without Title -->
+[Link Text]: my-section
+
+<!-- Title with optional newline -->
+[Link Text]: my-section
+"Test Newline Title"
+
+<!-- Absolute Link -->
+[Foo]: /other-project/project "Project"

test/mkdocs.yml

@@ -13,10 +13,12 @@ nav:
     - 'disambiguation/sub1/sub4/index.md'
     - 'disambiguation/sub3/sub4/index.md'
     - 'disambiguation/sub3/sub4/about.md'
+    - 'reference-links/reference-links-test.md'
 theme: readthedocs
 docs_dir: 'docs'
 use_directory_urls: false
 plugins:
     - search
     - ezlinks:
-       wikilinks: true
+       wikilinks: true
+       reference_links: true