Skip to content

Commit 07de316

Browse files
JayPanozJayPanoz
committed
Update docs
1 parent 34a457e commit 07de316

9 files changed

Lines changed: 1561 additions & 1353 deletions

File tree

‎_includes/toc.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
<li><a href="CSS09-default_fonts.html">Typefaces and font-stacks</a></li>
1212
<li><a href="CSS10-libre_fonts.html">Open Source and Libre Fonts We Can Recommend</a></li>
1313
<li><a href="CSS10b-variable_fonts.html">Variable fonts</a></li>
14+
<li><a href="CSS10c-custom_fonts.html">Using custom fonts with Readium CSS</a></li>
1415
<li><a href="CSS11-overrides_classification.html">User Overrides’ Classification</a></li>
1516
<li><a href="CSS12-user_prefs.html">User Settings and Themes</a></li>
1617
<li><a href="CSS13-a11y_settings_baseline.html">Baseline for a11y-related user settings</a></li>

‎docs/CSS09-default_fonts.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -497,4 +497,10 @@ Implementers might want to load this patch only if they find one of the followin
497497
- version 1: `<dc:description id="ebpaj-guide">ebpaj-guide-1.0</dc:description>`
498498
- version 1.1: `<meta property="ebpaj:guide-version">1.1</meta>`
499499

500-
Since `@font-face` must be used to align with EBPAJ’s specific implementation (rendering engines have to go through 9–11 `local` sources in the worst-case scenario), implementers should expect a performance debt.
500+
Since `@font-face` must be used to align with EBPAJ’s specific implementation (rendering engines have to go through 9–11 `local` sources in the worst-case scenario), implementers should expect a performance debt.
501+
502+
## Android System Generic families Patch
503+
504+
In beta versions of Readium CSS 2, we introduced a patch for Times, Times New Roman, Arial, and Helvetica, relying on Nimbus Sans and Nimbus Roman as metric-compatible replacements on Android devices. It can be critical for Fixed-Layout publications using these fonts without having embedded their fonts.
505+
506+
Since we cannot provide `@font-face` rules for system fonts, this patch was not included in the final version of Readium CSS 2 and you will need to implement it yourself if you want to support these fonts on Android.

‎docs/CSS10c-custom_fonts.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Using custom fonts with Readium CSS
2+
3+
[Implementers’ doc]
4+
5+
Now that we have seen libre and variable fonts, let's see how to use custom fonts with Readium CSS.
6+
7+
Readium CSS cannot provide `@font-face` rules, as this would require apps to embed fonts in every EPUB file they render, at a specific path relative to the current resource displayed. This does not scale, would bloat file sizes, and would not resolve the issue of previewing these fonts in the app itself.
8+
9+
## Declaring fonts
10+
11+
Apps can declare custom fonts by injecting `@font-face` rules into the content’s `head` element. It is critical that these rules are injected in each content resource, as the browser needs to resolve the `font-family` values used in the Readium CSS stylesheet.
12+
13+
To declare a static font:
14+
15+
```css
16+
@font-face {
17+
font-family: "MyCustomFont";
18+
src: url("https://example.org/path/to/font.woff2") format("woff2");
19+
font-weight: normal;
20+
font-style: normal;
21+
}
22+
23+
@font-face {
24+
font-family: "MyCustomFont";
25+
src: url("https://example.org/path/to/font-italic.woff2") format("woff2");
26+
font-weight: normal;
27+
font-style: italic;
28+
}
29+
30+
/* Bold and BoldItalic */
31+
```
32+
33+
To declare a variable font:
34+
35+
```css
36+
@font-face {
37+
font-family: "MyCustomVariableFont";
38+
src: url("https://example.org/path/to/variable-font.woff2") format("woff2");
39+
font-weight: 100 900;
40+
font-stretch: 50% 200%;
41+
}
42+
```
43+
44+
Your `src` url must be the exact path to the font file. The path type depends on how you serve the fonts:
45+
46+
- **Relative paths** (e.g., `url("../fonts/font.woff2")`) when fonts are bundled within the package you serve
47+
- **Full absolute URLs** (e.g., `url("https://example.org/path/to/font.woff2")`) when fonts are hosted externally
48+
49+
This is important because the CSS may be used in different contexts such as iframes where incorrect path resolution will fail to load the font.
50+
51+
## Applying a custom font
52+
53+
Once you have declared a custom font, you can apply it to elements in your EPUB content by using the `--USER__fontFamily` property of Readium CSS.
54+
55+
```javascript
56+
document.documentElement.style.setProperty("--USER__fontFamily", "MyCustomFont, sans-serif");
57+
```
58+
59+
You can also leverage variable fonts by using their dedicated properties:
60+
61+
- `--USER__fontWeight`
62+
- `--USER__fontWidth`
63+
64+
Then:
65+
66+
```javascript
67+
document.documentElement.style.setProperty("--USER__fontWeight", "575");
68+
document.documentElement.style.setProperty("--USER__fontWidth", "125%");
69+
```

‎docs/ReadiumCSS_docs.epub‎

4.73 KB
Binary file not shown.

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-009.xhtml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -957,6 +957,14 @@ unicode-range: U+0500-052F;</code></pre>
957957

958958
<p>Since <code>@font-face</code> must be used to align with EBPAJ’s specific implementation (rendering engines have to go through 9–11 <code>local</code> sources in the worst-case scenario), implementers should expect a performance debt.</p>
959959
</section>
960+
961+
<section id="android-system-generic-families-patch" class="level2">
962+
<h2 id="sigil_toc_id_220">Android System Generic families Patch</h2>
963+
964+
<p>In beta versions of Readium CSS 2, we introduced a patch for Times, Times New Roman, Arial, and Helvetica, relying on Nimbus Sans and Nimbus Roman as metric-compatible replacements on Android devices. It can be critical for Fixed-Layout publications using these fonts without having embedded their fonts.</p>
965+
966+
<p>Since we cannot provide <code>@font-face</code> rules for system fonts, this patch was not included in the final version of Readium CSS 2 and you will need to implement it yourself if you want to support these fonts on Android.</p>
967+
</section>
960968
</section>
961969
</body>
962970
</html>

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-010c.xhtml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!DOCTYPE html>
3+
4+
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="en">
5+
<head>
6+
<meta charset="utf-8"/>
7+
<meta name="generator" content="pandoc"/>
8+
<title>Readium CSS Implementers’ doc</title>
9+
<link rel="stylesheet" type="text/css" href="../Styles/stylesheet.css"/>
10+
</head>
11+
12+
<body xml:lang="en">
13+
<section id="custom-fonts" class="level1">
14+
<h1>Using custom fonts with Readium CSS</h1>
15+
16+
<p>[Implementers’ doc]</p>
17+
18+
<p>Now that we have seen libre and variable fonts, let's see how to use custom fonts with Readium CSS.</p>
19+
20+
<p>Readium CSS cannot provide <code>@font-face</code> rules, as this would require apps to embed fonts in every EPUB file they render, at a specific path relative to the current resource displayed. This does not scale, would bloat file sizes, and would not resolve the issue of previewing these fonts in the app itself.</p>
21+
22+
<section id="declaring-fonts" class="level2">
23+
<h2 id="sigil_toc_id_221">Declaring fonts</h2>
24+
25+
<p>Apps can declare custom fonts by injecting <code>@font-face</code> rules into the content’s <code>head</code> element. It is critical that these rules are injected in each content resource, as the browser needs to resolve the <code>font-family</code> values used in the Readium CSS stylesheet.</p>
26+
27+
<p>To declare a static font:</p>
28+
29+
<pre><code>@font-face {
30+
font-family: "MyCustomFont";
31+
src: url("https://example.org/path/to/font.woff2") format("woff2");
32+
font-weight: normal;
33+
font-style: normal;
34+
}
35+
@font-face {
36+
font-family: "MyCustomFont";
37+
src: url("https://example.org/path/to/font-italic.woff2") format("woff2");
38+
font-weight: normal;
39+
font-style: italic;
40+
}
41+
42+
/* Bold and BoldItalic */</code></pre>
43+
44+
<p>To declare a variable font:</p>
45+
46+
<pre><code>@font-face {
47+
font-family: "MyCustomVariableFont";
48+
src: url("https://example.org/path/to/variable-font.woff2") format("woff2");
49+
font-weight: 100 900;
50+
font-stretch: 50% 200%;
51+
}</code></pre>
52+
53+
<p>Your <code>src</code> url must be the exact path to the font file. The path type depends on how you serve the fonts:</p>
54+
55+
<ul>
56+
<li><strong>Relative paths</strong> (e.g., <code>url("../fonts/font.woff2")</code>) when fonts are bundled within the package you serve</li>
57+
<li><strong>Full absolute URLs</strong> (e.g., <code>url("https://example.org/path/to/font.woff2")</code>) when fonts are hosted externally</li>
58+
</ul>
59+
60+
<p>This is important because the CSS may be used in different contexts such as iframes where incorrect path resolution will fail to load the font.</p>
61+
</section>
62+
63+
<section id="applying-a-custom-font" class="level2">
64+
<h2 id="sigil_toc_id_222">Applying a custom font</h2>
65+
66+
<p>Once you have declared a custom font, you can apply it to elements in your EPUB content by using the <code>--USER__fontFamily</code> property of Readium CSS.</p>
67+
68+
<pre><code>document.documentElement.style.setProperty("--USER__fontFamily", "MyCustomFont, sans-serif");</code></pre>
69+
70+
<p>You can also leverage variable fonts by using their dedicated properties:</p>
71+
72+
<ul>
73+
<li><code>--USER__fontWeight</code></li>
74+
<li><code>--USER__fontWidth</code></li>
75+
</ul>
76+
77+
<p>Then:</p>
78+
79+
<pre><code>document.documentElement.style.setProperty("--USER__fontWeight", "575");
80+
document.documentElement.style.setProperty("--USER__fontWidth", "125%");</code></pre>
81+
</section>
82+
</section>
83+
</body>
84+
</html>

‎docs/ReadiumCSS_docs/OEBPS/Text/nav.xhtml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,9 @@
269269
<li>
270270
<a href="../Text/Section-009.xhtml#sigil_toc_id_130">EBPAJ patch for Japanese</a>
271271
</li>
272+
<li>
273+
<a href="../Text/Section-009.xhtml#sigil_toc_id_220">Android System Generic families Patch</a>
274+
</li>
272275
</ol>
273276
</li>
274277
<li>
@@ -323,6 +326,17 @@
323326
</li>
324327
</ol>
325328
</li>
329+
<li>
330+
<a href="../Text/Section-010c.xhtml">Using custom Fonts with Readium CSS</a>
331+
<ol>
332+
<li>
333+
<a href="../Text/Section-010c.xhtml#sigil_toc_id_221">Declaring fonts</a>
334+
</li>
335+
<li>
336+
<a href="../Text/Section-010c.xhtml#sigil_toc_id_222">Applying a custom font</a>
337+
</li>
338+
</ol>
339+
</li>
326340
<li>
327341
<a href="../Text/Section-011.xhtml">User Overrides’ Classification</a>
328342
<ol>

‎docs/ReadiumCSS_docs/OEBPS/content.opf‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<dc:language>en</dc:language>
99
<dc:identifier id="epub-id-1">urn:uuid:527D093B-9C0A-4C83-8AF6-0A40E91D30FC</dc:identifier>
1010
<meta name="cover" content="cover_jpg" />
11-
<meta property="dcterms:modified">2025-11-03T17:21:00Z</meta>
11+
<meta property="dcterms:modified">2026-02-19T10:52:18Z</meta>
1212
<meta name="Sigil version" content="0.9.8" />
1313
<meta property="schema:accessibilityFeature">displayTransformability</meta>
1414
<meta property="schema:accessibilityFeature">readingOrder</meta>
@@ -77,6 +77,7 @@
7777
<item id="Section-028.xhtml" href="Text/Section-028.xhtml" media-type="application/xhtml+xml"/>
7878
<item id="alt-lines.png" href="Images/alt-lines.png" media-type="image/png"/>
7979
<item id="Section-010b.xhtml" href="Text/Section-010b.xhtml" media-type="application/xhtml+xml"/>
80+
<item id="Section-010c.xhtml" href="Text/Section-010c.xhtml" media-type="application/xhtml+xml"/>
8081
<item id="Cabin.png" href="Images/Cabin.png" media-type="image/png"/>
8182
<item id="Crimson-pro.png" href="Images/Crimson-pro.png" media-type="image/png"/>
8283
<item id="EB-Garamond.png" href="Images/EB-Garamond.png" media-type="image/png"/>
@@ -106,6 +107,7 @@
106107
<itemref idref="Section-009.xhtml"/>
107108
<itemref idref="Section-010.xhtml"/>
108109
<itemref idref="Section-010b.xhtml"/>
110+
<itemref idref="Section-010c.xhtml"/>
109111
<itemref idref="Section-011.xhtml"/>
110112
<itemref idref="Section-012.xhtml"/>
111113
<itemref idref="Section-013.xhtml"/>

0 commit comments

Comments
 (0)