CIP relative link problems: footer + nested README files

[rphair]

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]

@katomm @fill-the-fill cross-referencing #1121.

[rphair]

@fill-the-fill the other place relative links don't parse right is for inline links to CIP & CPS README.md files; which across a number of contexts (including GitHub itself) can be referenced by the containing directory. See this table in CIP-0088 (cc @Crypto2099): https://github.com/cardano-foundation/CIPs/blob/master/CIP-0088/README.md#6-cip-specific-information

... with the links in the last column (Rationale) of the Dev Portal page all broken; pointing to nonexistent URLs on GitHub (but not reported as warnings during the build process, since the files aren't local): https://developers.cardano.org/docs/governance/cardano-improvement-proposals/CIP-0088#6-cip-specific-information

As with the case above, we are trying to get support for typical linking syntax in the derived web sites rather than forcing CIP editors (cc @Ryun1) & authors to confine themselves to a narrower link syntax than they see supported on GitHub.

I agree with @katomm's #1121 (comment) that a "fragile" CIP build script on the Dev Portal (or any derived web site) should not restrict how CIPs are written when their markup is otherwise valid (defined, I think, as valid on GitHub).

[fill-the-fill]

I unfortunately still didn't have time to look into this issue since very busy with other stuff but I'm keeping my eye on it

[Shivam-1M]

Hello there @rphair @fill-the-fill!
I am new to this repo and I have managed to work on this issue.

Problem: The referenced style links in CIPs are causing problem (e.g., CIP-0114).

Proposed solution:

1. When downloading CIP contents, first check the "referenced style links" (mentioned at the bottom of the page)

For example, [CIP Tag Registry Schema]

2. Then replace the "referenced items" in the content with "referenced item" and corresponding "relative file link" to make it an inline link.

For example, [CIP Tag Registry Schema](./registry.schema.json)

3. The present code will do the rest of the work of downloading the files and updating the content.

For example, [CIP Tag Registry Schema](../../../static/img/cip/./CIP-0114/./registry.schema.json)

I have the solution but I am not sure how I can push my branch in here as it throws permission error.

[katomm]

Welcome, you can not push your branch directly you need to create a pull request from your fork.

[rphair]

Potentially fixed by #1262.