developer-portal icon indicating copy to clipboard operation
developer-portal copied to clipboard

CIP relative link problems: footer + nested README files

Open rphair opened this issue 3 months ago • 5 comments

The relative links that work inline in the text of all CIPs, e.g. in the two CIP-0072 *.json schemas beginning here (both opening as JSON files hosted on the Dev Portal in the browser), aren't evaluated correctly when the relative links appear in the document footer as follows in this recently merged CIP (in https://github.com/cardano-foundation/CIPs/blob/master/CIP-0114/README.md:)

The format of the registry is defined by the json schema: [CIP Tag Registry Schema].
New entries MUST be added to the [CIP Tag Registry] in a PR for a CIP that first defines a new CBOR Tag.
...
[CIP Tag Registry Schema]: ./registry.schema.json
[CIP Tag Registry]: ./registry.json

You can see on the currently built Dev Portal CIP page that these links are broken: https://developers.cardano.org/docs/governance/cardano-improvement-proposals/CIP-0114 ... and we also get the usual build warning about not being able to evaluate the relative links:

[WARNING] Docusaurus found broken links!
...
- On source page path = /docs/governance/cardano-improvement-proposals/CIP-0114:
   -> linking to ./registry.schema.json (resolved as: /docs/governance/cardano-improvement-proposals/registry.schema.json)
   -> linking to ./registry.json (resolved as: /docs/governance/cardano-improvement-proposals/registry.json)

I don't think CIP editors can require authors to avoid the "footnote" syntax for relative links: either by turning them into absolute links or repeating the link reference wherever it appears inline. Therefore the only remaining solution is to also interpret the relative links correctly — as they are when appearing inline — when they appear in the footnote.

So far CIP-0114 is the only CIP or CPS which is using relative URLs in the footer, so it's both a good test case & our only instance of the problem:

$ grep ']: ./' */README.md
CIP-0114/README.md:[CIP Tag Registry Schema]: ./registry.schema.json
CIP-0114/README.md:[CIP Tag Registry]: ./registry.json
$

cc @stevenj @Ryun1 @Crypto2099

rphair avatar Mar 20 '24 16:03 rphair