🎨 Semantic themes for use with Stencila encoda.

• Quick Start
• Available Themes
• Theme Structure
• Development
  • Prerequisites
  • Installation
  • Testing
• Technical Notes
• Acknowledgments

npm install @stencila/thema

/* myStyleSheet.css */
@import '@stencila/thema/dist/stencila/styles.css';

/* myJavaScript.js */
@import '@stencila/thema/dist/stencila';

• stencila: A custom designed theme suited for long-form reading, specifically research papers. It strives to deliver an optimal reading experience whilst giving figures and other media objects as much room as possible.
• eLife: Inspired by the eLife website, this theme provides as close of an approximation as possible for solely semantically structured documents such as Markdown.

There are two primary files inside each theme folder. The naming of these two files is important, and they must not be changed since they are referred to from encoda.

• styles.css: CSS and visual styles specific to the theme. We use PostCSS to compile the CSS, this is done to utilize PostCSS utilities such as autoprefixing vendor flags to selectors, and writing nested selectors.
• index.ts: Written in TypeScript, this file is loaded asynchronously. It is used to progressively enhance the theme with things like syntax highlighting of code blocks.

• Node.js
• npm
• git

1. Clone this repository

git clone [email protected]:stencila/thema.git

2. Install dependencies

npm install

3. Run development server

npm run dev

We use visual regression testing powered by Sauce Labs, Argos, and WebdriverIO. The themes are built, rendered in a browser running on Sauce Labs, and screenshots taken and compared by Argos, with the build results for Thema viewable here.

To run these tests locally, run npm run test. By default Webdriver will try to run the tests using Chrome, but you can switch to Firefox by setting an TEST_BROWSER=firefox environment variable.

When testing locally, there are three screenshot folders to be aware of inside the test/screenshots directory.

• reference: These are the baseline screenshots. To generate them, make sure your Git branch is free of any changes, and run npm test.
• local: These are screenshots generated by Webdriver tests, and will be compared to those found in the reference directory.
• diff: If any discrepancies are found between the reference and local screenshots, the differences will be highlighted and saved to this directory.

Results for online visual regression tests can be seen at argos-ci.com/stencila/thema.

We use Parcel to compile this module. One of the plugins we utilize to generate transportable and offline-viewable documents is parcel-plugin-url-loader to base64 encode and inline binary assets found in the CSS. This has the tradeoff that it leads to much larger page sizes, but the ability to generate stylesheets without inlining assets is on the roadmap.

We rely on many tools and services for which we are grateful ❤ to their developers and contributors for all their time and energy.

Tool	Use
	Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.
WebdriverIO	Next-gen WebDriver test framework for Node.js.
Argos CI	visual regression system gives you high confidence in doing changes.