Need section outlining of markdown headers

[rphair]

This is a recently prioritised issue especially because of long CIPs and CPSs submitted in the Consensus category, particularly for evolutions of the Ouroboros protocol that are very detailed and conceptually novel, requiring very detailed specification and rationale.

Knowledge of the CIP format is not enough for readers of such long & detailed documents to navigate without a Table of Contents. These have been automatically generated (at least as an option) on GitHub, and generated previously on the prominent CIP section of the Developer Portal (since then, re-linked to cips.cardano.org), but are missing here.

@aldo555 I believe you have already received this suggestion favourably and I trust this issue will help to track the response. Here are the preliminary discussions that led to the issue (cc @fallen-icarus @nhenin @rrtoledo @bwbush):

• CIP-0159? | Account Address Enhancement CIPs#1061 (comment)
• CIP-0161? | Ouroboros Phalanx - Breaking Grinding Incentives CIPs#1065 (comment)

I would make the one technical recommendation that such elements currently in CIPs should be ignored when parsing, as currently appearing in the merged CIP-0140 (cc @abailly @bwbush), to avoid a duplicated and perhaps inconsistent ToC:

<details>
  <summary><h2>Table of contents</h2></summary>
  ...
</details>

while leaving other <details> elements transparently rendered e.g. in the Acknowledgement section of CIP-1694. If this seems a problem to implement or error-prone, you can avoid that and we'll address the problem at source as outlined in cardano-foundation/CIPs#1065 (comment).

cc (fellow CIP editors): @Ryun1 @Crypto2099 @perturbing

[aldo555]

This should've been addressed in the latest version.

[rphair]

@nhenin @fallen-icarus what do you think of the automatic outlining as appearing e.g. here? Is the appearance & heading depth OK for this & other proposals with a lot of subsections, and will it suit your own proposals?

• https://staging-cip-cardanofoundation.netlify.app/cip/CIP-0140

[rphair]

p.s. @aldo555 there is one thing missing from the parsed headers, though the outline is generated fine: exposure of their anchors for deep linking into the document as we have on GitHub:

• the headers in the document are not given handles so we can copy the anchors;
• when clicking the headings on the right sidebar outline, they're not interpolated into the currently browsed URL.

e.g. to quote the links I posted in #51 (comment) I had to browse the DOM and copy the id= attributes by hand. Site users will expect some widget like the familiar # objects on GitHub, Jekyll, and other Markdown parsers. 🙏

cc @Ryun1 @Crypto2099 @perturbing & @nhenin

[nhenin]

This is great! For our CPD, even though it’s still buggy and I’ll need to fix it, it would be better if the full content could be displayed instead of being constrained in a fixed window.

in addition, The CIP/CPS titles in the left menu get truncated when they’re too long. Could we either allow them to wrap onto two lines or increase the width of the column ? @aldo555 ?

[fallen-icarus]

It looks good to me. However, some of the ToC entries are incorrect/broken:

• Specification -> Non-normative overview of the Peras protocol - there is no such sub-header in the spec.
• Specification -> Protocol parameters - there is no such sub-header in the spec.

These sections are present in the actual CIP-140, but not on the CIP website.

[rphair]

@nhenin #52 (comment): ... CIP/CPS titles in the left menu get truncated when they’re too long ...

This has already been identified, with pending solution, here: #53 (comment)

[rphair]

@fallen-icarus @aldo555 indeed this whole section & its header are missing on the staging site: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0140/README.md#non-normative-overview-of-the-peras-protocol

Could that be a bug triggered by the content (e.g. lots of math markup, images, tables containing images), or could the staging content just be out of sync with GitHub?

[aldo555]

So in the case of CIP-140 it was an edge case. Two issues occured here:

• Table of contents is not in the usual format
• Those two sections happened to have a string inside of them that my Table of contents remover script was mistaking

In the future I'd say it would be best to stick to the Table of contents format of CIP-1

[aldo555]

@rphair The two issues you had should also be fixed.

[rphair]

thanks @aldo555 for supporting the ToC format as arranged in #52 (comment). We've practically confirmed that future CIPs with this level of outline detail, and particularly from this subject area, will be following the same format (as per @nhenin):

• CIP-0161? | Ouroboros Phalanx - Breaking Grinding Incentives CIPs#1065 (comment)

and CIP editors will try to ensure that consistency as well whenever we see an out-of-section Table of Contents in a document. - cc @Ryun1 @Crypto2099 @perturbing