Merge pull request #5 from orbikm/feature/add_title_support

Add Title support for links
orbikm · Feb 19, 2021 · e312a0a · e312a0a
2 parents f1f3e7b + 94c4ff2
commit e312a0a
Show file tree

Hide file tree

Showing 11 changed files with 47 additions and 19 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,7 @@
+# mkdocs local build default name
+site/
+
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/README.md b/README.md
@@ -4,9 +4,9 @@ Plugin for mkdocs which enables easier linking between pages.
 This plugin was written in order to provide an up-to-date and
 feature complete plugin for easily referencing documents
 with a variety of features:
-* File name linking (e.g. `[Text](file)`)
+* File name linking (e.g. `[Text](file#anchor "title")`)
 * Absolute paths (e.g. `[Text](/link/to/file.md)`)
-* WikiLinks support (e.g. `[[Link]]`)
+* WikiLinks support (e.g. `[[Link#anchor|Link Title]]`)
 
 # Install
 ```
@@ -47,6 +47,7 @@ Given a layout such as
   +-- filename.md
   +-- image.png
 ```
+
 The following links will result in the following translations
 |Link|Translation|
 |----|-----------|
@@ -56,6 +57,7 @@ The following links will result in the following translations
 |`[Link Text](filename.md#Anchor)`|`[Link Text](folder/filename.md#Anchor)`|
 |`![Image Alt Text](image)`|`![Image Alt Text](folder/image.png)`|
 |`![Image Alt Text](image.png)`|`![Image Alt Text](folder/image.png)`|
+|`![Image Alt Test](image "Image Title")|`![Image Alt Text](folder/image.png "Image Title")`|
 
 
 ## Absolute Links

diff --git a/mkdocs_ezlinks_plugin/plugin.py b/mkdocs_ezlinks_plugin/plugin.py
@@ -13,6 +13,7 @@ class Link:
     text: str
     target: str
     anchor: str
+    title: str
 
 @dataclass
 class EzLinksOptions:
@@ -39,8 +40,11 @@ def __call__(self, match: re.Match) -> str:
               return match.group(0)
 
             # Render the link
-            rendered_link = f"{'!' if link.image else ''}[{link.text}]({link.target}{'#' + link.anchor if link.anchor else ''})"
-            return rendered_link
+            img = '!' if link.image else ''
+            anchor = f"#{link.anchor}" if link.anchor else ''
+            title = f' "{link.title}"' if link.title else ''
+
+            return f"{img}[{link.text}]({link.target}{anchor}{title})"
         except BrokenLink as ex:
             if self.options.strict:
                 print(f"ERROR -  {ex}")
@@ -64,7 +68,6 @@ def _get_link_to_file(self, filename: str) -> str:
                 abs_to = os.path.join(self.root, filename[1:])
                 if not self.options.absolute:
                     print(f"WARNING -  Absolute link '{filename}' detected, but absolute link support disabled.")
-                    # Return the whole string, unaltered
                     return filename
             else:
                 files = self.filenames.get(search_name)
@@ -82,11 +85,17 @@ def _get_link_to_file(self, filename: str) -> str:
     # Generate a Link with the details supplied by an md link
     def _get_md_link(self, match: re.Match) -> Link:
         groups = match.groupdict()
-        target = self._get_link_to_file(groups.get('md_filename'))
+        # Straight .get doesn't work, because in absence of a capture group,
+        # it is '', not None
+        full_match = match.group(0)
+        md_filename = groups.get('md_filename')
+        filename = md_filename if md_filename not in ['', None] else self.page_url
+        target = self._get_link_to_file(filename)
         return Link(
             image=groups.get('md_is_image') or groups.get('md_alt_is_image'),
             text=groups.get('md_text', ''),
             target=target,
+            title=groups.get('md_title', ''),
             anchor=groups.get('md_anchor', '')
         )
 
@@ -114,7 +123,8 @@ def _get_wiki_link(self, match: re.Match) -> Link:
             image=groups.get('wiki_is_image'),
             text=wiki_text if wiki_text and wiki_text != '' else wiki_link,
             target=link,
-            anchor=anchor
+            anchor=anchor,
+            title=wiki_text
         )
         return result
 
@@ -165,15 +175,15 @@ def on_page_markdown(self, markdown, page, config, site_navigation=None, **kwarg
 
         # +------------------------------+
         # | MD Link Regex Capture Groups |
-        # +---------------------------------------------------------------------------------------+
-        # | md_is_image      |  Contains ! when an image tag, or empty if not (check both)        |
-        # | md_alt_is_image  |  Contains ! when an image tag, or empty if not (check both)        |
-        # | md_text          |  Contains the Link Text between [md_text]                          |
-        # | md_target        |  Contains the full target of the Link (filename.md#anchor)         |
-        # | md_filename      |  Contains just the filename portion of the target (filename.md)    |
-        # | md_anchor        |  Contains the anchor, if present (e.g. file.md#anchor -> 'anchor') |
-        # +----------------------------------------------------------------------------------------
-        # TODO: Support - [Alt Text](my-page.md "My Title") (Link titles)
+        # +-------------------------------------------------------------------------------------+
+        # | md_is_image      |  Contains ! when an image tag, or empty if not (check both)      |
+        # | md_alt_is_image  |  Contains ! when an image tag, or empty if not (check both)      |
+        # | md_text          |  Contains the Link Text between [md_text]                        |
+        # | md_target        |  Contains the full target of the Link (filename.md#anchor)       |
+        # | md_filename      |  Contains just the filename portion of the target (filename.md)  |
+        # | md_anchor        |  Contains the anchor, if present (e.g. `file.md#anchor`)         |
+        # | md_title         |  Contains the title, if present (e.g. `file.md "My Title"`)      |
+        # +-------------------------------------------------------------------------------------+
         md_link_pattern =\
             r'(?:'                                        \
                 r'(?P<md_is_image>\!?)\[\]'               \
@@ -185,8 +195,9 @@ def on_page_markdown(self, markdown, page, config, site_navigation=None, **kwarg
             r')'                                          \
             r'\('                                         \
                 r'(?P<md_target>'                         \
-                    r'(?P<md_filename>\/?[^#\ \)]+)'      \
-                        r'(?:#(?P<md_anchor>[^\ \)]*)?)?' \
+                    r'(?P<md_filename>\/?[^#\ \)]*)?'     \
+                    r'(?:#(?P<md_anchor>[^\)\"]*)?)?'     \
+                    r'(?:\ \"(?P<md_title>[^\"\)]*)\")?'  \
                 r')'                                      \
             r'\)'
 

diff --git a/setup.py b/setup.py
@@ -29,7 +29,7 @@
     'Programming Language :: Python',
     'Programming Language :: Python :: 3 :: Only'
   ],
-  packages=find_packages(exclude=['*.test']),
+  packages=find_packages(exclude=['test.*']),
   entry_points={
     'mkdocs.plugins': [
       'ezlinks = mkdocs_ezlinks_plugin.plugin:EzLinksPlugin'

diff --git a/mkdocs_ezlinks_plugin/test/docs/index.md → test/docs/index.md b/mkdocs_ezlinks_plugin/test/docs/index.md → test/docs/index.md
diff --git a/...inks_plugin/test/docs/my-project/index.md → test/docs/my-project/index.md b/...inks_plugin/test/docs/my-project/index.md → test/docs/my-project/index.md
diff --git a/test/docs/my-project/link_updates.md b/test/docs/my-project/link_updates.md
@@ -0,0 +1,10 @@
+
+[Testing a local Anchor](#Test Header)
+[Testing a remote Anchor](project.md#Test Header)
+
+[My Section](my-section.md "Testing this Title")
+
+[My Section](my-section.md#Anchor-test "Test Title")
+
+![Alt Text](puppy "Test Title")
+
diff --git a/...est/docs/my-project/section/my-section.md → test/docs/my-project/section/my-section.md b/...est/docs/my-project/section/my-section.md → test/docs/my-project/section/my-section.md
diff --git a/...plugin/test/docs/other-project/project.md → test/docs/other-project/project.md b/...plugin/test/docs/other-project/project.md → test/docs/other-project/project.md
diff --git a/..._plugin/test/docs/static/images/puppy.jpg → test/docs/static/images/puppy.jpg b/..._plugin/test/docs/static/images/puppy.jpg → test/docs/static/images/puppy.jpg
diff --git a/mkdocs_ezlinks_plugin/test/mkdocs.yml → test/mkdocs.yml b/mkdocs_ezlinks_plugin/test/mkdocs.yml → test/mkdocs.yml
@@ -3,6 +3,7 @@ strict: false
 nav:
     - Home: 'index.md'
     - My Project: 'my-project/index.md'
+    - 'my-project/link_updates.md'
     - 'my-project/section/my-section.md'
     - 'other-project/project.md'
 theme: readthedocs