unisonweb / unison

A friendly programming language from the future
https://unison-lang.org
Other
5.78k stars 270 forks source link

Docs feature: link across Doc terms to Anchor tags #2785

Open rlmark opened 2 years ago

rlmark commented 2 years ago

Currently you can link to an anchor tag within a Doc term with the anchor tag link syntax, but we've encountered a few cases where it would be useful to link to an anchor tag within a different Doc term. This feature might be useful in cases where the targeted doc section is embedded within a longer doc, but linking directly to a transcluded fragment strips the user of necessary context.

Caveats: We're aware that the Doc type is a unique type and we'd like to avoid creating a Doc3 migration for users.

Discussed in collaboration with @hojberg

pchiusano commented 2 years ago

As a workaround for now, can use regular (site relative or relative) HTML links -

/articles/distributed-datasets/core-idea#blah
foo/blah#abc that will be relative to the current document
../blah#abc

Downside of this workaround is if you change the names of the docs on the docs site, then links can break. There's not a great way of doing local previews of those links outside of building the docs site.