bikeshed-conversion

Bikeshed Conversion

Preserving Anchor IDs

When converting a spec to Bikeshed, anchor IDs used by other specifications must be preserved. Bikeshed auto-generates IDs for <dfn> elements based on their text content, but these auto-generated IDs often differ from the IDs that were in the original spec. Other specs link to these IDs, so changing them silently breaks cross-spec references.

The Problem

Bikeshed generates IDs like dfn-wall-clock from <dfn>wall clock</dfn>, but the original spec may have used a different ID or no explicit ID (relying on the HTML spec's own ID generation). When other W3C specs reference anchors like #dfn-wall-clock, #dom-performance, or #dfn-coarsen-time, those links break if the IDs change.

The Fix

Always add explicit id attributes to <dfn> elements to preserve the anchors other specs depend on:

<!-- BAD: Bikeshed auto-generates an ID that may differ from the original -->
<dfn data-export>wall clock</dfn>

<!-- GOOD: Explicit ID preserves the anchor -->
<dfn data-export id=dfn-wall-clock>wall clock</dfn>

Common ID Patterns to Preserve

Based on w3c/hr-time#173, these are typical ID patterns that get lost:

| Type | Pattern | Example | |------|---------|---------| | Concept definitions | dfn-{name} | id=dfn-wall-clock, id=dfn-monotonic-clock, id=dfn-duration | | Algorithm definitions | dfn-{algorithm-name} | id=dfn-coarsen-time, id=dfn-duration-from | | IDL typedefs | dom-{typename} | id=dom-domhighrestimestamp, id=dom-epochtimestamp | | IDL interfaces | dom-{interface} | id=dom-performance | | IDL blocks | idl-def-{name} | id=idl-def-domhighrestimestamp | | Compound concepts | dfn-{hyphenated} | id=dfn-current-high-resolution-time, id=dfn-relative-high-resolution-coarse-time |

Checklist

When converting a spec to Bikeshed:

1. Inventory all <dfn> elements in the original spec and note their IDs
2. Check for cross-spec references — search other W3C specs that link to this spec's anchors (use xref or grep the spec's URL in other repos)
3. Add explicit id attributes to every <dfn> that had an ID in the original, matching the original ID exactly
4. Verify after conversion — build the Bikeshed output and confirm all anchors from the original spec still resolve
5. Check data-dfn-for scoping — Bikeshed uses data-dfn-for to scope definitions; make sure scoped dfns also retain their original IDs (e.g., id="wall-clock-unsafe-current-time" for <dfn data-dfn-for="wall clock">unsafe current time</dfn>)