View on GitHub

AozoraEpub3-JDK21

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

AozoraEpub3 Usage Guide

Complete guide for using AozoraEpub3 to convert Aozora Bunko format text files to EPUB 3 format.

System Requirements: Java 25 recommended (Java 21 or later also works). Check with java -version.

Table of Contents

Quick Start

GUI Mode (No Arguments)

Simply double-click the JAR file or run:

java -jar AozoraEpub3.jar

A graphical interface will open where you can:

  1. Select input file (TXT, ZIP, RAR)
  2. Choose device preset (Kobo, Kindle, etc.)
  3. Click “Convert” to generate EPUB

CLI Mode (Simple)

## Convert UTF-8 text to EPUB
java -jar AozoraEpub3.jar -of -d output input.txt

## Convert with encoding specification
java -jar AozoraEpub3.jar -enc UTF-8 -of -d output input.txt

GUI Mode

Main Window

GUI Screenshot

Input File Selection

Output Settings

Device Presets

Select optimized settings for your e-reader:

Image Settings

Style Settings

Conversion Process

  1. Click Browse to select input file
  2. Select Device Preset (optional)
  3. Adjust Style Settings as needed
  4. Click Convert
  5. Progress bar shows conversion status
  6. EPUB file is saved to output directory

Web Novel Direct Conversion

Drag & drop a web novel URL or .url shortcut file to fetch and convert directly from supported sites.

Supported sites: Shōsetsuka ni Narō / Narō R18 / Kakuyomu / Hameln / Akatsuki / novelist.jp / FC2 Novel, etc.

narou.rb-Compatible Format Settings: Open “Web Novel Settings” from the GUI menu to configure:

Setting INI Key Description Default
Show update date per chapter show_post_date Display last update date at end of each chapter OFF
Show initial publish date per chapter show_publish_date Display original publish date for revised chapters OFF
Auto-detect author comments enable_author_comments Detect foreword/afterword by *44/*48 patterns ON
Auto indent enable_auto_indent Automatically insert line-leading indentation ON
Heading after page break enable_enchant_midashi Convert first line after page break to heading ON
Blank line compression enable_pack_blank_line Compress consecutive blank lines ON
Number to kanji enable_convert_num_to_kanji Convert Arabic numerals to kanji ON
Alphabet to zenkaku enable_alphabet_to_zenkaku Convert short English words to full-width ON
End of book marker enable_display_end_of_book Show completion mark at end ON
Auto join in brackets enable_auto_join_in_brackets Auto-join lines within brackets ON
Auto join at comma enable_auto_join_line Join lines ending with commas ON

Settings are saved in setting_narourb.ini and are compatible with narou.rb’s setting.ini keys.

Notes:

Command Line Interface

Basic Syntax

java -jar AozoraEpub3.jar [OPTIONS] input_file

Common Options

Input/Output

-enc <encoding>     Input file encoding (UTF-8, Shift_JIS, etc.)
-of                 Overwrite existing output file
-d <directory>      Output directory
-o <filename>       Output filename (without extension)

Device Presets

-p <preset.ini>     Use device preset file

Available presets (in presets/ directory):

Style Options

-y                  Horizontal writing mode (default: vertical)
-fs <size>          Font size percentage (80-150, default: 100)
-lh <height>        Line height (1.0-2.0, default: 1.75)
-mar <top>,<bottom>,<left>,<right>  Margins in em (default: 0,0,0,0)

Image Options

-ih <height>        Image max height in pixels
-iw <width>         Image max width in pixels
-isize <kb>         Image max size in KB
-jpeg <quality>     JPEG quality (1-100, default: 85)
-rmargin            Remove image margins

Table of Contents

-tocnest <level>    TOC nesting level (1-3, default: 2)
-toctitle <title>   TOC title (default: "目次")

Cover Image

-cover <image>      Cover image file

Advanced

-gaiji <mode>       Gaiji (external characters) mode
                    0=Use UTF-8, 1=Use alternative characters
-dakuten <mode>     Dakuten font mode (0-2)
-autopage <lines>   Auto page break after N lines

Web Novel URL

-url <URL>          Convert web novel from URL directly
-narou              Apply narou.rb-compatible format settings
-interval <seconds> Page fetch interval (default: 0.5)
-cache <path>       Cache directory (default: .cache)

Examples

Convert UTF-8 text (vertical)

java -jar AozoraEpub3.jar -enc UTF-8 -of -d output novel.txt

Convert with Kobo preset

java -jar AozoraEpub3.jar -p presets/kobo_glo.ini -of -d output novel.txt

Horizontal writing with custom style

java -jar AozoraEpub3.jar -y -fs 110 -lh 1.8 -of -d output essay.txt

Batch conversion

java -jar AozoraEpub3.jar -of -d output chapter*.txt

Convert ZIP archive

java -jar AozoraEpub3.jar -of -d output novel_archive.zip

With cover image

java -jar AozoraEpub3.jar -cover cover.jpg -of -d output novel.txt

Convert web novel from URL

java -jar AozoraEpub3.jar -url https://ncode.syosetu.com/nXXXX/ -d output

# With narou.rb-compatible settings
java -jar AozoraEpub3.jar -url https://ncode.syosetu.com/nXXXX/ -narou -d output

Device Presets

Preset files (.ini) contain optimized settings for specific e-readers.

Using Presets

GUI: Select from “Device Preset” dropdown

CLI: Use -p option

java -jar AozoraEpub3.jar -p presets/kobo_glo.ini input.txt

Preset File Format

[画像設定]
画像の倍率=1.0
画像縮小JPEG品質=80
最大画像横幅=758
最大画像縦幅=1024
最大画像ファイルサイズ=64

[余白設定]
表紙上余白=0.0
表紙下余白=0.0
本文上余白=0.0
本文下余白=0.0

[スタイル設定]
フォントサイズ=100
行の高さ=1.7

Creating Custom Presets

  1. Copy an existing preset file
  2. Edit values in a text editor
  3. Save with .ini extension
  4. Use with -p option

Template Customization

AozoraEpub3 uses Apache Velocity templates for EPUB generation.

Template Files Location

template/
├── mimetype
├── META-INF/
│   └── container.xml
└── OPS/
    ├── package.vm          # package.opf generation
    ├── toc.ncx.vm          # NCX table of contents
    └── css/
        ├── vertical_text.vm    # Vertical CSS
        └── horizontal_text.vm  # Horizontal CSS

Customizing CSS

Edit template/OPS/css/vertical_text.vm or horizontal_text.vm:

:root {
  --font-size: ${fontSize}%;
  --line-height: ${lineHeight};
  --margin-top: ${marginTop}em;
  --margin-bottom: ${marginBottom}em;
}

body {
  font-size: var(--font-size);
  line-height: var(--line-height);
}

Variables from INI files or CLI options are automatically injected.

Customizing XHTML Structure

Edit package.vm to modify EPUB metadata or manifest structure.

Note: After modifying templates, rebuild the application:

./gradlew clean build

Troubleshooting

Encoding Issues

Problem: Garbled text in EPUB

Solution: Specify correct encoding

java -jar AozoraEpub3.jar -enc UTF-8 input.txt

Common encodings:

Image Size Issues

Problem: Images too large for device

Solution: Use image resize options

java -jar AozoraEpub3.jar -iw 758 -ih 1024 input.txt

Memory Issues

Problem: OutOfMemoryError with large files

Solution: Increase Java heap size

java -Xmx2g -jar AozoraEpub3.jar input.txt

EPUB Validation Errors

Problem: EPUB doesn’t open on device

Solution: Validate with epubcheck

java -jar epubcheck.jar output.epub

Fix common issues:

ZIP/RAR Archive Issues

Problem: Cannot extract text from archive

Solution:

Advanced Features

Aozora Notation Support

AozoraEpub3 supports most Aozora Bunko notation:

Ruby (Furigana)

漢字《かんじ》
｜漢字《かんじ》

Emphasis

［＃傍点］強調テキスト［＃傍点終わり］
［＃「○○」に傍点］

Font Size

［＃大きな文字］Large Text［＃大きな文字終わり］
［＃小さな文字］Small Text［＃小さな文字終わり］

Alignment

［＃ここから２字下げ］
Indented paragraph
［＃ここで字下げ終わり］

Page Breaks

［＃改ページ］
［＃改丁］

External Characters (Gaiji)

AozoraEpub3 handles external characters using:

Example:

※［＃「木＋世」、第3水準1-85-66］

Auto Page Break

Split large files into multiple pages:

java -jar AozoraEpub3.jar -autopage 100 large_novel.txt

Creates page breaks every 100 lines.

Table of Contents Depth

Control TOC nesting:

java -jar AozoraEpub3.jar -tocnest 3 novel.txt