mkdocs-wikilinks-plugin 0.1.0__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/PKG-INFO +18 -81
  2. mkdocs_wikilinks_plugin-0.1.2/README.md +116 -0
  3. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_wikilinks_plugin.egg-info/PKG-INFO +18 -81
  4. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/setup.py +2 -2
  5. mkdocs_wikilinks_plugin-0.1.0/README.md +0 -191
  6. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/LICENSE +0 -0
  7. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/__init__.py +0 -0
  8. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/file_mapper.py +0 -0
  9. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/plugin.py +0 -0
  10. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/replacer.py +0 -0
  11. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/scanners/__init__.py +0 -0
  12. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/scanners/base_link_scanner.py +0 -0
  13. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/scanners/md_link_scanner.py +0 -0
  14. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/scanners/reference_link_scanner.py +0 -0
  15. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/scanners/wiki_link_scanner.py +0 -0
  16. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_ezlinks_plugin/types.py +0 -0
  17. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_wikilinks_plugin.egg-info/SOURCES.txt +0 -0
  18. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_wikilinks_plugin.egg-info/dependency_links.txt +0 -0
  19. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_wikilinks_plugin.egg-info/entry_points.txt +0 -0
  20. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_wikilinks_plugin.egg-info/requires.txt +0 -0
  21. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/mkdocs_wikilinks_plugin.egg-info/top_level.txt +0 -0
  22. {mkdocs_wikilinks_plugin-0.1.0 → mkdocs_wikilinks_plugin-0.1.2}/setup.cfg +0 -0
@@ -1,8 +1,8 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: mkdocs-wikilinks-plugin
3
- Version: 0.1.0
3
+ Version: 0.1.2
4
4
  Summary: A mkdocs plugin that makes linking to other documents easy.
5
- Home-page: https://github.com/carloslab-ai/mkdocs-wikilinks-plugin
5
+ Home-page: https://github.com/carlos-truong/mkdocs-wikilinks-plugin
6
6
  Author: Carlos
7
7
  Author-email: carlos.truong.dev@gmail.com
8
8
  License: MIT
@@ -18,12 +18,24 @@ License-File: LICENSE
18
18
  Requires-Dist: mkdocs
19
19
  Requires-Dist: dataclasses>=0.7; python_version < "3.7.0"
20
20
  Requires-Dist: pygtrie==2.*
21
+ Dynamic: author
22
+ Dynamic: author-email
23
+ Dynamic: classifier
24
+ Dynamic: description
25
+ Dynamic: description-content-type
26
+ Dynamic: home-page
27
+ Dynamic: keywords
28
+ Dynamic: license
29
+ Dynamic: license-file
30
+ Dynamic: requires-dist
31
+ Dynamic: requires-python
32
+ Dynamic: summary
21
33
 
22
34
  *Fork*
23
35
  To install this fork :
24
- `pip install mkdocs-ezlinked-plugin`
36
+ `pip install mkdocs-wikilinks-plugin`
25
37
 
26
- # mkdocs-ezlinks-plugin
38
+ # mkdocs-wikilinks-plugin
27
39
 
28
40
  ![](logo.png)
29
41
 
@@ -42,7 +54,7 @@ with a variety of features:
42
54
 
43
55
  # Install
44
56
  ```
45
- pip install mkdocs-ezlinks-plugin
57
+ pip install mkdocs-wikilinks-plugin
46
58
  ```
47
59
 
48
60
  Edit your mkdocs configuration file to enable the plugin:
@@ -54,88 +66,13 @@ plugins:
54
66
  > **NOTE**
55
67
  > If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.
56
68
 
57
- # Release Log
58
-
59
- ## Release 0.1.14
60
- This is a bugfix release.
61
-
62
- Issues addressed:
63
- * GH issue #35, `Links between deeply nested subfolders fails.`
64
- Dev @Mara-Li reported an issue with wikilinks between deeply nested subfolders failing due to an incorrectly
65
- rendered relative link to the file.
66
-
67
- * An unreported Windows usage issue
68
- It's possible this bug existed for quite some time. Basically, on Windows, there was disagreement between the
69
- path separators used at different points in the file mapping and searching process. This unifies it to store
70
- and search for paths only with the `/` delimiter instead of the OS defined separator.
71
-
72
-
73
- ## Release 0.1.13
74
- Adds support for Reference Link parsing. This is to support certain Foam editors, which generate [Reference Links](https://spec.commonmark.org/0.29/#reference-link).
75
-
76
- Issues Addressed:
77
- * GH Issue #31, `Add support for reference link definitions`. Allows compatibility with certain Foam editors which generate Reference Links.
78
-
79
- ## Release 0.1.12
80
- This is a bugfix release.
81
-
82
- Issues addressed:
83
- * GH issue #25, `Absolute links not using http:// or https:// are treated as relative`.
84
- Dev @robbcrg (thanks!) reported that links with protocol schemes other than those two should also be treated as
85
- absolute links. The regex will exclude any link from a conformant protocol scheme from being converted using EzLinks.
86
-
87
- * GH Issue #27, `Dictionary file cache is not being leveraged`.
88
- An inverted comparison led to the fast file cache lookup never really being exercised. Now, if a filename is unique, it will find it in the fast file cache first, saving a more expensive full trie lookup.
89
-
90
- ## Release 0.1.11
91
- This is a bugfix release. The prior release switched from a dictionary lookup to a prefix trie lookup strategy, which allowed for better disambiguation between links, but is more expensive. The bug was that, even if a link was direct, it would trigger a full trie search. Now, direct links
92
- are checked and returned directly if the file exists.
93
-
94
- Additionally, a slight performance improvement was made where, in the case that a filename is unique to the entire site, it will rely on a fast dictionary lookup instead of a trie lookup.
95
-
96
69
  # Configuration Options
97
70
  ```
98
71
  plugins:
99
72
  - search
100
73
  - ezlinks:
101
- warn_ambiguities: {true|false}
102
74
  wikilinks: {true|false}
103
- reference_links: {true|false}
104
75
  ```
105
- ## warn_ambiguities
106
- 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:
107
-
108
- ```
109
- + folder1/
110
- +-- index.md
111
- + folder2/
112
- +-- index.md
113
- ```
114
-
115
- If you had any links that targeted `index.md`, EzLinks is not able to determine _which_ of the instances of `index.md` to target, thus it is ambiguous.
116
-
117
- ### Disambiguating links
118
- By default, EzLinks will attempt to resolve the ambiguity automatically. It does this by searching for the file closest to the file that is linking (with respect to the folder hierarchy).
119
-
120
- ```
121
- + guide/
122
- + test.md
123
- + getting_started/
124
- + index.md
125
- + tutorials/
126
- - test.md
127
- + getting_started/
128
- + index.md
129
- + more_advanced/
130
- + index.md
131
- ```
132
- If you placed a link inside `guide/getting_started/index.md` such as `[Test](test)`, the resulting link has ambiguity, but in the default case, the `guide/test.md` file is _closer_ than the `tutorials/test.md`, therefore, it will select that file.
133
-
134
- In the circumstance above, it would be possible to disambiguate _which_ `test.md` by including the containing folder, e.g. `guide/test.md` or `tutorials/test.md`. Note: This also works in conjunction with extension-less targets, e.g. `guide/test` and `tutorials/test`.
135
-
136
- This disambiguation can continue with as many parent directories are specified, for instance `folder1/subfolder1/subfolder2/test.md`, specifying as many path components as necessary to fully disambiguate the links.
137
-
138
- This method of disambiguation is supported by each of the supported link formats (MD links, wiki/roamlinks). For instance, you can use `[[folder1/index|Link Title]]` and `[[folder2/index.md]]`.
139
76
 
140
77
  ## wikilinks
141
78
  Determines whether to scan for wikilinks or not (See [WikiLink Support](#wikilink-support)).
@@ -0,0 +1,116 @@
1
+ *Fork*
2
+ To install this fork :
3
+ `pip install mkdocs-wikilinks-plugin`
4
+
5
+ # mkdocs-wikilinks-plugin
6
+
7
+ ![](logo.png)
8
+
9
+ Plugin for mkdocs which enables easier linking between pages.
10
+
11
+ This plugin was written in order to provide an up-to-date and
12
+ feature complete plugin for easily referencing documents
13
+ with a variety of features:
14
+
15
+ * Optimized file name lookup
16
+ * Code Block Preservation
17
+ * File name linking (e.g. `[Text](file#anchor "title")`)
18
+ * Absolute paths (e.g. `[Text](/link/to/file.md)`)
19
+ * WikiLinks support (e.g. `[[Link#anchor|Link Title]]`)
20
+ * Reference Link support (e.g. `[foo]: bar/ "Foo Title"`)
21
+
22
+ # Install
23
+ ```
24
+ pip install mkdocs-wikilinks-plugin
25
+ ```
26
+
27
+ Edit your mkdocs configuration file to enable the plugin:
28
+ ```
29
+ plugins:
30
+ - search
31
+ - ezlinks
32
+ ```
33
+ > **NOTE**
34
+ > If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.
35
+
36
+ # Configuration Options
37
+ ```
38
+ plugins:
39
+ - search
40
+ - ezlinks:
41
+ wikilinks: {true|false}
42
+ ```
43
+
44
+ ## wikilinks
45
+ Determines whether to scan for wikilinks or not (See [WikiLink Support](#wikilink-support)).
46
+ > **NOTE**
47
+ > 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.
48
+
49
+ ## reference_links
50
+ 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"`)
51
+
52
+ # Features
53
+ ## Filename Links
54
+ Given a layout such as
55
+ ```
56
+ - index.md
57
+ - folder/
58
+ +-- filename.md
59
+ +-- image.png
60
+ ```
61
+
62
+ The following links will result in the following translations,
63
+
64
+ |Link|Translation|
65
+ |----|-----------|
66
+ | `[Link Text](filename)` | `[Link Text](folder/filename.md)`|
67
+ | `[Link Text](filename#Anchor)` | `[Link Text](folder/filename.md#Anchor)`|
68
+ | `[Link Text](filename.md)` | `[Link Text](folder/filename.md)`|
69
+ | `[Link Text](filename.md#Anchor)` | `[Link Text](folder/filename.md#Anchor)` |
70
+ | `![Image Alt Text](image)` | `![Image Alt Text](folder/image.png)` |
71
+ | `![Image Alt Text](image.png)` | `![Image Alt Text](folder/image.png)` |
72
+ | `![Image Alt Test](image "Image Title")` | `![Image Alt Text](folder/image.png "Image Title")` |
73
+
74
+
75
+ ## Absolute Links
76
+ Given a layout such as
77
+ ```
78
+ - static/
79
+ +-- image.png
80
+ - folder/
81
+ +-- document.md
82
+ - index.md
83
+ ```
84
+ Given that we are entering the links into the `folder/document.md` file,
85
+
86
+ |Link|Translation|
87
+ |----|-----------|
88
+ | `![Link Text](/static/image.png)` | `![Link Text](../static/image.png)` |
89
+
90
+ # WikiLink Support
91
+ Given a layout such as
92
+ ```
93
+ - folder1/
94
+ +-- main.md
95
+ - folder2/
96
+ +-- page-name.md
97
+ - images/
98
+ +-- puppy.png
99
+ ```
100
+ and these links are entered in `folder1/main.md`, this is how wikilinks will be translated
101
+
102
+ |Link|Translation|
103
+ |----|-----------|
104
+ | `[[Page Name]]` | `[Page Name](../folder2/page-name.md)` |
105
+ | `![[Puppy]]` | `![Puppy](../images/puppy.png)` | `[[Page Name#Section Heading]]` | `[Page Name](../relative/path/to/page-name.md#section-heading)` |
106
+ | `[[Page Name\|Link Text]]` | `[Link Text](../folder2/page-name.md)` |
107
+ | `[[Page Name#Section Heading\|Link Text]]` | `[Link Text](../folder2/page-name.md#section-heading)` |
108
+
109
+ # Attribution
110
+ This work is highly inspired from the following plugins:
111
+ - [mkdocs-autolinks-plugin](https://github.com/midnightprioriem/mkdocs-autolinks-plugin/)
112
+ - [mkdocs-roamlinks-plugin](https://github.com/Jackiexiao/mkdocs-roamlinks-plugin)
113
+ - [mkdocs-abs-rel-plugin](https://github.com/sander76/mkdocs-abs-rel-plugin)
114
+
115
+ I have combined some the features of these plugins, fixed several existing bugs, and am adding features in order to
116
+ provide a cohesive, up-to-date, and maintained solution for the mkdocs community.
@@ -1,8 +1,8 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: mkdocs-wikilinks-plugin
3
- Version: 0.1.0
3
+ Version: 0.1.2
4
4
  Summary: A mkdocs plugin that makes linking to other documents easy.
5
- Home-page: https://github.com/carloslab-ai/mkdocs-wikilinks-plugin
5
+ Home-page: https://github.com/carlos-truong/mkdocs-wikilinks-plugin
6
6
  Author: Carlos
7
7
  Author-email: carlos.truong.dev@gmail.com
8
8
  License: MIT
@@ -18,12 +18,24 @@ License-File: LICENSE
18
18
  Requires-Dist: mkdocs
19
19
  Requires-Dist: dataclasses>=0.7; python_version < "3.7.0"
20
20
  Requires-Dist: pygtrie==2.*
21
+ Dynamic: author
22
+ Dynamic: author-email
23
+ Dynamic: classifier
24
+ Dynamic: description
25
+ Dynamic: description-content-type
26
+ Dynamic: home-page
27
+ Dynamic: keywords
28
+ Dynamic: license
29
+ Dynamic: license-file
30
+ Dynamic: requires-dist
31
+ Dynamic: requires-python
32
+ Dynamic: summary
21
33
 
22
34
  *Fork*
23
35
  To install this fork :
24
- `pip install mkdocs-ezlinked-plugin`
36
+ `pip install mkdocs-wikilinks-plugin`
25
37
 
26
- # mkdocs-ezlinks-plugin
38
+ # mkdocs-wikilinks-plugin
27
39
 
28
40
  ![](logo.png)
29
41
 
@@ -42,7 +54,7 @@ with a variety of features:
42
54
 
43
55
  # Install
44
56
  ```
45
- pip install mkdocs-ezlinks-plugin
57
+ pip install mkdocs-wikilinks-plugin
46
58
  ```
47
59
 
48
60
  Edit your mkdocs configuration file to enable the plugin:
@@ -54,88 +66,13 @@ plugins:
54
66
  > **NOTE**
55
67
  > If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.
56
68
 
57
- # Release Log
58
-
59
- ## Release 0.1.14
60
- This is a bugfix release.
61
-
62
- Issues addressed:
63
- * GH issue #35, `Links between deeply nested subfolders fails.`
64
- Dev @Mara-Li reported an issue with wikilinks between deeply nested subfolders failing due to an incorrectly
65
- rendered relative link to the file.
66
-
67
- * An unreported Windows usage issue
68
- It's possible this bug existed for quite some time. Basically, on Windows, there was disagreement between the
69
- path separators used at different points in the file mapping and searching process. This unifies it to store
70
- and search for paths only with the `/` delimiter instead of the OS defined separator.
71
-
72
-
73
- ## Release 0.1.13
74
- Adds support for Reference Link parsing. This is to support certain Foam editors, which generate [Reference Links](https://spec.commonmark.org/0.29/#reference-link).
75
-
76
- Issues Addressed:
77
- * GH Issue #31, `Add support for reference link definitions`. Allows compatibility with certain Foam editors which generate Reference Links.
78
-
79
- ## Release 0.1.12
80
- This is a bugfix release.
81
-
82
- Issues addressed:
83
- * GH issue #25, `Absolute links not using http:// or https:// are treated as relative`.
84
- Dev @robbcrg (thanks!) reported that links with protocol schemes other than those two should also be treated as
85
- absolute links. The regex will exclude any link from a conformant protocol scheme from being converted using EzLinks.
86
-
87
- * GH Issue #27, `Dictionary file cache is not being leveraged`.
88
- An inverted comparison led to the fast file cache lookup never really being exercised. Now, if a filename is unique, it will find it in the fast file cache first, saving a more expensive full trie lookup.
89
-
90
- ## Release 0.1.11
91
- This is a bugfix release. The prior release switched from a dictionary lookup to a prefix trie lookup strategy, which allowed for better disambiguation between links, but is more expensive. The bug was that, even if a link was direct, it would trigger a full trie search. Now, direct links
92
- are checked and returned directly if the file exists.
93
-
94
- Additionally, a slight performance improvement was made where, in the case that a filename is unique to the entire site, it will rely on a fast dictionary lookup instead of a trie lookup.
95
-
96
69
  # Configuration Options
97
70
  ```
98
71
  plugins:
99
72
  - search
100
73
  - ezlinks:
101
- warn_ambiguities: {true|false}
102
74
  wikilinks: {true|false}
103
- reference_links: {true|false}
104
75
  ```
105
- ## warn_ambiguities
106
- 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:
107
-
108
- ```
109
- + folder1/
110
- +-- index.md
111
- + folder2/
112
- +-- index.md
113
- ```
114
-
115
- If you had any links that targeted `index.md`, EzLinks is not able to determine _which_ of the instances of `index.md` to target, thus it is ambiguous.
116
-
117
- ### Disambiguating links
118
- By default, EzLinks will attempt to resolve the ambiguity automatically. It does this by searching for the file closest to the file that is linking (with respect to the folder hierarchy).
119
-
120
- ```
121
- + guide/
122
- + test.md
123
- + getting_started/
124
- + index.md
125
- + tutorials/
126
- - test.md
127
- + getting_started/
128
- + index.md
129
- + more_advanced/
130
- + index.md
131
- ```
132
- If you placed a link inside `guide/getting_started/index.md` such as `[Test](test)`, the resulting link has ambiguity, but in the default case, the `guide/test.md` file is _closer_ than the `tutorials/test.md`, therefore, it will select that file.
133
-
134
- In the circumstance above, it would be possible to disambiguate _which_ `test.md` by including the containing folder, e.g. `guide/test.md` or `tutorials/test.md`. Note: This also works in conjunction with extension-less targets, e.g. `guide/test` and `tutorials/test`.
135
-
136
- This disambiguation can continue with as many parent directories are specified, for instance `folder1/subfolder1/subfolder2/test.md`, specifying as many path components as necessary to fully disambiguate the links.
137
-
138
- This method of disambiguation is supported by each of the supported link formats (MD links, wiki/roamlinks). For instance, you can use `[[folder1/index|Link Title]]` and `[[folder2/index.md]]`.
139
76
 
140
77
  ## wikilinks
141
78
  Determines whether to scan for wikilinks or not (See [WikiLink Support](#wikilink-support)).
@@ -3,7 +3,7 @@ from setuptools import setup, find_packages
3
3
  description = "A mkdocs plugin that makes linking to other documents easy."
4
4
  long_description = description
5
5
 
6
- version="0.1.0"
6
+ version="0.1.2"
7
7
 
8
8
  with open("README.md", "r") as f:
9
9
  long_description = f.read()
@@ -16,7 +16,7 @@ setup(
16
16
  long_description=long_description,
17
17
  long_description_content_type="text/markdown",
18
18
  keywords="mkdocs, wikilinks, ezlinks, obsidian, roam",
19
- url="https://github.com/carloslab-ai/mkdocs-wikilinks-plugin",
19
+ url="https://github.com/carlos-truong/mkdocs-wikilinks-plugin",
20
20
  author="Carlos",
21
21
  author_email="carlos.truong.dev@gmail.com",
22
22
  license="MIT",
@@ -1,191 +0,0 @@
1
- *Fork*
2
- To install this fork :
3
- `pip install mkdocs-ezlinked-plugin`
4
-
5
- # mkdocs-ezlinks-plugin
6
-
7
- ![](logo.png)
8
-
9
- Plugin for mkdocs which enables easier linking between pages.
10
-
11
- This plugin was written in order to provide an up-to-date and
12
- feature complete plugin for easily referencing documents
13
- with a variety of features:
14
-
15
- * Optimized file name lookup
16
- * Code Block Preservation
17
- * File name linking (e.g. `[Text](file#anchor "title")`)
18
- * Absolute paths (e.g. `[Text](/link/to/file.md)`)
19
- * WikiLinks support (e.g. `[[Link#anchor|Link Title]]`)
20
- * Reference Link support (e.g. `[foo]: bar/ "Foo Title"`)
21
-
22
- # Install
23
- ```
24
- pip install mkdocs-ezlinks-plugin
25
- ```
26
-
27
- Edit your mkdocs configuration file to enable the plugin:
28
- ```
29
- plugins:
30
- - search
31
- - ezlinks
32
- ```
33
- > **NOTE**
34
- > If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.
35
-
36
- # Release Log
37
-
38
- ## Release 0.1.14
39
- This is a bugfix release.
40
-
41
- Issues addressed:
42
- * GH issue #35, `Links between deeply nested subfolders fails.`
43
- Dev @Mara-Li reported an issue with wikilinks between deeply nested subfolders failing due to an incorrectly
44
- rendered relative link to the file.
45
-
46
- * An unreported Windows usage issue
47
- It's possible this bug existed for quite some time. Basically, on Windows, there was disagreement between the
48
- path separators used at different points in the file mapping and searching process. This unifies it to store
49
- and search for paths only with the `/` delimiter instead of the OS defined separator.
50
-
51
-
52
- ## Release 0.1.13
53
- Adds support for Reference Link parsing. This is to support certain Foam editors, which generate [Reference Links](https://spec.commonmark.org/0.29/#reference-link).
54
-
55
- Issues Addressed:
56
- * GH Issue #31, `Add support for reference link definitions`. Allows compatibility with certain Foam editors which generate Reference Links.
57
-
58
- ## Release 0.1.12
59
- This is a bugfix release.
60
-
61
- Issues addressed:
62
- * GH issue #25, `Absolute links not using http:// or https:// are treated as relative`.
63
- Dev @robbcrg (thanks!) reported that links with protocol schemes other than those two should also be treated as
64
- absolute links. The regex will exclude any link from a conformant protocol scheme from being converted using EzLinks.
65
-
66
- * GH Issue #27, `Dictionary file cache is not being leveraged`.
67
- An inverted comparison led to the fast file cache lookup never really being exercised. Now, if a filename is unique, it will find it in the fast file cache first, saving a more expensive full trie lookup.
68
-
69
- ## Release 0.1.11
70
- This is a bugfix release. The prior release switched from a dictionary lookup to a prefix trie lookup strategy, which allowed for better disambiguation between links, but is more expensive. The bug was that, even if a link was direct, it would trigger a full trie search. Now, direct links
71
- are checked and returned directly if the file exists.
72
-
73
- Additionally, a slight performance improvement was made where, in the case that a filename is unique to the entire site, it will rely on a fast dictionary lookup instead of a trie lookup.
74
-
75
- # Configuration Options
76
- ```
77
- plugins:
78
- - search
79
- - ezlinks:
80
- warn_ambiguities: {true|false}
81
- wikilinks: {true|false}
82
- reference_links: {true|false}
83
- ```
84
- ## warn_ambiguities
85
- 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:
86
-
87
- ```
88
- + folder1/
89
- +-- index.md
90
- + folder2/
91
- +-- index.md
92
- ```
93
-
94
- If you had any links that targeted `index.md`, EzLinks is not able to determine _which_ of the instances of `index.md` to target, thus it is ambiguous.
95
-
96
- ### Disambiguating links
97
- By default, EzLinks will attempt to resolve the ambiguity automatically. It does this by searching for the file closest to the file that is linking (with respect to the folder hierarchy).
98
-
99
- ```
100
- + guide/
101
- + test.md
102
- + getting_started/
103
- + index.md
104
- + tutorials/
105
- - test.md
106
- + getting_started/
107
- + index.md
108
- + more_advanced/
109
- + index.md
110
- ```
111
- If you placed a link inside `guide/getting_started/index.md` such as `[Test](test)`, the resulting link has ambiguity, but in the default case, the `guide/test.md` file is _closer_ than the `tutorials/test.md`, therefore, it will select that file.
112
-
113
- In the circumstance above, it would be possible to disambiguate _which_ `test.md` by including the containing folder, e.g. `guide/test.md` or `tutorials/test.md`. Note: This also works in conjunction with extension-less targets, e.g. `guide/test` and `tutorials/test`.
114
-
115
- This disambiguation can continue with as many parent directories are specified, for instance `folder1/subfolder1/subfolder2/test.md`, specifying as many path components as necessary to fully disambiguate the links.
116
-
117
- This method of disambiguation is supported by each of the supported link formats (MD links, wiki/roamlinks). For instance, you can use `[[folder1/index|Link Title]]` and `[[folder2/index.md]]`.
118
-
119
- ## wikilinks
120
- Determines whether to scan for wikilinks or not (See [WikiLink Support](#wikilink-support)).
121
- > **NOTE**
122
- > 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.
123
-
124
- ## reference_links
125
- 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"`)
126
-
127
- # Features
128
- ## Filename Links
129
- Given a layout such as
130
- ```
131
- - index.md
132
- - folder/
133
- +-- filename.md
134
- +-- image.png
135
- ```
136
-
137
- The following links will result in the following translations,
138
-
139
- |Link|Translation|
140
- |----|-----------|
141
- | `[Link Text](filename)` | `[Link Text](folder/filename.md)`|
142
- | `[Link Text](filename#Anchor)` | `[Link Text](folder/filename.md#Anchor)`|
143
- | `[Link Text](filename.md)` | `[Link Text](folder/filename.md)`|
144
- | `[Link Text](filename.md#Anchor)` | `[Link Text](folder/filename.md#Anchor)` |
145
- | `![Image Alt Text](image)` | `![Image Alt Text](folder/image.png)` |
146
- | `![Image Alt Text](image.png)` | `![Image Alt Text](folder/image.png)` |
147
- | `![Image Alt Test](image "Image Title")` | `![Image Alt Text](folder/image.png "Image Title")` |
148
-
149
-
150
- ## Absolute Links
151
- Given a layout such as
152
- ```
153
- - static/
154
- +-- image.png
155
- - folder/
156
- +-- document.md
157
- - index.md
158
- ```
159
- Given that we are entering the links into the `folder/document.md` file,
160
-
161
- |Link|Translation|
162
- |----|-----------|
163
- | `![Link Text](/static/image.png)` | `![Link Text](../static/image.png)` |
164
-
165
- # WikiLink Support
166
- Given a layout such as
167
- ```
168
- - folder1/
169
- +-- main.md
170
- - folder2/
171
- +-- page-name.md
172
- - images/
173
- +-- puppy.png
174
- ```
175
- and these links are entered in `folder1/main.md`, this is how wikilinks will be translated
176
-
177
- |Link|Translation|
178
- |----|-----------|
179
- | `[[Page Name]]` | `[Page Name](../folder2/page-name.md)` |
180
- | `![[Puppy]]` | `![Puppy](../images/puppy.png)` | `[[Page Name#Section Heading]]` | `[Page Name](../relative/path/to/page-name.md#section-heading)` |
181
- | `[[Page Name\|Link Text]]` | `[Link Text](../folder2/page-name.md)` |
182
- | `[[Page Name#Section Heading\|Link Text]]` | `[Link Text](../folder2/page-name.md#section-heading)` |
183
-
184
- # Attribution
185
- This work is highly inspired from the following plugins:
186
- - [mkdocs-autolinks-plugin](https://github.com/midnightprioriem/mkdocs-autolinks-plugin/)
187
- - [mkdocs-roamlinks-plugin](https://github.com/Jackiexiao/mkdocs-roamlinks-plugin)
188
- - [mkdocs-abs-rel-plugin](https://github.com/sander76/mkdocs-abs-rel-plugin)
189
-
190
- I have combined some the features of these plugins, fixed several existing bugs, and am adding features in order to
191
- provide a cohesive, up-to-date, and maintained solution for the mkdocs community.