Vivliostyle Themes Contribution Guide

Developing theme

See Theme Spec.

Developing this repository

This repository is a pnpm workspace. Install pnpm and use the Node.js version pinned in .nvmrc.

pnpm install
pnpm build       # generate the theme CSS and compile the TypeScript packages; validate needs them
pnpm lint
pnpm fmt         # or fmt:check
pnpm typecheck
pnpm validate    # check every theme package against the spec
pnpm test

The example:* scripts work on the example books shipped with each theme, not on the themes themselves. Building them renders every example with Vivliostyle CLI, which downloads a browser on first run and takes several minutes:

pnpm example:build
pnpm example:capture-pdf  # regenerate docs/assets/captures/*.webp from the built PDFs
pnpm --filter @vivliostyle/theme-techbook example:preview  # preview a single example

Releasing

Releases run on Changesets. Add a changeset in the same pull request as your change:

pnpm exec changeset

Merging to main opens a version pull request, and merging that one publishes to npm.

Publishing runs in the Production deployment environment, so any reviewers configured on it are asked to approve the release. Publishing, tagging and the GitHub release all happen in that one job: GitHub requests approval separately for every job referencing an environment, and splitting them would mean approving the same release several times. Every published package gets a <name>@<version> tag; the GitHub release is created for @vivliostyle/theme-base only.

Publishing authenticates through npm's trusted publishing (OIDC), which every package registers against the workflow file name .github/workflows/release.yml. Renaming that file stops publishing until each package's trusted publisher entry is updated.

Donating your theme

We appreciate your donation to the list of our official themes!

Merging criteria

The design and type of your theme should be reasonably distinct from all other existing official themes. This is to avoid duplication.
Your theme has to meet our Theme Spec.
You have to sign the Contributor License Agreement.
You must follow Code of Conduct.

Perks

You will become a member of Vivliostyle as well as a maintainer of vivliostyle/theme as a part of @vivliostyle/theme team.
You will be given permissions to manage vivliostyle/themes and all the other theme-related repositories which enables you to:
- Push to the repository
- Triage issues
- Review and merge pull-requests