A comprehensive, blazing-fast local toolkit for scraping, managing, and compiling Light Novels into premium EPUBs.
Built originally to circumvent complex anti-scraping measures on translation sites, NarrativeOS gives you absolute control over your novel archiving experience. It seamlessly bridges the gap between web content and beautifully formatted eBooks.
With a robust Python backend and a highly responsive Vanilla JavaScript frontend, it transforms raw web text into professional, structured EPUB files in seconds.
The latest update introduces heavy-duty PDF parsing capabilities, refined metadata quality-of-life enhancements, and strict architectural stability.
- Native PDF Ingestion: A brand-new dedicated PDF2MD frontend panel lets you securely drag & drop raw PDFs and automatically extract their formatted text directly into your Novel Volumes.
- Smart Layout Mapping: Powered by a robust Python pipeline using
pdfplumberandPyMuPDF, it intelligently preserves paragraphs, chapter headers, and text structures.
- Visual Cover Autocomplete: Say goodbye to typing paths manually. The Metadata cover field now features an interactive popup grid that previews all local images inside your active volume. Click an image to instantly select it as the cover.
- TOC Quick Edit: A dedicated inline "Edit" button has been added directly to your Table of Contents markdown items. Clicking it instantly teleports you into the MD Editor for that exact chapter.
- Automated Data Syncing: Patched asynchronous panel-switching race conditions. Navigating between Scraper, Editor, and Metadata tabs perfectly synchronizes your selected novel/volume states without loading glitches.
- Stripped Production Assets: Executed a full-repository script to safely strip all redundant code comments (
//,<!-- -->,#), reducing file sizes and improving read speed. - Removed Orphaned Junk: Permanently expunged leftover testing folders (
test_debug,test_out,test_stress_out,tests) and redundantPDF2MD/subdirectories to keep the codebase hyper-clean.
v1.3.260620 (Architecture & UI Refinement)
- Frontend Modularization: Completely dismantled the monolithic
app.jsinto highly focused, specialized modules (editor.js,scraper.js,metadata.js,library.js, etc.). - Smart Media Engine: Auto-downloads and compresses markdown images to local WebP files on compile.
- Premium Themes: Added aesthetic palettes like Indigo Dark, Cinema Rose, Financial Navy, and Clean SaaS.
- Image Autocomplete Gallery: Real-time visual image autocomplete inside the Markdown editor.
- Advanced Cloudflare Bypass: Integrated
StealthyFetcherto aggressively bypass anti-bot protections.
v1.2.061926 (Security Update)
- Dynamic API Session Tokens: Implemented a robust
X-API-Keyauthentication system to completely lock down local backend endpoints against unauthorized access. - SSRF Mitigation: Added strict IP validation (
is_safe_url) to block unauthorized internal network requests during automated image downloads. - Enhanced Path Traversal Protection: Hardened backend security to completely block malicious file access requests (
..,:validation). - CORS Lockdowns: Restrictive Cross-Origin Resource Sharing applied to ensure only authorized local interfaces can communicate with the API.
- ReDoS Prevention: Mitigated severe Regex Denial of Service vulnerabilities in the Table of Contents extraction logic.
- Logging Overhaul: Replaced rudimentary log writing with Python's robust
RotatingFileHandler. - Thread Safety: Implemented
threading.Lockfixes during simultaneous markdown file saving to prevent data corruption.
- Automated Scraping: Paste a URL and NarrativeOS will fetch the chapter and convert it perfectly to clean Markdown.
- Batch Processing: Feed it a list of URLs and process an entire volume in seconds.
- Premium Bypass (HTML Paste): Got a locked chapter? Copy the HTML source code from your browser and paste it directly. NarrativeOS easily bypasses the lock.
- Advanced Image Recovery: Built-in canvas decoding easily breaks through obfuscated base64 canvases used by modern translation sites.
- Split-Pane View: Write or edit in raw Markdown on the left while watching a real-time, styled HTML preview on the right.
- Custom Syntax Highlighting: Uses a custom-built highlighter tailored specifically for novel formatting, making dialogue and thoughts pop.
- Auto-Saving & File Management: Rename, delete, or create chapters seamlessly within the interface.
- Intelligent Carry-Over: Creating a new volume automatically copies the Author, Artist, Genres, and Translator from the previous volume.
- Language Targeting: Set your primary title language (Japanese, English, Romaji) so your final EPUB looks exactly how you want it.
- Automated Book Assembly: With one click, NarrativeOS parses your Markdown and metadata to generate a perfectly structured EPUB.
- Premium Styling Elements: Automatically supports Drop Caps, elegant Scene Breaks (
***to❖ ❖ ❖), Character Thought Boxes(thought), Character Stats Box[stats], retro Game UI Notifications[UI], and Full-Page Image Isolation. - Smart Image Engine: Automatically downloads remote images, converts massive PNGs/JPEGs into lightweight WebP formats, compresses them, and safely localizes URLs.
- Backend: Python 3, FastAPI, Uvicorn, BeautifulSoup4, Scrapling
- Frontend: HTML5, Vanilla JavaScript (ES6 Modules), CSS3
- Compiler Architecture: Modular Python pipeline utilizing
zipfile,xml.etree.ElementTree, and standard libraries.
You need Python 3.8+ installed on your system.
Clone the repository and install the required dependencies:
git clone https://github.com/takoyune/NarrativeOS.git
cd NarrativeOS
pip install -r requirements.txtTo start the backend server and open the interface, simply run:
run_web.bat(Or manually run python server.py)
Open your web browser and navigate to: http://localhost:8765 (or the port defined in your console).
- Create a Novel: Add a Novel folder and then a Volume.
- Scrape or Write: Use the Scraper panel or Editor to add chapters.
- Add Metadata: Set your cover image and Table of Contents in the Metadata panel.
- Build: Click "Compile EPUB" in the Builder panel. Your finished book is ready!
For a complete list of supported Markdown tricks (like [UI] boxes, (thought) boxes, and (image) splitters), refer to the Styling_and_Tricks_Guide.md file included in this repository.