W3C Credentials Community Group

Increasing trust on the Web, one spec at a time.

Next Meeting

Time: 12pm Boston
    VoIP: sip:ccg@
    US phone: +1.540.274.1034 x6306
    EU phone: + x6306
Chat: Web, IRC
Duration:60 minutes

Connecting to the Calls
Mailing List
Meeting Minutes
W3C Community Page

View the Project on GitHub w3c-ccg/w3c-ccg.github.io

Creating spectext with markdown and bikeshed


Bikeshed is a tool that generates specs (spectext html files) from simpler source files, such as markdown.


The BTCR DID method spec uses bikeshed for generating spectext. We edit the BTCR index.bs file, and then run bikeshed to generate the index.html file. The rendered output is shown here.

When to use

Spec authors/editors may prefer to use markdown and bikeshed for the following types of CCG work items:

In later phases of Community Specifications, especially complex ones like the DID spec, participants may prefer direct diffs on the html for precision.

Known Issues

While easier to work with than spectext files, this still involves bikeshed tool install/run instructions, and therefore is not non-dev friendly.

As a workaround, we could stand up a generation tool to allow people to run bikeshed in a browser.

Installing Bikeshed

git clone https://github.com/tabatkins/bikeshed.git
cd <location>/bikeshed
pip install --editable <location>/bikeshed

other possible prereqs:

brew install python@2
‚Ä©pip install pygments lxml --upgrade

Starting a spec

Use the bikeshed quick start.

An example of the BTCR metadata section is here:

<pre class='metadata'>
Title: BTCR DID Method
Shortname: didm-btcr
Level: 1
Status: w3c/CG-DRAFT
Group: Credentials Community Group
URL: https://w3c-ccg.github.io/didm-btcr/

Editor: Christopher Allen, http://www.lifewithalacrity.com/
Editor: Kim Hamilton Duffy, https://github.com/kimdhamilton
Editor: Ryan Grant
Editor: Dan Pape, https://github.com/danpape

Abstract: The Bitcoin Reference DID method specification conforms to the requirements specified in the <a href="https://w3c-ccg.github.io/did-spec/">DID specification</a> currently published by the W3C Credentials Community Group. For more information about DIDs and DID method specifications, please see the <a href="https://github.com/WebOfTrustInfo/rwot7/blob/master/topics-and-advance-readings/did-primer.md">DID Primer</a>.


Note: In Amira, I ended up adding this line as well for markdown-to-html bolding:

Markup Shorthands: css no, markdown yes

Running Bikeshed

python bikeshed.py spec ../didm-btcr/index.bs