Transform .md links to .html for sphinx docs

[talonchandler]

@amitabhverma I tested the docs locally and found this conversion to work well. Please check and use this if it solves your problem.

[amitabhverma]

@amitabhverma I tested the docs locally and found this conversion to work well. Please check and use this if it solves your problem.

Did this solution work for guide.html which is generated using the include method, .md file in the .rst file ?

waveorder/docs/sphinx_source/guide.rst

Lines 4 to 5 in 0c9a2a7

	.. include:: ./guide/README.md
	:parser: myst_parser.sphinx_

It does work for .md files converted via the myst_parser directly (napari-plugin-guide.html) but does not seem to work for cases where its being included in a .rst.
I am using the README.md in /guide as the landing page as it is used on github, if an Index view of the landing page is acceptable then this method can be used. I've shared the previews below..

vs

[talonchandler]

Did this solution work for guide.html which is generated using the include method, .md file in the .rst file ?

Have you tried it locally? In my tests I was able to see the landing page and click the links from the guide.html. The links are broken on this link https://waveorder.readthedocs.io/en/latest/guide.html, but I don't have control (or understanding) of which branch is being displayed there.

I am using the README.md in /guide as the landing page as it is used on github, if an Index view of the landing page is acceptable then this method can be used. I've shared the previews below..

I prefer the landing page. The section navigation on the left seems to provide a top level view and the landing page gives a bit more guidance.

Thanks for your help here @amitabhverma.

[amitabhverma]

Did this solution work for guide.html which is generated using the include method, .md file in the .rst file ?

Have you tried it locally? In my tests I was able to see the landing page and click the links from the guide.html. The links are broken on this link https://waveorder.readthedocs.io/en/latest/guide.html, but I don't have control (or understanding) of which branch is being displayed there.

@talonchandler
I do have the latest changes committed to my repo which generates the docs on the site but I don't see the .md links being converted correctly in guide.html, they do work correctly in napari-plugin-guide.html. Can you please confirm once again your local copy of guide.html is rendering correctly with in-page md links ?

If this still does not work, there is another work around using post-build job that can be setup. Once you confirm the above I'll look into that. I agree the landing page layout looks a lot better so we will work towards that.

[amitabhverma]

Update: The online version of guide.html is working but uses the post-build job. Please still confirm how your local copy of guide.html builds since that would be a cleaner way. Thanks.

[talonchandler]

Apologies @amitabhverma, I accidentally misled myself and I think this PR was a false start.

The problem is illustrated in the attached screen recording. The first tab shows the broken link on the webpage (which I'm hoping we can fix), the second tab shows my local build created with sphinx-build -b html . _build/html && open _build/html/guide/README.html, but this only seems to be working from /guide/README.html...the final case from guide.html still seems to be broken. This explains our discrepant outcomes on this branch...I was checking a different case.

I'll let you solve this however you think is best. Pardon me for the false start.

Screen.Recording.2025-08-18.at.3.05.38.PM.mov

[talonchandler]

Closing in favor of #461.