// Guidelines for converting W3C specs to Bikeshed format. Covers anchor ID preservation, dfn handling, and common pitfalls. Read this before any Bikeshed conversion or migration work.
Guidelines for converting W3C specs to Bikeshed format. Covers anchor ID preservation, dfn handling, and common pitfalls. Read this before any Bikeshed conversion or migration work.
Process and publish WebPerfWG meeting minutes from Google Docs zip exports. Read this before handling any WebPerfWG meeting minute zip files.
| name | bikeshed-conversion |
| description | Guidelines for converting W3C specs to Bikeshed format. Covers anchor ID preservation, dfn handling, and common pitfalls. Read this before any Bikeshed conversion or migration work. |
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.
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.
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>
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 |
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.
When converting a spec to Bikeshed:
<dfn> elements in the original spec and note their IDsid attributes to every <dfn> that had an ID in the original, matching the original ID exactlydata-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>)