Inconsistent link behavior

[Kenji776]

Me again :P I am noticing an issue where the link generation from one document to another seems to be a little inconsistent or inaccurate. I've noticed two specific kinds of failures.

Issue 1

An @See tag is resolving the link to contain the folder name when both files are in the same folder. EX the source code for the file StripeAgreement.cls contains this tag. @See StripeRESTService

Which when processed becomes a link <a href="/Misc/StripeRESTService.md">StripeRESTService</a>

Which is incorrect as both StripeAgreement and StripeRestService are in the same folder (additionally they are being placed in a 'Misc' folder when they are both in the '@Group Stripe_Integration', not sure why that is.

Issue 2

I'm unsure if this is intentional but when links are generated they prepended with a '/' which at least on my windows 10 machine with Chrome makes it want to resolve to absolute file path. EX @See StripeRestServiceTest

Becomes <a href="/Misc/StripeRESTServiceTest.md">StripeRESTServiceTest</a>

Which my browser then interprets as file:///C:/Misc/StripeRESTServiceTest.md

When the actual path would be file:///C:/Users/Kenji/Documents/SFDX%20Projects/ClientName/ApexDoc/docs/markdown/Misc/StripeRESTServiceTest.md

Maybe adding a flag to the command to either include or exclude that beginning slash? I know system file paths get weird and different OS handle them differently and probably even different browsers so I'm not sure if there is a one size fits all fix there but just thought you should know.

[cesarParra]

Hi @Kenji776

I'm actually having trouble replicating both of these issues. Would you be able to share some of the apex docs of the files that are giving you issues? Doesn't need to be the entire thing, but maybe just the structure of the class level docs.

For the linking, how are you getting the HTML <a> tags? Are you running the .md through a tool to get HTML that you could share with me or are you serving them through a static site generator? I'm trying to see if I can replicate the environment since at least Github pages seems to be linking things correctly for me.

[Kenji776]

Hey @cesarParra

Ah yeah, replicating bugs is always a pain. I can send you a copy of my project if you like and you can then see exactly what's happening. Is there a place I can send you a zip file?

For the HTML a tags, I have a browser extension just called 'markdown viewer'. Once allowed to view local files you can just open up markdown files and it'll process them for you. Those links are just from inspecting the source of what it generates, but even looking at the markdown source it's including the directory when it shouldn't. This is what the markdown looks like in the raw source file.

**See** [StripeRESTService](/Misc/StripeRESTService.md)

Which markdown viewer then converts into

<a href="/Misc/StripeRESTServiceTest.md">StripeRESTServiceTest</a>

When the'/Misc'/ really shouldn't be there.

As for generation actual HTML files, I have another package I use just called markdown-to-html which does most of the conversion. I then have to do some post processing as the HTML it generates isn't quite perfect.

Just to give a little overview understanding of what I've got going it's like this. I have a NodeJS script that copies all the desired apex class files from your actual working directory to a local temp directory. It then uses your generator to create markdown files from all those classes. After that I convert the markdown to html and do my post processing to fix it up (as best I can, still working on that). I then zip both folders and save that as a new file for delivery to the customer. So all I have to do is re-run my script and the newest code documentation is pulled and generated for everything I've worked on. It's pretty nifty, or will be when I can get these last few bugs worked out.

[cesarParra]

@Kenji776

Thanks for that background, and that sounds pretty sweet!

You can send files to my email: cesar.parra@gmail.com.

[cesarParra]

@Kenji776, here's a quick update on this:

The Misc issue unfortunately I haven't been able to replicate, but I was able to see the issue with the markdown viewer extension, which seems to be an issue in general when viewing the files locally through file:// paths.

The reasoning behind the leading / is because is because that indicates to both Github Pages and Docsify that it is a root relative link, so that allows for easy linking between classes that link to different groups without having to figure out dynamically if the path should go up a directory or not.

I've prototyped something that allows the linking to be more dynamic and figure out where to link to. For this I've added a new generator that simply creates the markdown files called plain-markdown, which should also fit your use case a bit better since it will also stop printing the Jekyll front matter at the top of the file (the table at the top that says: Layout | default).

I've released this as a beta if you want to test it out. To install you can run npm install @cparra/apexdocs@2.5.0-beta.0 and to run you can specify the -g argument to be plain-markdown (eg. apexdocs-generate -s src -t docs -g plain-markdown --scope public global .Things should also work without the -g override but it will just output that table at the top which I'm guessing is not desired.

Let me know if things look good and I can release that version to the GA channel.

[Kenji776]

Cesar,

Thanks again for the quick update! It seems to be working great now. I still have a couple issues to work out with the HTML versions but that's my problem. Everything on your side is working slick.Even the folder grouping seems to be working now which is great. You're awesome!

On Fri, Jun 3, 2022 at 7:54 AM Cesar Parra @.***> wrote:

@Kenji776 https://github.com/Kenji776, here's a quick update on this:

The Misc issue unfortunately I haven't been able to replicate, but I was able to see the issue with the markdown viewer extension, which seems to be an issue in general when viewing the files locally through file:// paths.

The reasoning behind the leading / is because is because that indicates to both Github Pages and Docsify that it is a root relative link https://maximorlov.com/deploying-to-github-pages-dont-forget-to-fix-your-links/, so that allows for easy linking between classes that link to different groups without having to figure out dynamically if the path should go up a directory or not.

I've prototyped something that allows the linking to be more dynamic and figure out where to link to. For this I've added a new generator that simply creates the markdown files called plain-markdown, which should also fit your use case a bit better since it will also stop printing the Jekyll front matter at the top of the file (the table at the top that says: Layout | default).

I've released this as a beta if you want to test it out. To install you can run npm install @@.*** and to run you can specify the -g argument to be plain-markdown (eg. apexdocs-generate -s src -t docs -g plain-markdown --scope public global`

Let me know if things look good and I can release that version to the GA channel.

— Reply to this email directly, view it on GitHub https://github.com/cesarParra/apexdocs/issues/55#issuecomment-1145934545, or unsubscribe https://github.com/notifications/unsubscribe-auth/AASPED5Y5VKJLCF4RK4T4TTVNH577ANCNFSM5XV6UHOQ . You are receiving this because you were mentioned.Message ID: @.***>

[cesarParra]

That's great to hear! I've gone ahead and released a GA version (2.5.0) with these changes as well.