[Bundle] Adds anchor tags for headings and bullets #612
Conversation
Signed-off-by: Rob Dolin <robdolin@microsoft.com>
|
|
||
| ## Container Format | ||
| ## <a name="containerFormat" />Container Format |
There was a problem hiding this comment.
I don't think we need to add anchors to the headers, since both GitHub and Pandoc agree on the auto-generated container-format anchor (and likewise for other headers):
$ curl -Ls https://github.com/opencontainers/runtime-spec/releases/download/v1.0.0-rc2/oci-runtime-spec-1.0.0-rc2.html | grep 'Container Format'
<h2 id="container-format">Container Format</h2>
There was a problem hiding this comment.
The proposed PR separates the anchor tag from the header text.
This follows the recommendation from the Open API Initiative (formerly Swagger) which.
I'm hesitant to use the auto-generated anchor links from GitHub since we might change the header text (ex: adding section numbers like "4.1 Container Format" and that would change the auto-generated anchor links.
There was a problem hiding this comment.
I don't think link stability is a major issue, because folks referencing the spec should be pinning their reference to a particular version (like this). If we change the header later on, that link (pinned to v1.0.0-rc2) will still work. Even if you do attempt to provide a stable anchor between spec releases, sometimes the section will go away, or get moved to a different file, or be split into two sections, or whatever. In all of those cases the old unpinned link will no longer work regardless of any attempt at freezing the anchor. Do we really expect lots of churn in header text but minimal churn in the section or file structure?
That said, if folks do expect significant churn in header text and are happy to nip that in the bud by adding these headers to all of our existing sections, more power to 'em ;).
| @@ -10,11 +10,11 @@ The definition of a bundle is only concerned with how a container, and its confi | |||
| A Standard Container bundle contains all the information needed to load and run a container. | |||
| This MUST include the following artifacts: | |||
|
|
|||
| 1. `config.json`: contains configuration data. | |||
| 1. <a name="containerFormat01" />`config.json`: contains configuration data. | |||
There was a problem hiding this comment.
These anchors look good to me, although I think we should stick to the lowercase, hyphenated form that GitHub and Pandoc are using already for headers. In that case, the name here would be container-format-01.
There was a problem hiding this comment.
Does it make sense to actually not be hyphenated so we can distinguish them from github/pandoc anchors?
There was a problem hiding this comment.
Does it make sense to actually not be hyphenated so we can distinguish them from github/pandoc anchors?
If we're going to anchor everything independently of GitHub / Pandoc, I'd rather just use a language that adds anchors for us (#615). If we stick with Markdown, I'd rather use the GitHub / Pandoc anchors where they're generated, and only add occasional manual anchors where needed.
If you're worried about conflicts between manual and auto-generated anchors, I think having a consistent fragment style is more important. Just chose anchor names that are unlikely to be autogenerated from slugs.
|
See related PR #614 |
|
@opencontainers/runtime-spec-maintainers Per discussion on today's OCI Dev ConCall, please merge this PR. Thanks. |
|
LGTM |
|
LGTM |
Signed-off-by: Rob Dolin robdolin@microsoft.com