Consider using something like Bikeshed?

[jcbhmr]

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:

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 <dfn>development container</dfn> is a container in which a user can develop an application.

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

And then inside your [=development container=] you can use a [=dev container feature=] to ...

which autolinks to the corresponding <dfn> (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 devcontainers/devcontainers.github.io#10 https://speced.github.io/bikeshed/#id-gen and related autolinking confusion

[bamurtaugh]

Thanks for opening @jcbhmr! I think this is a really interesting idea. I'll try to allot some time in the next few weeks to play around with Bikeshed.

Either way, your points about consistency make a lot of sense, and it'd be valuable to set aside time to do a formatting pass (i.e. naming, capitalization, bolding).

For other folks who may be reviewing this - we definitely welcome PRs if you'd like to take a formatting pass or identify specific areas of inconsistency. 😄

[bamurtaugh]

Hi @jcbhmr, thanks again for your feedback on this issue (and continued engagement with the spec overall!).

We recently discovered https://devcontainers.org/ (via devcontainers/devcontainers.github.io#288), and we really like the UI. From an initial review of Bikeshed, it appears devcontainers.org uses Bikeshed.

I was wondering if you might own or contribute to https://devcontainers.org/? If so, we'd love to collaborate on theme changes to containers.dev based on what's discussed in this issue and present on that site. The dynamic elements are especially of interest to us (including dynamically pulling spec data from https://github.com/devcontainers/spec to keep both data sources in sync, and the keyword/title automatic linking you mention).

Looking forward to hearing what you think!

[bamurtaugh]

Looking forward to next steps:

• Continue discussion above (learn more about Bikeshed, ownership of devcontainers.org)
• Regardless of Bikeshed, do an edit pass of containers.dev and this spec repo (ensure consistency in things like caps, bolding, formatting)

[jcbhmr]

Regarding https://devcontainers.org/:

• Yes, I do currently have the domain
• The source code to said website is at https://github.com/devcontainers2/devcontainers2.github.io
• Yes, I do want to merge my changes
• I am not sure how to go about approaching such a monumental change
• I acquired the domain foreseeing 👆 that issue and thinking that you (@devcontainers) may want to have parallel websites like Node.js does: https://nodejs.org (old) and https://nodejs.dev (new,temp) in order to incrementally evaluate and progress through a change of such magnitude
• It's sorta like https://github.com/codspace or https://github.com/codspaces
• Yes, there's currently a spec repo https://github.com/devcontainers2/spec which deploys to https://devcontainers.org/spec/ that uses Bikeshed
• It originally had a copy-paste verbatim of the current spec text from https://containers.dev/implementors/reference/ (and child pages) just run through bikeshed (i.e. lacking fancy links)
• Now it has an incomplete demo of some of the possible ways to take advantage of Bikeshed's fancy autolinking system as an experiment

---

With that said, here's some more information about Bikeshed since you seem curious 😊:

• Bikeshed is what the @w3c and @whatwg specifications use. And @wintercg. And @WebAudio. And most other web-related and web-adjacent specifications.
• Bikeshed is installed via pip install bikeshed
• You run bikeshed on a .bs file via bikeshed spec [file] or bikeshed watch [file]
• You write Markdown+HTML -ish markup
• WebIDL is a first-class TypeScript-like language and makes it easy to define things then reference them with Bikeshed like this: https://github.com/devcontainers2/spec/blob/f45c89f0475f2876428697a4c81cc8bf4df97355/index.bs#L127-L196
• Bikeshed supports custom markup like [=term=] which auto-links to terms defined like <dfn>term</dfn> such as https://github.com/devcontainers2/spec/blob/f45c89f0475f2876428697a4c81cc8bf4df97355/index.bs#L93-L117
• Bikeshed does support splitting a single document across multiple files https://speced.github.io/bikeshed/#including
• Bikeshed was originally a Tab Atkins project but is now under https://www.w3.org/community/speced-cg/

I want to stress: You don't have to use Bikeshed. It's just the thing that I see plastered everywhere across various https://wicg.io/ https://spec.whatwg.org/ and https://www.w3.org/TR/. Some other specifications use plain Markdown! You can use whatever makes authoring the easiest.

In my opinion (which shouldn't be weighted much): since this specification involves a lot of linking to attributes, properties, and type-like things, that's a good case where {{forwardPorts}} is a lot easier than [`forwardPorts`](#devcontainer-json-forwardPorts) especially when that is repeated 100+ times throughout the document.

Here's some screenshots of Bikeshed experiment idea

[bamurtaugh]

Hi @jcbhmr, thank you so much for sharing this info!

Yes, there's currently a spec repo https://github.com/devcontainers2/spec which deploys to https://devcontainers.org/spec/ that uses Bikeshed
It originally had a copy-paste verbatim of the current spec text from https://containers.dev/implementors/reference/ (and child pages) just run through bikeshed (i.e. lacking fancy links)

This is good to know. To get the most out of Bikeshed, did you find it necessary to make a lot of changes to the base content in the spec repo? From what I can tell in https://github.com/devcontainers2/spec/tree/main, it looks like it's a subset of the spec's pages with an addition like https://github.com/devcontainers2/spec/blob/main/index.bs (so an initial demo like you mentioned). I'm mainly wondering if using Bikeshed required a lot of reworking of the spec (so it was easier to focus on just a couple pages), or if it didn't require much change but was just easier to experiment with a smaller subset of pages?

I acquired the domain foreseeing 👆 that issue and thinking that you (https://github.com/devcontainers) may want to have parallel websites like Node.js does: https://nodejs.org/ (old) and https://nodejs.dev/ (new,temp) in order to incrementally evaluate and progress through a change of such magnitude

Thank you for sharing this context! So far, we've been alright running the site locally and testing how changes look, but it's good to have this idea in mind, so we appreciate you sharing it. Would you be open to redirecting devcontainers.org back to containers.dev? Our primary concern is more users finding this site and thinking it's an alternate to containers.dev, and/or owned by another team at Microsoft (based on the copyright and author info throughout).