Vivliostyle Base Theme

Base theme and CSS toolkit for Vivliostyle themes

Install

npm install --save @vivliostyle/theme-base
# or
yarn add @vivliostyle/theme-base

Use

In vivliostyle.config.js:

module.exports = {
  theme: '@vivliostyle/theme-base',
};

This package is designed to be modular so that it can be referenced and used by other themes. Each setting is configured as a CSS variable so that it can be changed to suit your preferences.

There're several presets to import modules we recommend.

• theme-all.css: imports all modules, including typesetting-specific features (cross reference, footnote etc.)
• theme-basic.css: imports basic modules such as css reset and basic styling

Import from vivliostyle.config.js

// Import theme-all.css
module.exports = {
  theme: {
    specifier: '@vivliostyle/theme-academic',
    import: 'theme-all.css',
  },
};
// Import theme-basic.css
module.exports = {
  theme: {
    specifier: '@vivliostyle/theme-academic',
    import: 'theme-basic.css',
  },
};

Import from CSS

/* Import theme-all.css */
@import url(@vivliostyle/theme-base/theme-all.css);
/* Import theme-basic.css */
@import url(@vivliostyle/theme-base/theme-basic.css);

Available modules and CSS variables

| Modules | theme-all.css | theme-basic.css | | :---------------------------------------------------- | :-----------: | :-------------: | | Basic | ✅ | ✅ | | Cross-reference | ✅ | - | | Endnotes | ✅ | - | | Footnotes | ✅ | - | | Page layout | ✅ | - | | Section references | ✅ | - | | Table of Contents | ✅ | - | | Utility classes | ✅ | - | | Prism (Code highlighting) | - | - |

Basic

@import url(@vivliostyle/theme-base/css/common/meta-properties.css);
@import url(@vivliostyle/theme-base/css/common/reset.css);
@import url(@vivliostyle/theme-base/css/common/basic.css);

/* Configuration examples */
:root {
  --vs-font-family: 'Times New Roman', serif;
  --vs-font-size: 12px;
  --vs--heading-line-height: 1.3;
  --vs--h1-font-size: 2.5em;
}

• meta-properties.css defines CSS variables that affect document-wide styles
  • Name of css variable starts with --vs-
• basic.css defines styles of basic HTML tags
  • Name of css variable starts with --vs--

Cross-reference

@import url(@vivliostyle/theme-base/css/partial/crossref.css);

/* Configuration examples */
:root {
  --vs-crossref--counter-style: upper-roman;
  --vs-crossref--marker-cite-content: target-counter(attr(href), cite) '.';
}

• crossref.css defines styles about cross-reference of figure, table and citation
  • Name of CSS variable starts with --vs-crossref--

Endnotes

@import url(@vivliostyle/theme-base/css/partial/endnote.css);

/* Configuration examples */
:root {
  --vs-endnote--call-font-size: 90%;
  --vs-endnote--section-ol-list-style-type: lower-latin;
}

• endnote.css defines styles about endnotes
  • Name of CSS variable starts with --vs-endnote--

Footnotes

@import url(@vivliostyle/theme-base/css/partial/footnote.css);
@import url(@vivliostyle/theme-base/css/partial/footnote-external-link.css);

/* Configuration examples */
:root {
  --vs-footnote--call-content: '[' counter(footnote) ']';
  --vs-footnote--area-before-margin-inline: 0 80%;
}

• footnote.css defines styles about footnotes
  • Name of CSS variable starts with --vs-footnote--
• footnote-external-link.css adds footnotes for external links so that its URL can be recognized on print media

Page layout

@import url(@vivliostyle/theme-base/css/partial/page.css);

/* Configuration examples */
:root {
  --vs-page--mbox-content-bottom-center: counter(page);
  /*
   * Vivliostyle.js provides env(doc-title) and env(pub-title)
   * https://docs.vivliostyle.org/#/supported-css-features#values
   */
  --vs-page--mbox-content-top-left: env(doc-title);
  --vs-page--mbox-content-top-right: string(section-title);
}
/*
 * Setting named string
 * https://www.w3.org/TR/css-gcpm-3/#named-strings
 */
h1 {
  string-set: section-title content();
}

• page.css defines styles about paged media
  • Name of CSS variable starts with --vs-page--

Section references

@import url(@vivliostyle/theme-base/css/partial/section.css);

/* Configuration examples */
:root {
  --vs-section--marker-display: inline;
  --vs-section--call-content: 'Sec. ' target-counters(attr(href), sections, '.');
}

• section.css defines styles about heading counters and section reference
  • Name of CSS variable starts with --vs-section--

Table of contents

@import url(@vivliostyle/theme-base/css/partial/toc.css);

/* Configuration examples */
:root {
  --vs-toc--marker-margin-inline: 8rem;
}

• toc.css defines styles about table of contents (TOC) pages
  • Name of CSS variable starts with --vs-toc--

Utility classes

@import url(@vivliostyle/theme-base/css/partial/utility-classes.css);

• utility-classes.css provides HTML utility classes related to page layout.

Prism (Code highlighting)

@import url(@vivliostyle/theme-base/css/lib/prism/base.css);
/* Use okaidia theme */
@import url(@vivliostyle/theme-base/css/lib/prism/theme-okaidia.css);
/* Use prism theme */
@import url(@vivliostyle/theme-base/css/lib/prism/theme-prism.css);

/* Configuration examples */
:root {
  --vs-prism--background: #aaa;
  --vs-prism--block-code-padding: 2rem 1rem;
}

• prism/base.css defines styles compatible with Prism (code highlighting library)
  • Name of CSS variable starts with --vs-prism--
• prism/theme-prism.css enables Prism.js default theme
  • Original theme: https://github.com/PrismJS/prism/blob/master/themes/prism.css

• prism/theme-okaidia.css enables okaidia theme
  • Original theme: https://github.com/PrismJS/prism/blob/master/themes/prism-okaidia.css

License

CC0 1.0

Original author: Vivliostyle project team