search

SuffolkLITLab / docassemble-AssemblyLine-documentation

Legal form development and deployment process
https://assemblyline.suffolklitlab.org
8 stars 8 forks source link

Audit and replace internal cross references with more flexible links #414

Open nonprofittechy opened 2 months ago

nonprofittechy commented 2 months ago

We have some absolute links right now, and when upgrading to Docusaurus v3 we had to remove broken file path links. We should audit links and make sure that they can withstand future reorganization of content.

https://docusaurus.io/docs/markdown-features/links

plocket commented 2 months ago

can withstand future reorganization of content

Would love to talk live about this more and understand means with a bit more depth. Maybe we could take a few minutes during a meeting.

nonprofittechy commented 2 months ago

Hmm, if the issue isn't clear perhaps I have something wrong or I'm misunderstanding this feature. I just know having hardcoded URLs like /docs/something means if we change the slug for a page, that link will break. if it's possible to avoid that, it would be nice. The Docusaurus v1 and v2 were more flexible about this kind of reference.

Working on #415 might make this less important. Part of the problem is when you're editing a file and want to add a cross reference, it's a pain to figure out how to properly format that link because the file names and locations don't match the slug.

plocket commented 2 months ago

We decided we're going to re-organize the folder structure and slugs to match up with each other and maybe automate creating the left side-bar nav. I'm still not exactly sure which link format we settled on.

I'm still a fan of the relative links that use the file extensions. There was some discussion about how error messages may affect the decision. If the [error messages] only mention the slugs, it would be frustrating to need to figure out the file path from the slug information. I'm not exactly sure what the specifics of the error description was, but I decided to try it out and this is what I got:

[WARNING] Docs markdown link couldn't be resolved: (wrong.mdx) in "/Users/Comfadorable/Desktop/General/coding/suffolk-lit-lab-assembly-line/docassemble-AssemblyLine-documentation/docs/alkiln/intro.mdx" for version current

Maybe this is a different situation than the one we were discussing, though.

plocket commented 2 months ago

Another thought that occurred to me: There are some folders or files that we might want to skip, like folders that hold components, so maybe we want to coordinate about a prefix for folders or files we want to ignore? _ignore would be pretty clear. _ignore_folder_name or _ignore_file_name.mdx.