View on GitHub

AozoraEpub3-JDK21

AozoraEpub3 - Aozora Bunko to EPUB 3 Converter (JDK 21)

narou.rb Setup & Troubleshooting Guide

⚠️ Notice

  • This article is not an official narou.rb manual.
  • The following information as of 2025-12-21 is a temporary workaround applied at your own risk.
  • Always check the narou.rb Official Wiki and Issues for the latest official information.
  • If the narou.rb tool is updated, the workarounds in this guide may become unnecessary.
  • Tested environment: Windows 11, Ruby 3.4.1, narou 3.9.1

This guide provides steps to install narou.rb (a web novel downloader) and integrate it with AozoraEpub3.

As of narou.rb v3.9.1, the following known issues are reported by the community:

  1. Dependency library (tilt) version mismatch causing startup errors
  2. Incompatibility with current “syosetu.com” website specification changes (table of contents not fetched)

This guide consolidates community-shared workarounds for these issues.

For official installation steps and prerequisites, please also refer to:

Note: kindlegen is not covered in this guide as “Send to Kindle” / email registration is currently unavailable.

1. Install Ruby (Windows Example)

  1. Visit RubyInstaller for Windows.
  2. Download and run Ruby+Devkit 3.4.x (x64) (marked “WITH DEVKIT”).
  3. During installation, keep the “MSYS2 development toolchain” checkbox checked.
  4. After installation, open PowerShell and run ruby -v to verify the version is displayed.

macOS/Linux are also supported, but this guide primarily covers Windows.

2. Install narou.rb

In PowerShell (or Command Prompt), run:

gem install narou

Note: Dependency issues may occur immediately after installation. If you see errors, apply the fixes in section 4 and later.

3. Prepare AozoraEpub3

Running AozoraEpub3-JDK21 requires Java 21.

  1. Check Java
    Run java -version in Command Prompt and confirm it shows version “21”.
  2. Download the software
    • Download the latest zip from Releases.
    • Extract it to any location (e.g., C:\Tools\AozoraEpub3).

Point: Avoid paths with Japanese characters or spaces; use ASCII characters only for best compatibility.

4. Fix tilt/erubis Error (Known Issue)

Symptom: Running narou produces cannot load such file -- tilt/erubis error.

Cause: narou 3.9.1 uses a library version that is too new. Downgrade to an older version to work around this.

Fix:

  1. Uninstall current tilt: 
    gem uninstall tilt

    (Should display “Successfully uninstalled…”)

  2. Install the workaround version: 
    gem install tilt -v 2.4.0

Reference:

5. Fix “syosetu.com” Table of Contents Error (Temporary Workaround)

Symptom: Downloads fail; table of contents and text cannot be retrieved.

Cause: “syosetu.com” website specifications have changed, and narou’s configuration files are outdated. Manually replace the YAML configuration files with community-provided fixes.

Workaround:

Apply the temporary fix shared by the community (PR #446).

1. Download Fixed Files Open the following GitHub link and download 2 files as instructed:

  1. Find webnovel/ncode.syosetu.com.yaml in the file list.
  2. Click the “…” (three-dot menu) in the top-right corner and select “View file”.
  3. Once the file content appears, click the “Download raw file” (↓ arrow icon) to save it.
  4. Repeat for webnovel/novel18.syosetu.com.yaml.

2. Overwrite Files Copy the 2 downloaded files to the narou.rb installation folder:

Recommendation: Before overwriting, rename the original files (e.g., filename.yaml.bak) as a backup.

6. Initialize and Configure AozoraEpub3 Integration

Create a folder for managing novels and run the initialization command:

mkdir MyNovels
cd MyNovels
narou init

When prompted with configuration options:

  1. “Please specify the AozoraEpub3 folder” will be displayed.
  2. Enter the path to the folder containing AozoraEpub3.jar from step 3.
    • Example: C:\Tools\AozoraEpub3
    • You can also drag and drop the folder from File Explorer.

Once complete, narou.rb will remember the AozoraEpub3 location and auto-integration is configured.

Note: Configuration Files After initialization, an AozoraEpub3.ini file appears in the same directory as AozoraEpub3.jar. To adjust line height, font size, and other conversion settings, edit this file directly or save settings from the AozoraEpub3 GUI.

7. Troubleshooting Tips