Skip to content

Commit 34d2b95

Browse files
JayPanozJayPanoz
committed
Update docs
1 parent 990885b commit 34d2b95

5 files changed

Lines changed: 93 additions & 25 deletions

File tree

‎docs/badge-page.md‎

Lines changed: 47 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,72 @@
1-
# Badge Page
1+
# Badge Pages
22

3-
The badge page (`/badge/`) is a tool for OPDS and web catalog operators. It generates an "Add to Thorium Reader" badge — an SVG image wrapped in a deep link — that catalog pages can embed to let users add the catalog to Thorium Reader in one tap.
3+
The badge tools let OPDS/web catalog operators and publication hosts generate an "Add to Thorium Reader" badge — an SVG image wrapped in a deep link — to embed on their own pages so users can add the catalog or publication to Thorium Reader in one tap.
44

5-
## How it works
5+
`/badge/` is a hub page (`src/pages/[lang]/badge.astro`) linking to two separate generators:
66

7-
The badge is a static SVG (196×56 px) with the Thorium logo and localized "Add to Thorium Reader" text. When clicked, it opens a deep link URL that Thorium Reader intercepts to pre-fill a catalog entry.
7+
- `/badge/catalog/` — adds a catalog (and optional bookshelf)
8+
- `/badge/publication/` — adds a single publication
89

9-
The deep link is built from `addCatalogScheme` (defined in `src/links.ts`) with query parameters appended:
10+
Each generator page (`src/components/badge/*`) is a form that live-updates a preview badge and an embed snippet as the operator fills it in.
11+
12+
## Output formats
13+
14+
Each generator's output tab offers two integration options, selected via the "integration" field:
15+
16+
- **Link** — a static `<a href="…"><svg>…</svg></a>` snippet, wrapping the deep link scheme URL. The badge text is baked in at generation time for the selected language.
17+
- **Web component** — a `<thorium-badge-catalog>` or `<thorium-badge-publication>` custom element tag with the form values as attributes. This requires embedding the `@edrlab/thorium-badges` package (see [packages/thorium-badges/README.md](../packages/thorium-badges/README.md) and the deep-linking dev guide linked from the output panel) — the element renders its own SVG client-side and can use `lang="auto"` to detect the visitor's browser language, which the link format can't do.
18+
19+
## Catalog badge parameters
20+
21+
Deep link scheme: `addCatalogScheme` (`src/links.ts`), universal-link equivalent: `addCatalogUniversalLink`.
1022

1123
| Parameter | Required | Description |
1224
|-----------|----------|-------------|
1325
| `title` | yes | Catalog display name in Thorium Reader |
14-
| `browse` | yes* | OPDS or web URL to browse the catalog |
26+
| `main` | yes* | OPDS or web URL to browse the catalog |
1527
| `bookshelf` | yes* | OPDS or web URL for the user's bookshelf |
28+
| `passphrase` | no | Plain-text LCP passphrase |
29+
| `hashed_passphrase` | no | Pre-hashed LCP passphrase (use instead of `passphrase`) |
30+
| `open_in` | no | How to open catalog URLs: `webview` or `browser` |
1631
| `icon` | no | Square image URL (PNG or SVG) for the catalog icon |
17-
| `color` | no | Accent color (`gray`, `red`, `yellow`, `blue`, `green`, `purple`, `orange`) |
32+
| `banner` | no | Banner image URL |
33+
| `color` | no | Accent color (`gray`, `red`, `yellow`, `blue`, `green`, `purple`, `orange`, `pink`) |
34+
35+
*At least one of `main` or `bookshelf` is required for the badge link to be generated.
36+
37+
## Publication badge parameters
38+
39+
Deep link scheme: `addPublicationScheme` (`src/links.ts`), universal-link equivalent: `addPublicationUniversalLink`.
40+
41+
| Parameter | Required | Description |
42+
|-----------|----------|-------------|
43+
| `publication` | yes | Direct URL to the publication file |
44+
| `title` | no | Publication title |
45+
| `author` | no | Publication author |
46+
| `cover` | no | Cover image URL |
1847
| `passphrase` | no | Plain-text LCP passphrase |
19-
| `passphrase_hash` | no | Pre-hashed LCP passphrase (use instead of `passphrase`) |
20-
| `openIn` | no | How to open catalog URLs: `webview` or `browser` |
48+
| `hashed_passphrase` | no | Pre-hashed LCP passphrase (use instead of `passphrase`) |
2149

22-
*At least one of `browse` or `bookshelf` is required for the badge link to be generated.
50+
The full parameter/attribute lists live in [packages/thorium-badges/src/params.ts](../packages/thorium-badges/src/params.ts), shared between the generator pages and the web component.
2351

2452
## Output
2553

26-
The page produces an HTML snippet ready to paste into a catalog page:
54+
Both generators produce an HTML snippet ready to paste into a catalog or publication page:
2755

2856
```html
29-
<a href="https://www.thoriumreader.com?title=My+Catalog&browse=https%3A%2F%2F...">
57+
<a href="https://www.thoriumreader.com/add/catalog?title=My+Catalog&main=https%3A%2F%2F...">
3058
<svg …>…</svg>
3159
</a>
3260
```
3361

62+
## `/add/catalog/` and `/add/publication/` landing pages
63+
64+
These are the pages the universal links (and the web component's rendered links) point to — `src/pages/[lang]/add/catalog.astro` and `.../add/publication.astro`. They show a preview of the catalog/publication being added (name, cover when available), a button that retries the deep link (`ThoriumBadge`), and download links for Thorium Desktop (`DownloadContent`) for visitors without the app installed. If the URL carries no query params at all, the page shows an "invalid link" message instead of the normal add-in-progress copy.
65+
3466
## Localization
3567

36-
The badge text ("Add to" / "Thorium Reader") is rendered in the language selected in the form, independently of the page locale. All active site locales are available. The `badgeTexts` map (built at Astro render time from `en.json`, `fr.json`, etc.) is passed to the client script so the SVG updates live when the language selector changes.
68+
The badge text ("Add to" / "Thorium Reader") is rendered in the language selected in the generator form, independently of the page locale. All active site locales are available. The `badgeTexts` map (built at Astro render time from `en.json`, `fr.json`, etc.) is passed to the client script via `ClientData` so the SVG updates live when the language selector changes. The web component additionally supports `lang="auto"` (browser-language detection) — see [packages/thorium-badges/README.md](../packages/thorium-badges/README.md#localization).
3769

38-
## Updating `addCatalogScheme`
70+
## Updating `addCatalogScheme` / `addPublicationScheme`
3971

40-
The deep link base URL is `addCatalogScheme` in `src/links.ts`. Update it there if the scheme changes — the badge page picks it up automatically.
72+
The deep link base URLs are `addCatalogScheme`, `addPublicationScheme`, and their universal-link equivalents in `src/links.ts`. Update them there if a scheme changes — the badge pages pick it up automatically. See [links.md](links.md).

‎docs/components.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Full-width hero with a title, body text, and an image.
3030
| Prop | Type | Default | Description |
3131
|------|------|---------|-------------|
3232
| `title` | `string` | — | Heading text |
33-
| `body` | `string \| string[]` | — | Body paragraph(s) |
33+
| `body` | `string \| BodyBlock[]` | — | Body content — see [`BodyBlocks`](#componentssectionsbodyblocksastro) |
3434
| `image` | `{ src: ImageMetadata; alt: string }` | — | Hero image |
3535
| `clipImage` | `boolean` | `false` | Applies a clip-path to the image |
3636

@@ -49,7 +49,7 @@ Two-column feature block with text and a decoration or image.
4949
| Prop | Type | Default | Description |
5050
|------|------|---------|-------------|
5151
| `title` | `string` | — | Section heading |
52-
| `body` | `string \| string[]` | — | Body paragraph(s) |
52+
| `body` | `string \| BodyBlock[]` | — | Body content — see [`BodyBlocks`](#componentssectionsbodyblocksastro) |
5353
| `id` | `string` | — | HTML `id` on the section element |
5454
| `class` | `string` | — | Extra CSS classes |
5555
| `reverse` | `boolean` | `false` | Puts the media column on the left |
@@ -73,7 +73,7 @@ Call-to-action band with optional border graphics and a media column.
7373
| Prop | Type | Default | Description |
7474
|------|------|---------|-------------|
7575
| `title` | `string` | — | Heading |
76-
| `body` | `string \| string[]` | — | Body paragraph(s) |
76+
| `body` | `string \| BodyBlock[]` | — | Body content — see [`BodyBlocks`](#componentssectionsbodyblocksastro) |
7777

7878
**Slots**
7979

@@ -93,7 +93,7 @@ Introductory header used at the top of interior pages.
9393
| Prop | Type | Default | Description |
9494
|------|------|---------|-------------|
9595
| `title` | `string` | — | Page title |
96-
| `body` | `string \| string[]` | — | Optional subtitle |
96+
| `body` | `string \| BodyBlock[]` | — | Optional subtitle — see [`BodyBlocks`](#componentssectionsbodyblocksastro) |
9797
| `class` | `string` | — | Extra CSS classes |
9898

9999
**Slots**
@@ -104,6 +104,17 @@ Introductory header used at the top of interior pages.
104104

105105
---
106106

107+
### `components/sections/PageIntro.astro`
108+
109+
Title plus intro text, rendered via `BodyBlocks`. Used at the top of interior pages that don't need `PageHeader`'s extra styling.
110+
111+
| Prop | Type | Default | Description |
112+
|------|------|---------|-------------|
113+
| `title` | `string` | — | Page title |
114+
| `intro` | `string \| BodyBlock[]` | — | Optional intro content — see [`BodyBlocks`](#componentssectionsbodyblocksastro) |
115+
116+
---
117+
107118
### `components/sections/TabsSection.astro`
108119

109120
Section wrapper that renders a `Tabs` widget with decorative borders.
@@ -132,11 +143,31 @@ Accordion-style FAQ list.
132143
| Prop | Type | Default | Description |
133144
|------|------|---------|-------------|
134145
| `title` | `string` | — | Section heading |
135-
| `items` | `{ question: string; answer: FAQBlock[] }[]` | — | FAQ entries |
146+
| `items` | `{ question: string; answer: BodyBlock[] }[]` | — | FAQ entries — `answer` is rendered via [`BodyBlocks`](#componentssectionsbodyblocksastro) |
136147
| `class` | `string` | — | Extra CSS classes |
137148

138149
---
139150

151+
### `components/sections/BodyBlocks.astro`
152+
153+
Shared renderer for body content: a mix of paragraphs and up to two levels of nested lists. Used internally by `HeroSection`, `FeatureSection`, `CTASection`, `PageHeader`, `PageIntro`, and `FAQ` — any `body`/`intro`/`answer` prop typed `string | BodyBlock[]` accepts this format.
154+
155+
| Prop | Type | Default | Description |
156+
|------|------|---------|-------------|
157+
| `blocks` | `BodyBlock[]` | — | Blocks to render |
158+
159+
```ts
160+
type BodyListItem = string | string[];
161+
type BodyBlock = string | BodyListItem[];
162+
```
163+
164+
- A `string` block renders as a `<p>`.
165+
- A `BodyListItem[]` block renders as a `<ul>`. Each item is either a `string` (`<li>`) or a `string[]` — the first element is the parent `<li>` text, the rest render as a nested `<ul>`.
166+
167+
See [i18n-strings.md](i18n-strings.md#arrays) for the equivalent JSON shape.
168+
169+
---
170+
140171
## Buttons
141172

142173
### `components/buttons/ActionButton.astro`

‎docs/i18n-strings.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Body text that spans multiple paragraphs is stored as an array:
5050
}
5151
```
5252

53-
`t()` returns the array as-is; map over it to render each paragraph.
53+
`t()` returns the array as-is. Any prop rendered through `BodyBlocks` (`HeroSection`, `FeatureSection`, `CTASection`, `PageHeader`, `PageIntro`, and FAQ `answer`s — see [components.md](components.md#componentssectionsbodyblocksastro)) accepts this same array as its body content, including the list and nested-list forms described under [FAQ entries](#faq-entries) below — nesting isn't FAQ-specific, it works anywhere a `body`/`intro` prop takes a `BodyBlock[]`.
5454

5555
## Interpolation
5656

@@ -82,9 +82,9 @@ Locale-specific image alt strings live under the `alts` top-level key, keyed by
8282

8383
## FAQ entries
8484

85-
FAQ items live under `faq.items` and support up to two levels of list nesting inside the `answer` array.
85+
FAQ items live under `faq.items` and support up to two levels of list nesting inside the `answer` array. This is the same `BodyBlock[]` format used by any `body`/`intro` prop rendered through `BodyBlocks` — the nesting rules below apply there too.
8686

87-
Each element of `answer` is a block — either a paragraph or a list:
87+
Each element of `answer` (or `body`) is a block — either a paragraph or a list:
8888

8989
**Paragraph** — a plain string renders as `<p>`:
9090

‎docs/links.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,17 @@ All external URLs and versioned identifiers are centralized in `src/links.ts`. I
99
| `blogHref` | `string` | Thorium Reader blog URL |
1010
| `supportHref(lang)` | `(lang: string) => string` | Support site URL, locale-aware |
1111
| `discordHref` | `string` | Discord invite URL |
12+
| `githubHref` | `string` | EDRLab GitHub org URL — used for the Starlight sidebar social link in `astro.config.mjs` |
1213
| `appleAppId` | `string` | App Store app ID |
1314
| `appleReleaseDate` | `string` | App Store release date (Unix timestamp) |
1415
| `msProductId` | `string` | Microsoft Store product ID |
15-
| `addCatalogScheme` | `string` | Deep link base URL for adding a catalog to Thorium |
16+
| `addCatalogScheme` | `string` | Deep link scheme URL for adding a catalog to Thorium (`com.thoriumreader:/add/catalog`) |
17+
| `addCatalogUniversalLink` | `string` | HTTPS universal-link equivalent of `addCatalogScheme` (`https://www.thoriumreader.com/add/catalog`) |
18+
| `addPublicationScheme` | `string` | Deep link scheme URL for adding a single publication to Thorium |
19+
| `addPublicationUniversalLink` | `string` | HTTPS universal-link equivalent of `addPublicationScheme` |
1620
| `desktopVersion` | `string` | Current desktop release version string |
1721
| `downloadUrls` | `object` | Per-platform GitHub release download URLs (keyed by `macosArm`, `macosX64`, `windowsExe`, `windowsArm`, `linuxAppImage`, `linuxDeb`, `linuxAppImageArm`, `linuxDebArm`) |
22+
| `downloadPlatforms` | `object` | Same keys as `downloadUrls`, mapped to platform slugs used for analytics/labeling (e.g. `macosArm` → `"macos"`) |
1823

1924
## Updating the desktop version
2025

‎docs/release-notes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ See [Adding a Platform](adding-a-platform.md) if you're introducing release note
66

77
## Steps
88

9-
1. Create a new file named after the version: `src/content/release-notes/desktop/en/X.Y.Z.md`
9+
1. Create a new file named after the version, with dots replaced by dashes: `src/content/release-notes/desktop/en/X-Y-Z.md`
1010
2. Copy the frontmatter from an existing file and update the three fields:
1111

1212
```md

0 commit comments

Comments
 (0)