Reference HTML IDs in rendered HTML to facilitate referencing|bookmarks

[DazWilkin]

Describe the change you'd like to see

The API documentation uses HTML IDs, e.g. RouteStatusFields:

<h3 id="serving.knative.dev/v1.RouteStatusFields">RouteStatusFields</h3>

But the HTML ID is not surfaced in the rendered HTML making it cumbersome to grab the ID (from the source) to use it (as I did above).

Curiously, the Duck Types content does this e.g. Addressable so it may be just config|oversight:

<h3 id="addressable">Addressable<a class="headerlink" href="#addressable" title="Permanent link">¶</a></h3>

Additional context Add any other context or screenshots about the feature request here.

[snneji]

The API documentation is auto-generated whereas the duck types page was created manually. This is why the pages are slightly different. This might be an issue/limitation of the auto-generation script.

@csantanapr do you have any insight into whether this can be fixed or improved?

[github-actions[bot]]

This issue is stale because it has been open for 90 days with no activity. It will automatically close after 30 more days of inactivity. Reopen the issue with /reopen. Mark the issue as fresh by adding the comment /remove-lifecycle stale.

[snneji]

/lifecycle frozen

[abrennan89]

@psschwei @evankanderson might you be able to help with this one? Otherwise I think we would need to close it, since it's not something myself or Samia can do much about, as we didn't create / don't maintain these scripts.

[evankanderson]

I think this is "needs eng implementation" -- I'm not sure if there's a "site improvements" bucket for these to go in.

[abrennan89]

Added labels for these categories for now

[psschwei]

@abrennan89 Based on a quick look, I don't think the problem is the script. Instead, I think the problem is that the serving/eventing API docs are HTML-encoded. For example, here's a small sample from the serving doc:

<h2 id="autoscaling.internal.knative.dev/v1alpha1">autoscaling.internal.knative.dev/v1alpha1</h2>
<div>
<p>Package v1alpha1 contains the Autoscaling v1alpha1 API types.</p>
</div>
Resource Types:
<ul><li>
<a href="#autoscaling.internal.knative.dev/v1alpha1.PodAutoscaler">PodAutoscaler</a>
</li></ul>

source

I think all we need to do is remove the HTML tags and convert to markdown formatting, and that should solve the issue.

Links: https://github.com/knative/serving/blob/main/docs/serving-api.md?plain=1 https://github.com/knative/eventing/blob/main/docs/eventing-api.md?plain=1

[psschwei]

Alternatively, we could just add the links to the existing documents...

[knative-prow-robot]

This issue or pull request is stale because it has been open for 90 days with no activity.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close

/lifecycle stale

[github-actions[bot]]

This issue is stale because it has been open for 90 days with no activity. It will automatically close after 30 more days of inactivity. Reopen the issue with /reopen. Mark the issue as fresh by adding the comment /remove-lifecycle stale.