orbikm / mkdocs-ezlinks-plugin Goto Github PK
View Code? Open in Web Editor NEWPlugin for mkdocs which enables easier linking between pages
License: MIT License
Plugin for mkdocs which enables easier linking between pages
License: MIT License
I have my docs organized in the following structure:
docs
└── courses
├── A
│ ├── index.md
│ └── target.md
├── B
│ ├── index.md
│ └── target.md
└── C
├── index.md
└── target.md
Every index page contains a link: [Target](target)
. This worked fine for A and B.
However, after adding C all the links in the rendered HTML pages point to "../C/target" instead of their own target.
Can I do something to prevent this or do I need to use [Target](target.md)
so ezlinks use the file?
Latest version 0.1.14 does not work anymore with mkdocs 1.4.0
Basically links are corrupt.
(WARNING - Documentation file 'yyy/xxx.md' contains a link to 'aaa/..\bbb\ccc.md' which is not found in the documentation files.)
(Remark: Latest version 0.1.14 still work anymore with mkdocs 1.3.1)
Seems following change in mkdocs 1.4.0 is causing the issue:
https://www.mkdocs.org/about/release-notes/#replace-filesrc_path-to-not-deal-with-backslashes-2930
Advised on that page:
Use File.src_uri instead of File.src_path
Use os.path.* instead of posixpath.*
I quickly tested it and it seems to indeed solve the compatibility issues.
Sorry, as I can't reopen the my last issue, I create a new :)
So, the problem still persist :
It doesn't seems to work, on my side at last (windows 11) :
Image are localized in assets/img
who is in directly under docs (as docs/assets/img
) and Mnémosyne folder is located in docs/Roleplay/Personnages/Mnémosyne
Note : I use, effectively, Windows 11.
On windows, the src is missing the \
between the source directory shorthand
<img alt="image alt text" src="....\assets\images\image_20.png">
should be
<img alt="image alt text" src="..\..\assets\images\image_20.png">
Should probably also make these /
instead, even on Windows
When the file index.md is generated to be the file index.html, 3 different links to 3 different files are generated as 1 same href link.
Here are the original links:
[[./📜 Tài nguyên/💎 Giới thiệu về Obsidian/index|💎 Giới thiệu về Obsidian]]
[[./⚔️ Lớp Obsidian và Git/index|⚔️ Lớp Obsidian và Git]]
[[./⚡Hiểu biết sâu/index|⚡Hiểu biết sâu]]
They are generated as:
<a href="%F0%9F%93%9C%20T%C3%A0i%20nguy%C3%AAn/%F0%9F%92%8E%20Gi%E1%BB%9Bi%20thi%E1%BB%87u%20v%E1%BB%81%20Obsidian/Theo%20t%C3%ADnh%20n%C4%83ng%20c%E1%BB%A7a%20plugin/" title="💎 Giới thiệu về Obsidian">💎 Giới thiệu về Obsidian</a>
<a href="%F0%9F%93%9C%20T%C3%A0i%20nguy%C3%AAn/%F0%9F%92%8E%20Gi%E1%BB%9Bi%20thi%E1%BB%87u%20v%E1%BB%81%20Obsidian/Theo%20t%C3%ADnh%20n%C4%83ng%20c%E1%BB%A7a%20plugin/" title="⚔️ Lớp Obsidian và Git">⚔️ Lớp Obsidian và Git</a>
<a href="%F0%9F%93%9C%20T%C3%A0i%20nguy%C3%AAn/%F0%9F%92%8E%20Gi%E1%BB%9Bi%20thi%E1%BB%87u%20v%E1%BB%81%20Obsidian/Theo%20t%C3%ADnh%20n%C4%83ng%20c%E1%BB%A7a%20plugin/" title="⚡Hiểu biết sâu">⚡Hiểu biết sâu</a>
Notice the titles are different.
Why is this? Other pages seems fine. Here is the mkdocs.yml, but I don't think it has any problem in it,
Should support converting ![](picture.png "Image Title")
to ![](../path/to/image.png "Image Title")
When I try to use ezlinks do I get the following error on mkdocs serve
:
https://paste.helpch.at/rileqagejo.sql
I use MkDocs 1.1 just downloaded the plugin today (in the past 30 minutes) and also use Material for MkDocs v7 alongside all the dependencies it downloads
I faced with an issue when the markdown[[email protected]](mailto:[email protected])
was converted into relative link.
Unfortunately, I didn't find how to avoid conversion of e-mail protocol in the documentation. 😢
Hello,
I'm new to ezlinks, as I'm trying to work on both obsidian, and mkdocs publication of the obsidian vault.
It looks like the bug #35 has not been fixed, as I still have the issue.
Here is the structure used:
content/
├─ blog/
│ ├─ posts/
│ │ ├─ post.md
├─ campaign/
│ ├─ characters/
│ │ ├─ john.md
in the post.md
file, I use this code:
...
This is [[John]]
...
the john.md
contains:
# John
Hey I'm John!
When generating the site, the created link go up to the root, but does not go down to the john directory:
INFO - Doc file 'blog/posts/post.md' contains an unrecognized relative link '../../john', it was left as is.
It looks like the #35 was not fixed, as per the last comment from @Lisandra-dev ?
It's happening in linux by the way. Not sure it's of any help.
In Obsidian, if two files have the same name and are in different folders, the link will contain a slash.
for example:
- folder1
+-- index.md
- folder2
+-- index.md
In Obsidian, the link for the first will be [[folder1/index]]
and for the second it will be [[folder2/index]]
. In other words: in order to distinguish between the files, it uses a namespace. There is a chance of having multiple layers of namespaces as well.
A temporary workaround is to rename the files but I suggest that a fix.
Thanks for the plugin btw.
With this mkdocs.yml
:
site_name: test
plugins:
- ezlinks:
wikilinks: true
And this folder structure:
docs/
├── index.md
└── a/
└── index.md
After the build we will have:
site/
├── index.html
└── a/
└── index.html
If in docs/index.md
you have this content:
[[a/index]]
[[a/index.md]]
[[./a/index]]
[[./a/index.md]]
Then in site/index.html
the html will be:
| docs/index.md | site/index.html | Correct? |
| ---------------- | -------------------------------------------------- | -------- |
| [[a/index]] | <a href="a/" title="a/index">a/index</a> | ✔ |
| [[a/index.md]] | <a href="a/" title="a/index.md">a/index.md</a> | ✔ |
| [[./a/index]] | <a href="a/index" title="./a/index">./a/index</a> | ❌ |
| [[./a/index.md]] | <a href="a/" title="./a/index.md">./a/index.md</a> | ✔ |
At the same time Mkdocs will notice this:
INFO - Doc file 'index.md' contains an
unrecognized relative link
'a/index', it was left as is. Did
you mean 'a/index.md'?
ezlinks is using mdx_wikilink_plus which throws this error:
The provided example works:
![[Puppy]]
However, if I use a link like this, which Obsidian.md creates, the generated link is broken:
![[Puppy.png]]
I'm not sure if this is intentional or not.
Some wiki software (namely Gollum) uses a wikilink syntax that is "backwards" from the standard way wikilinks work.
Where normal wikilinks are of the format [[Page Name|Link Text]]
, Gollum link tags are of the format [[Link Text|Page Name]]
.
Since ezlinks aims for broad compatibility with many different types of link formats, would it be acceptable to add a configuration option to support this "reverse" version of wikilinks?
I encountered a weird behaviour, where the plugin doesn't seem to handle filename links at random, which causes them to turn into default relative links.
My folder structure (relative to the docs folder) is as follows:
- assets/
+- css/ // CSS stuff
+- img/ // Images
+- icons/ // Custom SVG Icons
- index.md
- github/
+- general.md
+- issues-pull-requests.md
+- wiki.md
The issue appeared in issues-pull-requests.md
when I tried to link to general.md
using
[:brands-github: General](general){: .md-button }
The link was rendered literally, meaning the resulting link, relative to the page, was issues-pull-requests/general
What makes it more confusing is, that I use the same link ([general features](general)
) on a different part in the same file and the resulting link actually points to the page in question.
Here's the part of my file, where it happens:
!!! pages "Pages"
[:brands-github: General](general){: .md-button }
# Issues/Pull Requests
This page lists all features that can be used across all issues and Pull requests on GitHub.
!!! info "Note"
Issues and Pull requests support all [general features](general).
The part inside the Pages admonition, which is a custom admonition type I set up, is not working, while the link in the info admonition is.
I have a guess what could be a possible cause. This started happening, when I changed the Link to a file from a total https-link to a basic filename link.
Perhaps the Plugin became somewhat confused and didn't handle the first link right.
Or maybe a cause could be reference links? Although I doubt this as I didn't encounter this issue anywhere else, where I also use those reference links...
An inverted comparison led to the fast file cache lookup never really being exercised. It was not handling the reduction of non-unique file names out of the dict. Therefore, when it would come time to check whether or not to use the unique file lookup, it would never contain any actual files.
I am a user of Foam. When I write note with Foam, it generate link reference definitions for wikilinks, but ezlinks is not aware of those. I think link reference definitions are helpful for generate links.
Hey there, I have a lot of warning about duplicate file names but since I use absolute links, all of them resolve correctly. Is there a way I could disable warnings for these?
The link [[#Section Heading]]
should convert to [Section Heading](#section-heading)
.
The link does not get matched by the wikilinks regex pattern. This is because it currently requires link text to exist before an anchor This should be trivially modified to accept either or.
I use indexe.navigations (see here), and I think I have an idea to get the best result with index : using the frontmatter.
Use case / Problem
I use Obsidian (the best note taking app in the world, yes). I often make links with "index" files (cf navigation.indexes de Material). In fact, it will regularly happen that there will be several times files named Index.
A first solution would be to get the closest index file (in the same folder) but it is common for me to quote indexes present in other folders, without necessarily quoting the whole path (a script takes care of converting the wikilinks paths by replacing the name of the "real" file by the index)
In fact, citations can quickly point to bad links.
Solution
By using python-frontmatter, it becomes possible to find the metadata of the files. When an ambiguity is found, the file can be checked.
My idea would be to use, in these cases, the title
field rather than the actual file title, with the title being indicated by the alias.
Finally, we use an "extra" indication in the wikilinks to point to the real file:
[[index|yaml_title]]
will thus point to the file whose title is the same as the one given in the yaml alias.
In case of an index with an alias that does not match any title, just take the closest one, i.e. using the current method.
Note: I'm not familiar with Mkdocs plugins yet, so I guess it's also possible to find the "yaml" titles of all files without going through the frontmatter.
Hi, I was trying to use your plugin but I encountered some issues:
python setup.py install
in my case did not copy the "scanners" folder to the package folder (/usr/lib/python3.9/site-packages/mkdocs_ezlinks_plugin/), and I had to do it manually. Is this desired?
In my mkdocs.yml
, the following
- ezlinks:
- wikilinks: {true|false}
throwed ERROR - Config value: 'plugins'. Error: Invalid config options for the "ezlinks" plugin.
, so I guess it should be:
- ezlinks:
wikilinks: {true|false}
I am getting a bunch of
WARNING - Duplicate filename `KaTeX_Size3-Regular` detected. Linking to it will only match the first file.
WARNING - Duplicate filename `KaTeX_Size3-Regular` detected. Linking to it will only match the first file.
WARNING - Duplicate filename `KaTeX_Size4-Regular` detected. Linking to it will only match the first file.
WARNING - Duplicate filename `KaTeX_Size4-Regular` detected. Linking to it will only match the first file.
WARNING - Duplicate filename `katex` detected. Linking to it will only match the first file.
# [ ... ]
I also have references to many "index.md" files, but I never entered them in square brackets.
KaTeX source files for instance are css files with multiple lines like this:
src: url(fonts/KaTeX_Size3-Regular.woff2) format('woff2'), url(fonts/KaTeX_Size3-Regular.woff) format('woff'), url(fonts/KaTeX_Size3-Regular.ttf) format('truetype');
Should the plugin ignore non markdown files/link format?
I am also getting a bunch of
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://www.mkdocs.org' in file map.
WARNING - Did not find 'https://example.org' in file map.
WARNING - Did not find 'https://example.com' in file map.
# [...]
Should the plugin ignore URLs starting with "http://" or "https://"?
I faced with an issue when the markdown[[email protected]](mailto:[email protected])
was converted into relative link.
Unfortunately, I didn't find how to avoid conversion of e-mail protocol in the documentation. 😢
In my case I am using IntelliJ and create links to allow me to edit any document from my editor using the Jetbrains Toolbox. The URL is of the form:
Hello. On my project, wikilinks doesn't seems to work.
My folder tree is :
docs/
├─ assets/
│ ├─ img/
│ │ ├─ img_char1.png
├─ Roleplay/
│ ├─ characters/
│ │ ├─ char1.md
│ ├─ references/
│ │ ├─ ref char1.md
img
doesn't workchar1
to ref char1
doesn't work.Links is in a short path, as : [[filename]]
I have 404 error and the path pointed by links are :
After some try, it seems that after the 3rd folder, the links generations are broken.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.