respec-themeable

respec-themeable

respec-themeable is a JS library that makes it easier to customize ReSpec for writing technical specifications. ReSpec developers are done a good job but there are some minor issues when you try to use it outside of W3C context. respec-themeable provides workarounds for these problems.

Features

• set background image text (left side bar) based on specStatus
• customizable publisher name (instead of the hardwired W3C)
• hide hardwired documentation W3C copyright texts
• set defaults for some respecConfig properties
• set logo from <link rel="icon" sizes="any" href="..."> element
• make main colors customizable via CSS variables

Demo

You can view this README file formatted with ReSpec at: https://respec-themeable.github.io

Installing

Add the following script tag after your respecConfig declaration script tag:

<script src="https://unpkg.com/respec-themeable" class="remove"></script>

Configuration

publisher

By default ReSpec uses W3C as an implicit publisher (ie: in background image text). respec-themeable accepts publisher from publisher configuration property.

var respecConfig = {
    publisher: "My Company"
}

When no publisher property is set, respec-themeable try to find company in the properties of authors and editors otherwise it falls back to shortName configuration property value.

noPackage

If the HTML document has web manifest link, respec-themeable will use it as source of some default respecConfig properties. Otherwise respec-themeable tries to use the file package.json relative to the HTML document. You can disable package.json usage by setting noPackage to true.

var respecConfig = {
    noPackage: true
}

logo

If the HTML document has icon link with sizes="any" attribute and there is no logo in respecConfig then the href from icon link will be used as logo src.

    <link rel="icon" sizes="any" href="logo.svg"/>

You can use data URL in the link's href attribute.

subtitle

If there is no subtitle in respecConfig then description property from manifest or package.json will be used as subtitle.

title

If there is no <title> tag in the HTML document then name property from manifest or package.json will be used as title.

shortName

If there is no shortName in respecConfig then name property from manifest or package.json will be used as shortName.

--theme-color

The main theme color can be set using --theme-color CSS variable.

:root {
    --theme-color: red;
}

--accent-color

The accent color can be set using --accent-color CSS variable.

:root {
    --accent-color: green;
}

version

If there is a version property in manifest or package.json then it will be displayed under the subtitle.

bugs

If there is a bugs property in manifest or package.json then it will be set with label Issues in the otherLinks configuration property.

repository

If there is a repisotroy.url property in manifest or package.json then it will be set with label Repository in the otherLinks configuration property.

data-format

You can use nunjucks, handlebars or mustache in data-format property (with data-include) for template processing external markdown files. Don't forget to provide script tag for selected template engine.

License

This project is licensed under the MIT License. See the LICENSE for details.