Option to disable warnings

[Stanzilla]

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?

[orbikm]

Ok, so there's two types of messages regarding duplicated filenames. One occurs during scanning of the docs directory. This is a debug warning, and respects filtering based on your current mkdocs verbosity settings. This message can pretty much always be safely ignored, as in and of itself, it is not dangerous. This is why that message is marked as debug, as it can potentially give information in the case that something is not functional, but otherwise can be ignored.

The other message given out is a warning. This is a bit more serious, because if you have two files named index.md in separate folders, there's currently no way to disambiguate which of the files the link should target. This emits as a Warning.

In the case of an absolute link being encountered (with a leading /), it should never emit that warning, as it simply skips that logic if it encounters an absolute link.

I would like some additional information from you, if you wouldn't mind:

1. Log of the specific warning you're encountering
2. Full source of the link that caused the warning to be emitted

If you also could potentially either describe a minimalistic repro site setup, it would help me understand the specific issue you're having.

[Stanzilla]

An example would be this:

WARNING -  [EzLinks] Link targeting a duplicate file 'api/index.md'.
  [0]   - index.md <-- Active
  [1]   - api/index.md 
  [2]   - creator_kit/index.md 

WARNING -  [EzLinks] Link targeting a duplicate file 'img/EditorManual/icons/image3.png'.
  [0]   - img/EditorManual/icons/image3.png <-- Active
  [1]   - img/EnvironIntro/image3.png 
  [2]   - img/LightBulb/image3.png 
  [3]   - img/Materials/image3.png 
  [4]   - img/ModelingBasics/image3.png 
  [5]   - img/SceneCreation/image3.png 

WARNING -  [EzLinks] Link targeting a duplicate file 'img/EditorManual/icons/image4.png'.
  [0]   - img/EditorManual/icons/image4.png <-- Active
  [1]   - img/EnvironIntro/image4.png 
  [2]   - img/Materials/image4.png 
  [3]   - img/ModelingBasics/image4.png 

WARNING -  [EzLinks] Link targeting a duplicate file 'img/EditorManual/icons/image8.png'.
  [0]   - img/EditorManual/icons/image8.png <-- Active
  [1]   - img/EnvironIntro/image8.png 
  [2]   - img/LightBulb/image8.png 
  [3]   - img/Materials/image8.png 
  [4]   - img/ModelingBasics/image8.png 

I can get a test branch up in a bit.

[orbikm]

I believe if you put a leading / in front of those links, it will work.

I believe it's currently stripping away the path & just checking the filename, because it does not think it is an absolute path.

[Stanzilla]

That fixed some of them, I still get the warnings for things like these though:

WARNING -  [EzLinks] Link targeting a duplicate file '../img/scripting/createNewScript.png'.
  [0]   - img/EditorManual/PersistentStorage/createNewScript.png <-- Active
  [1]   - img/scripting/createNewScript.png 

WARNING -  [EzLinks] Link targeting a duplicate file '../api/index.md'.
  [0]   - index.md <-- Active
  [1]   - api/index.md 
  [2]   - creator_kit/index.md 

WARNING -  [EzLinks] Link targeting a duplicate file '../api/index.md'.
  [0]   - index.md <-- Active
  [1]   - api/index.md 
  [2]   - creator_kit/index.md 

[orbikm]

Those links are not absolute links though. Absolute links will always start with a /, which indicates the link is to be relative to the site root. Links that start with ../ are relative links, as .. is equivalent to "up one directory from where the current file is."

If you simply make those links: /api/index.md, /img/scripting/createNewScript.png it will work.

[Stanzilla]

Hrm that does cause them to no longer be clickable/properly linked in VSCode though...

[orbikm]

Hrm that does cause them to no longer be clickable/properly linked in VSCode though...

So, this is going to be out of the scope of this plugin. This plugin executes as part of a build step. In this step, it analyzes all links and converts them from absolute/wiki/roam to proper md links. This only occurs as part of the build, and the links are not modified in the source markdown. The converted links will be embedded inside the generated output properly, which makes the links functional on the context of a website.

If you require the links to work from VScode, you'd likely need to find an extension that handled this type of absolute->relative links extension (if one exists).

[Stanzilla]

OKay I see, I was just used to this working from the mkdocs-autolinks plugin!

[orbikm]

OKay I see, I was just used to this working from the mkdocs-autolinks plugin!

I would actually love to understand this better. It would be my understanding that mkdocs-autolinks works the same way, as a plugin, at build time.

Relative links will work from VS Code, but this plugin aims to solve having to rely on relative links at all. This requires a translation at build time to accompish. Both mkdocs-autolinks and this plugin use very similar hooks into mkdocs to accomplish the end goal.

It would be a great help if you could provide an example where by mkdocs-autolinks can correctly expand non-relative links in VS Code. I would love to match feature for feature, but would have to understand how this worked in the autolinks in order to accomplish that.

[Stanzilla]

Yep, certainly. I just put up a test branch here https://github.com/ManticoreGamesInc/platform-documentation/tree/ezlinks

You can see the difference by switching between the last two commits.

And like I said, ezlinks does get the links right, it is just all the warnings that I wanted to disable.

[orbikm]

Hello @Stanzilla, I believe my latest feature in version 0.1.9 may help you in two ways:

1. Allows you to easily disambiguate links to files with duplicate names which are not in the same directory
2. Warnings for ambiguous links is now off by default. You can re-enable this functionality by using the warn_ambiguities configuration parameter.

Please give it a try, it's available via pip, and let me know if this fits your needs.

[Stanzilla]

Oh awesome, will try tomorrow!

[Stanzilla]

Okay I tested it and it looks like relative links now point to the .md file instead of the pretty url like before and it no longer correctly resolves links in the same directory.

Example:

[Leaderboards](../api/leaderboards.md) players' names, id's and a score, and can be used 
as a way to keep track of players whose data will be needed later for a specific scenario. 
See the [Leaderboard Reference](leaderboards.md) for more information about using them.

The first link goes to http://127.0.0.1:8000/api/leaderboards.md (wrong, should be http://127.0.0.1:8000/api/leaderboards/) and the second goes to http://127.0.0.1:8000/api/leaderboards/ (wrong, should be http://127.0.0.1:8000/tutorials/leaderboards/ since the file this link is in is in the tutorials folder.)

[orbikm]

Ah OK. I will take a look at this asap.

On Mon, Jun 7, 2021, 2:00 AM Benjamin Staneck @.***> wrote:

Okay I tested it and it looks like relative links now point to the .md file instead of the pretty url like before and it no longer correctly resolves links in the same directory.

Example:

Leaderboards players' names, id's and a score, and can be used as a way to keep track of players whose data will be needed later for a specific scenario. See the Leaderboard Reference for more information about using them.

The first link goes to http://127.0.0.1:8000/api/leaderboards.md (wrong, should be http://127.0.0.1:8000/api/leaderboards/) and the second goes to http://127.0.0.1:8000/api/leaderboards/ (wrong, should be http://127.0.0.1:8000/tutorials/leaderboards/ since the file this link is in is in the tutorials folder.)

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/orbikm/mkdocs-ezlinks-plugin/issues/19#issuecomment-855747579, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAZG2YM2NXKIKXGUTTBQT4DTRSDCRANCNFSM46AIFPKQ .

[orbikm]

Ok @Stanzilla, I went ahead & created release 0.1.10. I believe this fixes some (but possibly not all) of the issues you've raised. I went ahead & released that, and yanked the 0.1.9 release, because of this bug.

When I run EzLinks on your site, I'm still receiving a lot of errors that I'm still tracking down, related to relative links in paths.

The thing is, mkdocs by default, fully supports relative path linking. EzLinks is supposed to make such relative pathing unnecessary, but it (at least) should remain functional if it receives a valid relative link.

Locally, I was able to get ~90% of your pages working by doing a find and replace on "(../" --> "", which converts the links from relative to EzLinks.

Now, last note, while processing your site, (which is rather large), the search strategy is becoming a bit slow. This is to be expected, as I have not spent any time optimizing this approach yet. It works very well for smaller sites, but the complexity seems to be adding up on yours. I'm going to explore a more aggressive caching mechanic for preventing repeated lookups in the trie. I'm guessing that will speed things up significantly.

[Stanzilla]

Hah interesting, I'm glad my project is helping you debug this!

[orbikm]

@Stanzilla,

Exciting news, I believe I've resolved the remaining issues with EzLinks on your site. When I build it locally, on the ezlinks branch, I get the following results:

$ python3 -m mkdocs build
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/morbik/dev/platform-documentation/site 
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - icons.md
  - index.fr.md
  - creator_kit/index.fr.md
  - generated/tags.md
  - getting_started/community_content.fr.md
  - getting_started/core_help.fr.md
  - getting_started/editor_intro.fr.md
  - getting_started/installing_core.fr.md
  - getting_started/my_first_multiplayer_game.fr.md
  - getting_started/performance_panel.fr.md
  - getting_started/profiler.fr.md
  - getting_started/publishing.fr.md
  - getting_started/publishing_checklist.fr.md
  - perks/implementing_perks.fr.md
  - perks/joining_perks.fr.md
  - perks/perks_program.fr.md
  - perks/perks_rules.fr.md
  - tutorials/first_game_rpg.fr.md
  - tutorials/global_game_jam.fr.md
  - tutorials/ui_tutorial.md 
INFO    -  Documentation built in 28.11 seconds 

I thought that my link searching strategy was slowing down your site... but it's simply that your site is rather large, and it's actually mkdocs itself that takes up the majority of the processing time. The difference between enabling ezlinks and not is ~1 second, even on a site as large as yours, and I find that perfectly acceptable from a performance standpoint.

I was also able to provide 2 further optimizations:

1. If the link is a direct, functional link to an existing file, it will never search for it, but return the link directly.
2. If a filename is unique across the entire site, we can simply leverage a dictionary for additional efficiency in this case.

Please let me know if release-0.1.11 works for you as I think it will, and let me know if you have any further issues!

[Stanzilla]

I just tested it and it looks like everything is correct now, indeed! I'll need to do some more testing in combinatiuon with the https://github.com/ultrabug/mkdocs-static-i18n plugin but so far everything looks great. Thank you so much for your help!

[orbikm]

Awesome! I am happy to help! One of the explicit goals of me starting this plugin was to be incredibly responsive to issues that arise, as I was not finding that in the other plugins out there.

Your site, and this issue helped me resolve a number of bugs and inefficiencies that I likely would not have found for quite some time by myself, so thank you so much for that as well!

[orbikm]

Oh interesting... I suspect that that plugin could work fine depending on the order it is added. I think if EzLinks were processed first, then the translation plugin ran, it would probably work OK.

If not, let me know, and I'll see if there's a way to make it compatible.

On Sat, Jun 12, 2021, 12:36 PM Benjamin Staneck @.***> wrote:

I just tested it and it looks like everything is correct now, indeed! I'll need to do some more testing in combinatiuon with the https://github.com/ultrabug/mkdocs-static-i18n plugin but so far everything looks great. Thank you so much for your help!

— You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub https://github.com/orbikm/mkdocs-ezlinks-plugin/issues/19#issuecomment-860099067, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAZG2YLAN3IO62LD7GEAN2LTSOZNLANCNFSM46AIFPKQ .

[Stanzilla]

Thanks, will do!