Mantium

Mantium is a cross-site manga tracker. It allows you to track manga from multiple source sites such as Mangadex and MangaPlus.

Mantium does not download the chapter images. Instead, it retrieves:

• Manga metadata (name, URL, cover, etc.)
• Chapter metadata (number, name, URL)

This data is displayed and managed in a web dashboard and can be embedded via an iFrame in your own dashboard.

---

Supported Sources

Mantium natively supports:

• Manga Plus
• MangaDex
• MangaHub
• MangaUpdates
• RawKuma
• KLManga
• JManga

It can also automatically track manga from nearly all sites using the Custom Manga feature.

Basic Workflow

1. Find a manga on a supported site.
2. Add it to Mantium.
3. Set its status (reading, dropped, completed, etc.).
4. Optionally set the last chapter you have read.
5. Configure periodic checks (e.g., every 30 minutes) to detect new chapters.
6. When notified about a new chapter, read it.
7. Update the last read chapter in Mantium.

This keeps your reading progress synchronized across sources.

---

Dashboard

By default, the dashboard:

• Shows manga with unread chapters first.
• Orders them by latest released chapter.
• Highlights unread manga titles with an animation effect.

Two display modes are available:

• Grid view
• List view

Grid View

<p align="center"> <img src="https://github.com/user-attachments/assets/404a5108-52d2-43a7-9bf3-81fa6721409a"> </p>

List View

<p align="center"> <img src="https://github.com/user-attachments/assets/93308cdb-93c0-420b-a32e-def5760b8671"> </p>

You can add manga from natively supported sites in two ways:

• By pasting the manga URL.
• By searching for the manga by name directly in Mantium.

| Using the Manga URL | Searching by Name | | :----------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------: | | | |

Sidebar

From the sidebar, you can:

• Filter manga by:
  • Name
  • Status (reading, completed, dropped, on hold, plan to read, all)
• Sort by:
  • Name
  • Last chapter read
  • Last uploaded chapter
  • Number of chapters
  • Unread (prioritizes unread manga)
• Reverse the sorting order.
• Add new manga.
• Configure dashboard settings (display mode, number of columns, etc.).

---

iFrame

Mantium provides an endpoint that returns a minimalist iFrame version of the dashboard.

The iFrame:

• Shows only manga with unread chapters.
• Includes only manga with status reading or completed.
• Is designed to be embedded in external dashboards.
• More details are available in the iFrame usage section below.

Multimanga

A Multimanga is a container for multiple entries of the same manga across different source sites.

When you add a manga to Mantium, a Multimanga is automatically created. You always interact with the Multimanga — not the individual source entries.

Why Multimanga?

If you track the same manga on multiple sites independently:

• Each entry appears separately in the dashboard and iFrame.
• You receive multiple notifications.
• You must update the last read chapter for each source.

With Multimanga:

• All sources are grouped.
• Only one dashboard and iFrame card is shown.
• You set the last read chapter once.
• You receive a single notification.

Current manga

Each Multimanga has a current manga, which determines:

• Which display name, cover image, and last released chapter to be shown in the dashboard and iFrame
• Chapter list shown when selecting last read chapter
• Chapter included in notifications

Mantium automatically selects the current manga to be the one with the newest released chapter using these rules:

1. If chapter numbers are equal → choose the one released most recently.
2. If chapter numbers differ → choose the one with the highest chapter number.
3. If chapter numbers are non-numeric → choose the one released most recently.

This selection runs:

• When adding/removing a manga from a Multimanga.
• During the background update job.

You can manage Multimanga settings via the Highlight button, including:

• Updating status
• Changing last read chapter
• Updating the cover image to one you prefer
• Adding or removing source entries
• Deleting the Multimanga

| Edit Multimanga | Edit Multimanga Cover Image | Manage Multimanga Mangas | | :----------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------: | | | | |

---

Custom Manga

Custom Manga allows you to track content not supported natively (manga, manhwa, light novels, etc.).

You must manually provide:

• Name
• URL
• Cover image (or use default)
• Last released chapter selectors

Last Released Chapter Selectors

Custom manga can automatically detect new chapters by getting the web page defined in the custom manga's URL field and applying selectors to get the chapter number and URL:

• Selector: CSS or XPath selector used to locate the element. Add the prefix css: for CSS selectors, and xpath: for XPATH selectors (ex: css:div.chapter-box > h4:first-child > a span). XPATH selectors also work with XML pages.
• Attribute (optional): Attribute containing the chapter name or URL (e.g., href). If empty, the element text is used.
• Regex (optional): Extracts the chapter number from the selected value.
• Get First (optional): If enabled, selects the first matching element; otherwise, selects the last.
• Use Browser (optional): Uses a headless browser if the page requires JavaScript rendering. Otherwise, a simple HTTP GET request is used.

[!NOTE] If the URL selector doesn't return a string that starts with http, Mantium will consider it a relative URL and will prepend the manga URL to it. For example, if the manga URL is https://example.com/one-piece and the URL selector returns /chapter1000, Mantium will consider the chapter URL to be https://example.com/chapter1000.

<img width="855" height="1335" alt="image" src="https://github.com/user-attachments/assets/4e844149-964e-463f-821f-f59a45c9a644" />

---

Background Updates and Notifications

Mantium can periodically:

• Refresh manga metadata from the source sites.
• Detect new chapters.
• Send notifications for manga with status reading or completed.

If an error occurs during background processing:

• A warning is displayed on the dashboard and iFrame.
• This warning can be disabled.
• You can set the minimum number of consecutive errors that must happen to show the warnings.

Custom manga selectors are also checked during background updates.

---

Integrations

Mantium has integrations with:

• Ntfy for new chapter notifications
• Kaizoku
• Tranga
• Suwayomi

See integrations.md for details.

---

Running

By default:

• API runs on port 8080.
• It is not exposed externally unless configured.

To expose it:

• Use Docker host network mode, or
• Place it behind a reverse proxy.

API_PORT can be used to change the default port.

Docker Compose

1. Clone the repository or create your own docker-compose.yml based on the one in this repository.
2. Create a .env file based on .env.example.
3. Start services:

docker compose up -d

Running manually/setting development environment

The steps are at the bottom of this README.

Notes:

iFrame usage

Endpoint:

/v1/mangas/iframe

[!NOTE]

• The endpoint is available via the API container, not the dashboard. If you run the API on port 8080 on your server, use your server IP address + port 8080.
• The iFrame is fetched directly by the web browser, not by your dashboard service.
• You browser must be able to access the Mantium API.
• If embedding in an HTTPS dashboard, the API must also be served over HTTPS, or else your browser will block the iFrame.

Parameters

• api_url (required) URL used by the browser to access the API.
• theme (optional) The iFrame theme. Can be light or dark.
• limit (optional) Maximum number of manga to display.
• showBackgroundErrorWarning (optional) If true (default), when an error occurs in the background job, a