Consider using something like Bikeshed?

THIS IS HEAVILY OPINIONATED

from my background of reading and referencing specs like https://datatracker.ietf.org/doc/html/rfc2616 and https://html.spec.whatwg.org/multipage/workers.html and https://tc39.es/ecma262/multipage/global-object.html#sec-globalthis and https://wicg.github.io/webusb/ and https://drafts.csswg.org/selectors/#specificity-rules ... etc i have been conditioned to think of specifications as interconnected documents with lots of helpful links and terms and more in-page links and even more cross-spec links. I've found it a bit annoying having to open like 3 tabs on different pages to get a handle on how devcontainer.json interacts and combines with devcontainer-feature.json. 😅 and even then its a bunch of Ctrl+F-ing around the document to figure it out. i think it would be helpful if there was in-page links to other in-page terms.

in fact, i can see that there was at least some kind of effort to label terms with `**term** is a term` like text throughout the document:

```md
A **development container** is a container in which a user can develop an application.
```

i think that it may be worth at least considering (and maybe even exploring) the idea of using https://speced.github.io/bikeshed/ or even just improving the markdown to make it easier to read the specification.

for example...

```
A development container is a container in which a user can develop an application.
```

this AUTOMATICALLY creates a `#development-container` id-ed `` and then later you can:

```
And then inside your [=development container=] you can use a [=dev container feature=] to ...
```
which autolinks to the corresponding `` (with plural normalization and some other magic) it when run through `bikeshed spec`

bikeshed seems to make spec writing easier (since that's its entire purpose lol), but of course this could be done in plain markdown manually too.

on the other hand, i know there's the docker-related specs which are much different and look more like multipage booklets https://docs.docker.com/compose/compose-file/ which i don't have as much experience reading.

ps i think this would solve https://github.com/devcontainers/devcontainers.github.io/issues/10 https://speced.github.io/bikeshed/#id-gen and related autolinking confusion