From 987f7f2d4bf4ff48da2ff8c6d2044fe9b9f6f8b6 Mon Sep 17 00:00:00 2001 From: everpcpc Date: Sun, 25 Oct 2026 14:39:18 +0800 Subject: [PATCH 1/3] docs: clarify supported library formats --- src/content/docs/server/intro.mdx | 16 ++++++++++++++++ src/pages/faq.astro | 8 ++++++++ src/pages/index.astro | 6 ++++++ src/pages/server/index.astro | 1 + 4 files changed, 31 insertions(+) diff --git a/src/content/docs/server/intro.mdx b/src/content/docs/server/intro.mdx index 6587f8e..f9bbdd1 100644 --- a/src/content/docs/server/intro.mdx +++ b/src/content/docs/server/intro.mdx @@ -25,9 +25,25 @@ Try KMServer at [demo.kmworks.date](https://demo.kmworks.date): the latest image - **Drop-in replacement** for `gotson/komga`: same port (25600), same `/config` and `/data` mounts, same `KOMGA_*` environment variables - **Data-level compatibility**: opens and upgrades existing komga data directories (`database.sqlite`, `tasks.sqlite`) in place, and the Java version can still open libraries written by KMServer +- **Library formats**: CBZ/ZIP, CBR/RAR, PDF, and EPUB — scanning, metadata extraction, thumbnails, and Komga-compatible page/resource serving - **API parity**: REST `/api/**`, OPDS v1.2/v2, SSE, Kobo sync, and KOReader progress sync, with endpoints, DTOs, pagination, error shapes, and authentication behavior matching the Java version - **Verified against the Java version**: byte-for-byte Flyway migrations, a differential test harness comparing ~105 endpoints against a live Java instance, and schema contract tests +## Supported formats + +KMServer scans the same library file types as Komga. Each library can independently enable or disable CBX (CBZ/ZIP and CBR/RAR), PDF, and EPUB scanning. + +| Format | Support | +| ------ | ------- | +| **CBZ / ZIP** | Image pages, `ComicInfo.xml` metadata, thumbnails, and page serving. | +| **CBR / RAR** | RAR 4 and RAR 5 image archives, with the same metadata, thumbnail, and page-serving flow. | +| **PDF** | Page analysis, thumbnails, and on-demand JPEG rendering through libpdfium. The Docker image includes libpdfium; standalone installations must provide it at runtime. | +| **EPUB** | OPF metadata, tables of contents, landmarks, reading positions, and resource serving. Compatible readers render reflowable and fixed-layout books; image-based EPUBs can also use DIVINA page reading. | + +Webtoon is a reading presentation, not a file format. For webtoons and long strips, choose Webtoon in a compatible reader; the book itself still uses one of the formats above. + +For media-type restrictions and PDFium lookup details, see [Known limitations](/server/limitations#media-formats). + ## Enhancements On top of drop-in compatibility, KMServer adds improvements the Java version does not have: diff --git a/src/pages/faq.astro b/src/pages/faq.astro index 04b4e0c..aa44f1b 100644 --- a/src/pages/faq.astro +++ b/src/pages/faq.astro @@ -27,6 +27,14 @@ const faqs = [ q: "Can I continue using other Komga clients?", a: "Yes. KMServer speaks the same API: REST, OPDS v1.2/v2, SSE, Kobo and KOReader sync. Your existing clients reconnect without changes.", }, + { + q: "Which file formats does KMServer support?", + a: "KMServer scans CBZ/ZIP, CBR/RAR, PDF, and EPUB books. Webtoon is a reading presentation for compatible books, not a separate file format.", + }, + { + q: "How can KMServer support PDF and EPUB while staying lightweight?", + a: "PDF pages are rendered on demand by libpdfium instead of PDFBox on a JVM. The Docker image includes libpdfium; standalone installations must provide it. EPUB packages are parsed on the server, while compatible readers handle layout using the served metadata, navigation, and resources.", + }, { q: "Does KMReader work offline?", a: "Yes. Downloaded books stay fully readable offline: pages, covers, metadata and progress are stored locally.", diff --git a/src/pages/index.astro b/src/pages/index.astro index a1d9759..b75af16 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -178,6 +178,12 @@ const serverFeatures = [ ))} +
+ CBZ + CBR + PDF + EPUB +
Download KMServer diff --git a/src/pages/server/index.astro b/src/pages/server/index.astro index 9bd38fd..f239d00 100644 --- a/src/pages/server/index.astro +++ b/src/pages/server/index.astro @@ -70,6 +70,7 @@ const clients = [
Written in Rust Komga-compatible + CBZ · CBR · PDF · EPUB Existing libraries Existing database Cross-platform From 846e54777806f4eab8e060423c14590183b377d1 Mon Sep 17 00:00:00 2001 From: everpcpc Date: Sun, 25 Oct 2026 15:11:02 +0800 Subject: [PATCH 2/3] docs: clarify full-featured Komga replacement --- astro.config.ts | 2 +- src/content/docs/server/compatibility.mdx | 11 +++++++++++ src/content/docs/server/intro.mdx | 15 +++++++++++---- src/pages/architecture.astro | 4 ++-- src/pages/faq.astro | 4 ++++ src/pages/index.astro | 11 ++++++----- src/pages/server/index.astro | 14 ++++++++------ 7 files changed, 43 insertions(+), 18 deletions(-) diff --git a/astro.config.ts b/astro.config.ts index fafa509..cced11f 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -9,7 +9,7 @@ const nimbusConfig = defineNimbusConfig({ site: "https://kmworks.date", title: "kmworks", description: - "kmworks is an open-source comic and manga reading ecosystem: server and native clients, drop-in compatible with Komga.", + "kmworks is an open-source reading ecosystem: KMReader, a native Apple client, and KMServer, a full-featured Komga drop-in replacement in Rust with additional capabilities.", locale: "en", github: "https://github.com/kmworks", editPattern: "https://github.com/kmworks/website/edit/main/{path}", diff --git a/src/content/docs/server/compatibility.mdx b/src/content/docs/server/compatibility.mdx index bb04f64..4de543e 100644 --- a/src/content/docs/server/compatibility.mdx +++ b/src/content/docs/server/compatibility.mdx @@ -6,6 +6,17 @@ sidebar: The compatibility target is **komga 1.29.0**: the Flyway migrations, the OpenAPI document, and the behavior fixtures are taken from that release, and API behavior is ported from it. Improvements and intentional behavior differences are listed under [Enhancements](/server/enhancements); accepted gaps under [Known limitations](/server/limitations). +## Compatibility scope + +KMServer is a full-featured drop-in replacement, not a CBZ/CBR-only or API-only subset. Its scope includes: + +- **Libraries and media**: CBZ/ZIP, CBR/RAR, PDF, and EPUB scanning, metadata extraction, thumbnails, and page/resource serving +- **APIs and clients**: REST, OPDS v1.2/v2, SSE, Kobo and KOReader sync, authentication, and the bundled web UI +- **Existing installations**: the same port, mounts, and `KOMGA_*` environment variables, with in-place upgrades of `database.sqlite` and `tasks.sqlite` that remain readable by Java Komga +- **Additional capabilities**: smart lists, reading trackers, CJK cross-search, outbound webhooks, reading statistics, and the other [Enhancements](/server/enhancements) + +The accepted gaps and intentional scope exclusions are explicit: see [Known limitations](/server/limitations). + ## Differential test harness `tests/diff/diff.py` starts the Java komga and kmrs side by side over the same fixture library and compares ~105 endpoints (status, normalized JSON/XML bodies, headers, zip structure): diff --git a/src/content/docs/server/intro.mdx b/src/content/docs/server/intro.mdx index f9bbdd1..2284d74 100644 --- a/src/content/docs/server/intro.mdx +++ b/src/content/docs/server/intro.mdx @@ -4,7 +4,7 @@ sidebar: order: 0 --- -KMServer is a drop-in, API-compatible reimplementation of the [Komga](https://komga.org) comic/manga server in Rust, distributed as the `kmrs` binary: a single static executable. +KMServer is a full-featured drop-in replacement for [Komga](https://komga.org) in Rust — same library formats, API, and database, plus additional capabilities. It is distributed as the `kmrs` binary: a single static executable. *The name: Keep Manga Reading Simple.* @@ -28,6 +28,7 @@ Try KMServer at [demo.kmworks.date](https://demo.kmworks.date): the latest image - **Library formats**: CBZ/ZIP, CBR/RAR, PDF, and EPUB — scanning, metadata extraction, thumbnails, and Komga-compatible page/resource serving - **API parity**: REST `/api/**`, OPDS v1.2/v2, SSE, Kobo sync, and KOReader progress sync, with endpoints, DTOs, pagination, error shapes, and authentication behavior matching the Java version - **Verified against the Java version**: byte-for-byte Flyway migrations, a differential test harness comparing ~105 endpoints against a live Java instance, and schema contract tests +- **Beyond Komga**: smart lists, reading trackers, CJK cross-search, outbound webhooks, reading statistics, and [more](/server/enhancements) ## Supported formats @@ -46,10 +47,16 @@ For media-type restrictions and PDFium lookup details, see [Known limitations](/ ## Enhancements -On top of drop-in compatibility, KMServer adds improvements the Java version does not have: +On top of drop-in compatibility, KMServer adds capabilities the Java version does not have: -- **Search**: simplified ↔ traditional Chinese cross-search and CJK boundary unigrams (e.g. `3月` matches `3月的狮子`). See [Search](/server/search). -- **Sorting**: natural sort of numbered titles ("Page 2" < "Page 10") with a configurable ICU locale (`server.sort-locale`). The full list: [Enhancements](/server/enhancements). +- **Smart lists**: saved searches evaluated live per user, with sharing scopes and generated covers +- **Reading trackers**: reading-progress sync with AniList, MyAnimeList, Bangumi, and MangaBaka +- **Search**: simplified ↔ traditional Chinese cross-search and CJK boundary unigrams (e.g. `3月` matches `3月的狮子`) +- **Outbound webhooks**: library events delivered as signed JSON payloads +- **Reading statistics**: per-user totals, daily activity, and reading streaks +- **Sorting**: natural sort of numbered titles ("Page 2" < "Page 10") with a configurable ICU locale (`server.sort-locale`) + +See the full list under [Enhancements](/server/enhancements). ## Migrating from Komga diff --git a/src/pages/architecture.astro b/src/pages/architecture.astro index c729a88..45a3fe7 100644 --- a/src/pages/architecture.astro +++ b/src/pages/architecture.astro @@ -10,12 +10,12 @@ export const prerender = true; const blocks = [ { title: "Server", - body: "KMServer is a single static Rust binary (kmrs). It scans your library directories in place and serves everything over HTTP on port 25600. The kmweb UI is embedded in the binary, so the browser interface works out of the box.", + body: "KMServer is a full-featured Komga drop-in replacement with additional capabilities, distributed as a single static Rust binary (kmrs). It scans your library directories in place and serves everything over HTTP on port 25600. The kmweb UI is embedded in the binary, so the browser interface works out of the box.", icon: "ph:hard-drives", }, { title: "API", - body: "The Komga-compatible surface: REST under /api, OPDS v1.2/v2 catalogs, SSE live updates, and Kobo and KOReader sync. A differential harness compares about 105 endpoints against a live Java instance of the compatibility target (komga 1.28.1).", + body: "The Komga-compatible surface: REST under /api, OPDS v1.2/v2 catalogs, SSE live updates, and Kobo and KOReader sync. A differential harness compares about 105 endpoints against a live Java Komga instance.", icon: "ph:plugs-connected", }, { diff --git a/src/pages/faq.astro b/src/pages/faq.astro index aa44f1b..482eddd 100644 --- a/src/pages/faq.astro +++ b/src/pages/faq.astro @@ -27,6 +27,10 @@ const faqs = [ q: "Can I continue using other Komga clients?", a: "Yes. KMServer speaks the same API: REST, OPDS v1.2/v2, SSE, Kobo and KOReader sync. Your existing clients reconnect without changes.", }, + { + q: "Is KMServer a full Komga replacement or a lightweight subset?", + a: "KMServer is a full-featured drop-in replacement for Komga, not a CBZ/CBR-only subset. It supports the same library formats, API, and database, and adds capabilities such as smart lists, reading trackers, CJK cross-search, webhooks, and reading statistics.", + }, { q: "Which file formats does KMServer support?", a: "KMServer scans CBZ/ZIP, CBR/RAR, PDF, and EPUB books. Webtoon is a reading presentation for compatible books, not a separate file format.", diff --git a/src/pages/index.astro b/src/pages/index.astro index b75af16..7155bfd 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -23,7 +23,7 @@ const dockerRun = `docker run -d \\ const serverFeatures = [ { title: "One binary", icon: "ph:package" }, { title: "Cross-platform", icon: "ph:devices" }, - { title: "Komga-compatible", icon: "ph:plugs-connected" }, + { title: "Komga + enhancements", icon: "ph:plugs-connected" }, { title: "Web UI included", icon: "ph:browser" }, { title: "Existing libraries", icon: "ph:books" }, { title: "Existing database", icon: "ph:database" }, @@ -32,7 +32,7 @@ const serverFeatures = [
@@ -47,7 +47,7 @@ const serverFeatures = [

An open-source ecosystem for your comic and manga library: KMReader, a native Apple client, and KMServer, a - Komga-compatible server in Rust. + full-featured Komga drop-in replacement in Rust.

@@ -167,8 +167,9 @@ const serverFeatures = [

KMServer

Your library. One server.

- Komga reimplemented in Rust: one static binary, a bounded - footprint, and the web UI included. + A full-featured Komga drop-in replacement in Rust: the same + formats, API and database, plus additional capabilities — in + one static binary.

{serverFeatures.map((f) => ( diff --git a/src/pages/server/index.astro b/src/pages/server/index.astro index f239d00..e526b3b 100644 --- a/src/pages/server/index.astro +++ b/src/pages/server/index.astro @@ -49,8 +49,8 @@ const clients = [ ---
@@ -64,12 +64,14 @@ const clients = [

KMServer

Your library. One server.

- Komga reimplemented in Rust: one static binary, a bounded - footprint, and the web UI included. + A full-featured Komga drop-in replacement in Rust: the same + formats, API and database, plus additional capabilities — in + one static binary.

Written in Rust Komga-compatible + Komga + enhancements CBZ · CBR · PDF · EPUB Existing libraries Existing database @@ -187,8 +189,8 @@ const clients = [

API parity, verified

REST, OPDS v1.2/v2, SSE, Kobo and KOReader sync. A differential - harness compares about 105 endpoints against a live Java - instance of the compatibility target (komga 1.28.1). + harness compares about 105 endpoints against a live Java Komga + instance.

From bd8a6f4848aed43a348d90789fc3ec0b88f9a3ab Mon Sep 17 00:00:00 2001 From: everpcpc Date: Sun, 25 Oct 2026 15:29:49 +0800 Subject: [PATCH 3/3] docs: highlight small footprint and efficient serving --- astro.config.ts | 2 +- src/content/docs/server/intro.mdx | 3 ++- src/pages/architecture.astro | 2 +- src/pages/faq.astro | 2 +- src/pages/index.astro | 9 +++++---- src/pages/server/index.astro | 13 +++++++------ 6 files changed, 17 insertions(+), 14 deletions(-) diff --git a/astro.config.ts b/astro.config.ts index cced11f..c74311b 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -9,7 +9,7 @@ const nimbusConfig = defineNimbusConfig({ site: "https://kmworks.date", title: "kmworks", description: - "kmworks is an open-source reading ecosystem: KMReader, a native Apple client, and KMServer, a full-featured Komga drop-in replacement in Rust with additional capabilities.", + "kmworks is an open-source reading ecosystem: KMReader, a native Apple client, and KMServer, a full-featured Komga drop-in replacement in Rust with additional capabilities and a small memory footprint.", locale: "en", github: "https://github.com/kmworks", editPattern: "https://github.com/kmworks/website/edit/main/{path}", diff --git a/src/content/docs/server/intro.mdx b/src/content/docs/server/intro.mdx index 2284d74..bce2060 100644 --- a/src/content/docs/server/intro.mdx +++ b/src/content/docs/server/intro.mdx @@ -4,7 +4,7 @@ sidebar: order: 0 --- -KMServer is a full-featured drop-in replacement for [Komga](https://komga.org) in Rust — same library formats, API, and database, plus additional capabilities. It is distributed as the `kmrs` binary: a single static executable. +KMServer is a full-featured drop-in replacement for [Komga](https://komga.org) in Rust — same library formats, API, and database, plus additional capabilities. It is distributed as the `kmrs` binary: a single static executable with no JVM and a small memory footprint. *The name: Keep Manga Reading Simple.* @@ -28,6 +28,7 @@ Try KMServer at [demo.kmworks.date](https://demo.kmworks.date): the latest image - **Library formats**: CBZ/ZIP, CBR/RAR, PDF, and EPUB — scanning, metadata extraction, thumbnails, and Komga-compatible page/resource serving - **API parity**: REST `/api/**`, OPDS v1.2/v2, SSE, Kobo sync, and KOReader progress sync, with endpoints, DTOs, pagination, error shapes, and authentication behavior matching the Java version - **Verified against the Java version**: byte-for-byte Flyway migrations, a differential test harness comparing ~105 endpoints against a live Java instance, and schema contract tests +- **Efficient by design**: no JVM, bounded memory, and container caches that avoid reopening books for every page - **Beyond Komga**: smart lists, reading trackers, CJK cross-search, outbound webhooks, reading statistics, and [more](/server/enhancements) ## Supported formats diff --git a/src/pages/architecture.astro b/src/pages/architecture.astro index 45a3fe7..6e02445 100644 --- a/src/pages/architecture.astro +++ b/src/pages/architecture.astro @@ -10,7 +10,7 @@ export const prerender = true; const blocks = [ { title: "Server", - body: "KMServer is a full-featured Komga drop-in replacement with additional capabilities, distributed as a single static Rust binary (kmrs). It scans your library directories in place and serves everything over HTTP on port 25600. The kmweb UI is embedded in the binary, so the browser interface works out of the box.", + body: "KMServer is a full-featured Komga drop-in replacement with additional capabilities, distributed as a single static Rust binary (kmrs) with no JVM and a small memory footprint. It scans your library directories in place and serves everything over HTTP on port 25600. The kmweb UI is embedded in the binary, so the browser interface works out of the box. Bounded memory and container caches keep resource use predictable and page serving efficient.", icon: "ph:hard-drives", }, { diff --git a/src/pages/faq.astro b/src/pages/faq.astro index 482eddd..bba0197 100644 --- a/src/pages/faq.astro +++ b/src/pages/faq.astro @@ -29,7 +29,7 @@ const faqs = [ }, { q: "Is KMServer a full Komga replacement or a lightweight subset?", - a: "KMServer is a full-featured drop-in replacement for Komga, not a CBZ/CBR-only subset. It supports the same library formats, API, and database, and adds capabilities such as smart lists, reading trackers, CJK cross-search, webhooks, and reading statistics.", + a: "KMServer is a full-featured drop-in replacement for Komga, not a CBZ/CBR-only subset. It supports the same library formats, API, and database, and adds capabilities such as smart lists, reading trackers, CJK cross-search, webhooks, and reading statistics. It also runs without a JVM, with bounded memory and container caches for efficient page serving.", }, { q: "Which file formats does KMServer support?", diff --git a/src/pages/index.astro b/src/pages/index.astro index 7155bfd..eae7101 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -21,7 +21,7 @@ const dockerRun = `docker run -d \\ ghcr.io/kmworks/kmrs`; const serverFeatures = [ - { title: "One binary", icon: "ph:package" }, + { title: "Small footprint", icon: "ph:package" }, { title: "Cross-platform", icon: "ph:devices" }, { title: "Komga + enhancements", icon: "ph:plugs-connected" }, { title: "Web UI included", icon: "ph:browser" }, @@ -32,7 +32,7 @@ const serverFeatures = [
@@ -47,7 +47,8 @@ const serverFeatures = [

An open-source ecosystem for your comic and manga library: KMReader, a native Apple client, and KMServer, a - full-featured Komga drop-in replacement in Rust. + full-featured Komga drop-in replacement in Rust with a small + memory footprint.

@@ -169,7 +170,7 @@ const serverFeatures = [

A full-featured Komga drop-in replacement in Rust: the same formats, API and database, plus additional capabilities — in - one static binary. + one static binary with no JVM and a small memory footprint.

{serverFeatures.map((f) => ( diff --git a/src/pages/server/index.astro b/src/pages/server/index.astro index e526b3b..b7c04b0 100644 --- a/src/pages/server/index.astro +++ b/src/pages/server/index.astro @@ -50,7 +50,7 @@ const clients = [
@@ -66,7 +66,7 @@ const clients = [

A full-featured Komga drop-in replacement in Rust: the same formats, API and database, plus additional capabilities — in - one static binary. + one static binary with no JVM and a small memory footprint.

Written in Rust @@ -77,6 +77,7 @@ const clients = [ Existing database Cross-platform Single binary + Small footprint
@@ -151,11 +152,11 @@ const clients = [
-

Bounded memory

+

Small footprint, efficient serving

- A 16 MiB SQLite page-cache budget per database and capped - allocator arenas keep the footprint flat, whatever the - hardware. Enhancements + A 16 MiB SQLite page-cache budget per database, capped + allocator arenas, and bounded container caches keep memory + predictable and page serving efficient. Enhancements