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

IDL Attribute Definitions

When converting <dfn> elements inside a <dl> that describes IDL interface attributes, add the attribute keyword to each <dfn> so Bikeshed knows they define IDL attributes (not plain terms). The parent <dl> should have dfn-for set to the interface name.

<!-- BAD: Bikeshed treats these as plain concept dfns -->
<dl dfn-for="PerformanceEntry" data-export>
  <dt><dfn>duration</dfn></dt>
  <dd>...</dd>
</dl>

<!-- GOOD: Bikeshed knows these are IDL attributes -->
<dl dfn-for="PerformanceEntry" data-export>
  <dt><dfn attribute>duration</dfn></dt>
  <dd>...</dd>
</dl>

Without the attribute keyword, Bikeshed won't correctly associate the dfn with the IDL attribute, and cross-references like {{PerformanceEntry/duration}} may fail to resolve.

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>)