Initial commit

Author: Zach Hannum

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 Zach Hannum 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,71 @@
+# MkDocs Autolinks Plugin
+
+* * *
+
+*An MkDocs plugin that simplifies relative linking between documents.*
+
+The Autolinks plugins allows you to link to pages and images within your MkDocs site without provided the entire relative path to the file in your document structure.
+
+## Installation
+
+* * *
+
+Install the package with pip:
+
+```sh
+cd mkdocs-autolinks-plugin
+pip install .
+```
+
+Enable the plugin in your `mkdocs.yml`:
+
+```yaml
+plugins:
+	- autolinks
+```
+
+More information about plugins in the [MkDocs documentation](https://www.mkdocs.org/user-guide/plugins/).
+
+## Usage
+
+* * *
+
+To use this plugin, simply create a link that only contains the filename of file you wish to link to.
+
+For example, say you have a document structure like this:
+
+```
+docs/
+├── guides/
+│   ├── onboarding.md
+│   └── syntax_guide.md
+├── software/
+│   ├── git_flow.md
+│   └── qnx.md
+└── images/
+    ├── avatar.png
+    └── example.jpg
+```
+
+Normally, if you want create a link to `git_flow.md` from inside `onboarding.md`, you would need to provide the relative path:
+
+```markdown
+# onboarding.md
+[Git Flow](../software/git_flow.md)
+```
+
+This link is fragile; if someone decides to rearrange the site structure, all of these relative links break. Not to mention having to figure out the relative path.
+
+With the Autolinks plugin, you simply need to provide the filename you wish to link to. The plugin will pre-process all of your markdown files and replace the filename with the correct relative path, given that the file exists in your document structure:
+
+```markdown
+# onboarding.md
+[Git Flow](git_flow.md)
+```
+
+The Autolinks plugin also works with `jpg` and `png` files:
+
+```markdown
+# onboarding.md
+![Avatar](avatar.png)
+```

deploy.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+rm -rf dist
+python setup.py bdist_wheel sdist --formats gztar && twine upload dist/*

mkdocs_autolinks_plugin/__init__.py

@@ -0,0 +1,52 @@
+import re
+import os
+from mkdocs.plugins import BasePlugin
+
+AUTOLINK_RE = r'\[([^\]]+)\]\(([^)/]+\.(md|png|jpg))\)'
+# (?<!```\n)\[([^\]]+)\]\(([^)/]+\.md)\)
+class AutoLinkReplacer:
+    def __init__(self, base_docs_url, page_url):
+        self.base_docs_url = base_docs_url
+        self.page_url = page_url
+
+    def __call__(self, match):
+        # Name of the markdown file
+        filename = match.group(2).strip()
+
+        # Absolute URL of the linker
+        abs_linker_url = os.path.dirname(os.path.join(self.base_docs_url, self.page_url))
+
+        # Find directory URL to target link
+        rel_link_url = ''
+        # Walk through all files in docs directory to find a matching file
+        for root, dirs, files in os.walk(self.base_docs_url):
+            for name in files:
+                # If we have a match, create the relative path from linker to the link
+                if name == filename:
+                    # Absolute path to the file we want to link to
+                    abs_link_url = os.path.dirname(os.path.join(root, name))
+                    # Constructing relative path from the linker to the link
+                    rel_link_url = os.path.join(os.path.relpath(abs_link_url, abs_linker_url), filename)
+        if rel_link_url == '':
+            print('WARNING: AutoLinksPlugin unable to find ' + filename + ' in directory ' + self.base_docs_url)
+            return match.group(0)
+
+        # Construct the return link by replacing the filename with the relative path to the file
+        link = match.group(0).replace(match.group(2), rel_link_url)
+
+        return link
+
+class AutoLinksPlugin(BasePlugin):
+
+    def on_page_markdown(self, markdown, page, config, site_navigation=None, **kwargs):
+
+        # Getting the root location of markdown source files
+        base_docs_url = config["docs_dir"]
+
+        # Getting the page url that we are linking from
+        page_url = page.file.src_path
+
+        # Look for matches and replace
+        markdown = re.sub(AUTOLINK_RE, AutoLinkReplacer(base_docs_url, page_url), markdown)
+
+        return markdown

mkdocs_autolinks_plugin/plugin.py

@@ -0,0 +1 @@
+mkdocs==1.0.3

requirements.txt

@@ -0,0 +1,2 @@
+[metadata]
+description-file = README.md

setup.cfg

@@ -0,0 +1,36 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='mkdocs-autolinks-plugin',
+    version='0.1.0',
+    description='An MkDocs plugin',
+    long_description='An MkDocs plugin that automagically generates relative links between markdown pages',
+    keywords='mkdocs',
+    url='https://github.com/midnightprioriem/mkdocs-autolinks-plugin',
+    download_url='https://github.com/midnightprioriem/mkdocs-autolinks-plugin/archive/v_010.tar.gz',
+    author='Zach Hannum',
+    author_email='zacharyhannum@gmail.com',
+    license='MIT',
+    python_requires='>=2.7',
+    install_requires=[
+        'mkdocs>=1.0.4',
+    ],
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: Developers',
+        'Intended Audience :: Information Technology',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3 :: Only',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7'
+    ],
+    packages=find_packages(),
+    entry_points={
+        'mkdocs.plugins': [
+            'autolinks = mkdocs_autolinks_plugin.plugin:AutoLinksPlugin',
+        ]
+    }
+)