All Projects → Carleslc → Readteractive

Carleslc / Readteractive

Tool for writing and generating interactive books.

Programming Languages

115432 projects - #7 most used programming language

Projects that are alternatives of or similar to Readteractive

Open Publisher
Using Jekyll to create outputs that can be used as Pandoc inputs. In short - input markdown, output mobi, epub, pdf, and print-ready pdf. With a focus on fiction.
Stars: ✭ 242 (+952.17%)
Mutual labels:  latex, pandoc, mobi, pdf, epub
Koodo Reader
A modern ebook manager and reader with sync and backup capacities for Windows, macOS, Linux and Web
Stars: ✭ 2,938 (+12673.91%)
Mutual labels:  mobi, pdf, epub, book
Book publishing as easy as it should be (built with Symfony components)
Stars: ✭ 744 (+3134.78%)
Mutual labels:  book, mobi, pdf, epub
Converts books written in Markdown to HTML, LaTeX/PDF and EPUB
Stars: ✭ 399 (+1634.78%)
Mutual labels:  latex, book, pdf, epub
Ethereum Development With Go Book
📖 A little book on Ethereum Development with Go (golang)
Stars: ✭ 754 (+3178.26%)
Mutual labels:  book, mobi, pdf, epub
The Economist Ebooks
经济学人(含音频)、纽约客、自然、新科学人、卫报、科学美国人、连线、大西洋月刊、新闻周刊、国家地理等英语杂志免费下载、订阅(kindle推送),支持epub、mobi、pdf格式, 每周更新. The Economist 、The New Yorker 、Nature、The Atlantic 、New Scientist、The Guardian、Scientific American、Wired、Newsweek magazines, free download and subscription for kindle, mobi、epub、pdf format.
Stars: ✭ 3,471 (+14991.3%)
Mutual labels:  kindle, mobi, pdf, epub
Laravel Book
Up to date Epub, Mobi and PDF versions from the official Laravel Docs
Stars: ✭ 221 (+860.87%)
Mutual labels:  kindle, mobi, pdf, epub
Authoring Books and Technical Documents with R Markdown
Stars: ✭ 2,768 (+11934.78%)
Mutual labels:  latex, book, epub
Descarga manga en español en diferentes formatos (PNG, PDF, EPUB, MOBI)
Stars: ✭ 43 (+86.96%)
Mutual labels:  mobi, epub, kindle
Pandoc Starter
📄 My pandoc markdown templates and makefiles
Stars: ✭ 443 (+1826.09%)
Mutual labels:  latex, pandoc, writing
Redux Offline Docs
Redux documentation in PDF, ePub and MOBI formats for offline reading.
Stars: ✭ 292 (+1169.57%)
Mutual labels:  mobi, pdf, epub
Pandoc Letter Din5008
Pandoc template for writing Markdown letters (DIN 5008)
Stars: ✭ 77 (+234.78%)
Mutual labels:  latex, pandoc, pdf
Cv Boilerplate
Programmatic generation of high-quality CVs
Stars: ✭ 967 (+4104.35%)
Mutual labels:  latex, pandoc, pdf
Narou.rb - 小説家になろうのダウンローダ&縦書き整形&管理アプリ。Kindle(などの電子書籍端末)でなろうを読む場合に超便利です!
Stars: ✭ 256 (+1013.04%)
Mutual labels:  kindle, mobi, epub
Pandoc Latex Template
A pandoc LaTeX template to convert markdown files to PDF or LaTeX.
Stars: ✭ 3,750 (+16204.35%)
Mutual labels:  latex, pandoc, pdf
The EbookReader Android App. Support file format like epub, pdf, txt, html, mobi, azw, azw3, html, doc, docx,cbz, cbr. Support tts.
Stars: ✭ 37 (+60.87%)
Mutual labels:  mobi, epub, kindle
Stories About Ming Dynasty
Stars: ✭ 52 (+126.09%)
Mutual labels:  latex, kindle, pdf
Lightnovel Crawler
Download and generate e-books from online sources.
Stars: ✭ 344 (+1395.65%)
Mutual labels:  mobi, pdf, epub
Pandoc Book Template
A simple Pandoc template to build documents and ebooks.
Stars: ✭ 214 (+830.43%)
Mutual labels:  pandoc, pdf, epub
Ruby Hacking
Ruby Hacking Guide Translation
Stars: ✭ 305 (+1226.09%)
Mutual labels:  mobi, pdf, epub


Tool for writing and generating interactive books, also known as gamebooks.

Play this README as a gamebook!



What is a gamebook?

A gamebook is a work of printed fiction that allows the reader to participate in the story by making choices. Gamebooks have been influenced by Choose Your Own Adventure Series and tabletop role-playing games.

Production of new gamebooks in the West decreased dramatically during the nineties as choice based stories have moved away from print based media, although the format may be getting a new lease of life on mobile and ebook platforms. Such digital gamebooks are considered interactive fiction.

Getting started

Clone this repository with git or download the current version as zip.

Install dependencies

Note for Windows: It is easier to install this dependencies and run Readteractive with a linux-like shell like Cygwin.

  • Python 3: Needed to process structure and build Markdown files used to generate your book.
  • Make: Needed to bundle commands and generate your books in any format.
    • Linux: apt-get install build-essential
    • Mac OS:
      • (Xcode Utils) xcode-select --install
      • Or, using Homebrew: brew install make
    • Windows: Install make from Cygwin installer.
  • (HTML, PDF, EPUB) Pandoc: Needed to generate HTML, PDF and EPUB from Markdown files.
  • (MOBI) KindleGen: Needed to generate MOBI for Kindle from EPUB file.
  • (Optional) Kindle Previewer: Needed to preview how your MOBI files looks in tablet and Kindle devices.
  • (Optional) librsvg: Convert SVG images for being used inside PDF
    • Linux: apt-get install librsvg2-bin
    • Mac OS, using Homebrew: brew install librsvg
    • Windows: Install librsvg2 from Cygwin installer.


In development CLI repository

A yeoman generator for scaffolding Readteractive books.

We provide a command line interface to easily generate your project doing scaffolding, so you don't need to remember the syntax of each file and you can just focus on writing.

The Readteractive structure and files can be automatically generated using this CLI for your custom book.

It also provides a tool for visualization of your book with current chapters and the links between them, so you can have a general overview of the narrative branches of your book.

Install CLI and boost your productivity with Readteractive!

Readteractive structure

Top folder

In the top folder there are the required files for building your books and configure dependencies. Please, do not edit or move this files to another folder or build will fail.

├── .git
├── .gitignore
├── pandoc-html.css
├── makefile

Books and chapters folders

Every book and chapter you generate needs to match the following structure:

├── book-example/
│   └── _meta.yml
│   └── first_chapter/
│       ├──
│       └── first_chapter.yml
│   └── second_chapter/
│       ├── image.png
│       ├──
│       └── second_chapter.yml
├── cover.png
├── stylesheet.css

This structure and files can be automatically generated using our CLI for your custom book.

Syntax of .yml files is based on YAML.

Syntax of .md files is based on Markdown.

Syntax of stylesheet.css file is based on CSS, but this is optional as explained later.

Book metadata


title: Example _gamebook_
- First Author
- Second Author
start: first_chapter
language: es
cover-image: cover.png
stylesheet: stylesheet.css
description: |
    This is the description of your book.
    Hope you enjoy writting with Readteractive.
  • (Required) Title: The title of your book. You can use Markdown here using **bold** and _italic_.
  • (Optional) Author: The author of your book, or a list of authors. You can use Markdown here using **bold** and _italic_.
  • (Optional) Starting chapter: The chapter id (folder) of the first chapter in the book. Defaults to the first alphanumerically chapter.
  • (Optional) Language: ISO 639-1 Language Code. Defaults to en (English).
  • (Optional) Cover Image: File of the main image of your book.
  • (Optional) Stylesheet: The CSS stylesheet of your book.
  • (Optional) Description: The description of your book.



title: Example _chapter_

You can use Markdown here using **bold** and _italic_.

The text of your chapter. You can use Markdown here.

Chapters order

It is true that a gamebook does not have a strict order for chapters because users can jump from one to another according to the options they decide to follow, but sometimes is more elegant to have chapters sorted by narrative branch or other order you decide.

Once book is built, the first chapter shown will be the chapter specified in _meta.yml (if provided). The following chapters are shown in alphabetical order, but you can define your own order giving a numerical prefix to chapter identifiers like in this example:

├── book-example/
│   └── _meta.yml
│   └── 0-before/
│       ├──
│       └── 0-before.yml
│   └── 1-after/
│       ├── image.png
│       ├──
│       └── 1-after.yml

In this example, assuming that no start is set inside _meta.yml, the first chapter to show up will be 0-before, followed by 1-after.

How to build your book

If you have all dependencies installed is as easy as executing one command:

make BOOK=book-example

This will ensure your book and chapters structure is right, check for broken links between chapters and then pack and build your book in different formats:

  • HTML
  • PDF
  • EPUB
  • MOBI

The PDF version use LaTeX to get a high-quality typography.

Each chapter will generate a header in the table of contents of the PDF, EPUB and MOBI metadata, and each option will have a clickable link that jumps to the next chapter page.

The HTML version is more dynamic. It only shows the current chapter you have followed with a click on a link so story proceeds more interactively over the book. It also works offline (is self-contained).

If you want to keep available all visited chapters doing scroll you can set the variable SCROLL:

make html BOOK=book-example SCROLL=yes

The MOBI version is useful for Kindle devices.

Furthermore, you can build only the desired format:

make html BOOK=book-example
make pdf BOOK=book-example
make epub BOOK=book-example
make mobi BOOK=book-example

If you are going to print your book then you should be asking about chapter and page references, because links does not work in paper. You are right. If you do so you will need to have chapter order defined as explained in Chapters Order. Then, you can build your book using the variable PRINTED:

make BOOK=book-example PRINTED=yes

This will add the chapter order on each section and all link references will have that number after the option text. Then you can go to the last page where the Table of Contents is located and follow the page of the referenced chapter.

Building your book is even easier with our CLI wizard:

yo readteractive:build

Built files are saved in your book folder:

├── book-example/
│   └── book-example.html
│   └── book-example.pdf
│   └── book-example.epub
│   └──

How to write your book

A gamebook has many chapters with links between them. We refer to a chapter as a step with description in one of your narrative branches.

If you have no previous experience writing gamebooks these are some tips:

  1. Plan your story. You can make a mind map with each of your narrative branches and which options follow which branch.
  2. Define each chapter and write them with Readteractive.
  3. Visualize your chapter graph with our CLI whenever you need to have an overview of your book and ensure each chapter have the links you want.
  4. Build your book from time to time to have a look of how it is looking.

How to write options

Each chapter can link to a many different chapters using the following syntax:

(Text -> [next])

Replace Text with your custom option text. Replace next with the chapter id which this link is pointing to.

Readteractive will generate a link to the chapter on your book for every reference following this syntax.

You can use Markdown in Text.

You can skip the chapter prefix defined for custom order at the moment of writing an option in next:

(Go to after -> [after])

This option has the same effect than (Go to after -> [1-after]) and (Go to after -> [1_after]). This prefix skipping only works for digits followed by - or _.

Styling your book


You can use Markdown syntax for styling your chapters. This README file is written entirely in Markdown.

Markdown is simpler than HTML, but if you need to use it, Markdown supports HTML tags.

The example chapter provides very useful examples using Markdown.

In order to improve your writting even more you can use a Markdown highlight editor. There are many Markdown editors, some are online like this or this, and other are desktop applications like Typeora. Code editors like Atom or Sublime Text have markdown plugins too (Atom package, Sublime Text 3 package).

When you build your book, Readteractive will make HTML, PDF and EPUB versions using Pandoc. Pandoc allows you to do a few more things besides. You can read more about that in the Pandoc Manual.


If you know CSS you can customize the style of the book even more than with markdown and HTML.

For custom CSS of the HTML version edit the file pandoc-html.css at the top folder.

With EPUB and MOBI (e-book versions) you can optionally specify a stylesheet.css for your e-book in the _meta.yml file to have custom styles such font family or size.

If no stylesheet is provided then this one is used by default.

This option is not available for PDF because LaTeX is used


Although CSS is not available for PDF version because its style is set by LaTeX you can change margins and page breaks.

You can edit margin size in centimeters (cm) or inches (in) for PDF files setting the variable PDF_MARGIN:

make pdf BOOK=book-example PDF_MARGIN=1cm

You can define an explicit page break using \newpage and explicit new line using \newline inside your chapter .md file. Unfortunately at the moment this only works for PDF version.


Math equations are rendered using MathML, supported for HTML and PDF but only for some EPUB3 readers and currently gives unrecognised tags on KindleGen converting to MOBI.


  • Yeoman CLI to visualize graph links and renaming chapter ids.

  • Validate links.

  • Additional Readme and Tutorial in Spanish.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected]