How Does link checker parse links?

[lwasser]

Hi there,
i'm adding the jupyter book link checker to our build. I ran into this previously where it identifies broken links internally that should be ok and do work locally.

Here is an example. i do use an include here and added a scope.md file update that should make the link to #package-categories resolve correctly but it's still finding errors. Is the link checker looking at pyopensci.org/contributing-guide/link-here
Or is it resolving to the localhost where it's built?

or am i creating links incorrectly?

[package fit within identified categories for the pyOpenSci ecosystem](../open-source-software-peer-review/aims-and-scope.html#package-categories/)

CI build here:
https://github.com/pyOpenSci/contributing-guide/actions/runs/3101475747/jobs/5022875383#step:6:46

NOTE: i provided an example with an include file however i'm seeing the same behavior for other internal links.
many thanks for any guidance. id love to be able to check links before publishing. The alternative will be something like html proofer i suppose.

[chrisjsewell]

Heya, yes its not intended that you specifically link to .html files, because (a) you are assuming the only output is HTML, and (b) you are assuming that the structure of the output files as the same as the input.

MyST provides functionality to link between files in a more "agnostic" way, either (recommended) you explicitly create a target to a heading.

(mytarget)=
# My heading

Then you can refer to this with {ref}`mytarget`

or you can use implicit tagets with: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors

[lwasser]

Ahhhh ok i think i understand. So essentially I need to look more closely into MyST syntax as it relates to page targets and adjust how i am creating links. I will play with this and report back just in case others run into this as well :). Thank you so much @chrisjsewell !!!

[lwasser]

@chrisjsewell if you have a moment to clarify or direct me to examples of this ...

Here is a link using vanilla markdown:
this doesn't to work: EDIT i think it was working it isn't
[email template](../appendices/templates.md#review-request-template)

This throws off the link checker:
[email template](../appendices/templates#review-request-template)

Note that i'm referring to a bookmark on this template page from another page.

In this case would targets still work? It seems difficult if i had to recreate targets that exist already as they are headings in the book (if this makes sense). I just want to do this efficiently and understand what syntax is preferred. Thank you so much! You've been super helpful!!

[lwasser]

i edited the above -- using .md doesn't work. i'm just sa bit confused about creating targets when they already exist on the pages via the headings. so for instance this target exists

appendices/templates.html#editor-s-template so i just need to link to it ... should i use .html#target-name ?