EpubFs 0.5.1

dotnet add package EpubFs --version 0.5.1
                    
NuGet\Install-Package EpubFs -Version 0.5.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="EpubFs" Version="0.5.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="EpubFs" Version="0.5.1" />
                    
Directory.Packages.props
<PackageReference Include="EpubFs" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add EpubFs --version 0.5.1
                    
#r "nuget: EpubFs, 0.5.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package EpubFs@0.5.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=EpubFs&version=0.5.1
                    
Install as a Cake Addin
#tool nuget:?package=EpubFs&version=0.5.1
                    
Install as a Cake Tool

EpubFs

EPUB authoring library for F#.

Nuget package

Nuget

Project status

This library has been extracted from a personal project of mine and represents the bare minimum necessary to create EPUB files for my purposes. As such, I do not intend to continue developing any new major features.

However, if you or your company have a need for a particular feature or require that some other part of the EPUB spec be implemented, and you are willing to pay for the development, I would be more than happy to work with you!

Bug reports and PRs will naturally still be looked at.

Usage

In order to create an EPUB, you need to supply some metadata and a file manifest including the title page, list of files with the actual book content as well as any CSS files you want to use.

Content files

Content files are accepted in the form of XmlNode list, which you can construct using the Giraffe.ViewEngine DSL, or as a Stream containing an XHTML that you have obtained in some other way.

CSS files

You can also include stylesheets to be used in the book. If a content file is provided as XmlNode list, every CSS file will automatically be referenced therein. On the other hand, if you're supplying a full XHTML file, you need to import the stylesheet (in the traditional HTML fashion) yourself by using the FileName of a matching CSS file.

Table of contents (navigation document)

Every EPUB requires a navigation document. There are two choices here - either you supply an XHTML (it has to conform to the navigation spec!) directly, or you let the library generate a simple table of contents page with hyperlinks to each of your content files (whose Navigation is not set to None).

The generated document's headings and fixed entries come from NavLabels - pass Autogenerated NavLabels.English or your own translations.

It also contains a hidden list of landmarks, which reading systems use for "go to" menus: the table of contents, the start of the content (the first file with Navigation set), and every file (title page included) whose Landmark is set to a structural semantics type, such as titlepage, glossary or appendix, labelled with the file's Title.

Page progression direction

Set the manifest's PageProgressionDirection to Some Rtl for books whose pages turn right to left (Arabic, Hebrew, vertical Japanese...). None leaves it up to the reading system.

Media overlays (SMIL)

Starting from v0.4 the library supports EPUB Media Overlays, which allow you to synchronize audio narration with text content using SMIL files.

To add media overlays:

  1. Include your audio files in the manifest's OtherFiles list
  2. For each content file that should have audio synchronization, set the Smil property with a SmilFile record
  3. Add MediaOverlay metadata to your Metadata record, including the total duration

SMIL content can be provided in three ways:

  • SmilInput.Raw - A pre-built SMIL file as a stream
  • SmilInput.Structured - A list of XmlNode representing the SMIL head and body content
  • SmilInput.ParNodes - A simplified list of ParNode records, where each generates a <par> element with text and audio synchronization

For the sake of simplicity, the API assumes that every SMIL file references exactly one audio file (but many SMIL files can reference the same audio file) despite the fact that the spec allows references to multiple audio files.

Additional metadata and prefixes

Starting from v0.5 you can add arbitrary <meta> elements to the package metadata via Meta, for properties the Metadata record doesn't model directly, such as rendition:flow or reading-system-specific ones. Each MetaProperty can optionally refine another element by ID via Refines (e.g. "#creator1" for the first creator).

Properties from vocabularies outside the reserved prefixes (dcterms, rendition, a11y, ...) need their prefix declared in Prefixes. The media prefix is always declared.

For example, Apple Books only uses embedded fonts by default if the book says so:

Prefixes = [ { Name = "ibooks"; Iri = "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/" } ]
Meta = [ { Property = "ibooks:specified-fonts"; Value = "true"; Refines = None } ]

Example

open EpubFs
open Giraffe.ViewEngine
open System.IO
open System.Text

let metadata = {
    // A unique book identifier, could be ISBN or URL...
    Id = "my-book"
    Title = "Ὀδύσσεια"
    // List of language tags - you should use ISO 639-2
    // If you specify more than one, the first is considered the primary language of the book
    Languages = [ "grc" ]
    // `None` defaults to DateTimeOffset.UtcNow
    ModifiedAt = None
    Source = Some "https://el.wikisource.org/wiki/%CE%9F%CE%B4%CF%8D%CF%83%CF%83%CE%B5%CE%B9%CE%B1"
    Creators = [ "John Doe"; "Ὅμηρος" ]
    Description = Some "The epic tale of Odysseus's journey home."
    Publisher = Some "Ancient Greek Press"
    Subjects = [ "Epic Poetry"; "Greek Literature"; "Mythology" ]
    Rights = Some "Public Domain"
    // Media overlay metadata - required when using SMIL
    MediaOverlay = Some {
        TotalDuration = Choice2Of2 (TimeSpan.FromSeconds 5.0)
        ActiveClass = Some "-epub-media-overlay-active"
        PlaybackActiveClass = None
        Narrators = [ "Narrator Name" ]
    }
    // Vocabulary prefixes for non-reserved properties used in `Meta`
    Prefixes = []
    // Additional <meta> elements
    Meta = [ { Property = "rendition:flow"; Value = "paginated"; Refines = None } ]
}

// The CSS Stream you would like to use throughout the book
let css = new MemoryStream (".red-font { color: red }"B)

// Audio file for narration
use audioStream = File.OpenRead "chapter1.mp3"

// Let's declare the title page document using `Giraffe.ViewEngine`
// Use the `red-font` class from our stylesheet
let titlePage = {
    FileName = "title.xhtml"
    Title = "Title"
    Input = Structured [
        h1 [ _class "red-font" ] [
            str "Ὀδύσσεια"
        ]
    ]
    Navigation = None
    Smil = None
    // Listed in the landmarks of the generated navigation document
    Landmark = Some "titlepage"
}

// We already have a pre-built XHTML of the first content document, so pass it as a stream
// Notice the manual reference to our stylesheet
use chapter1Stream =
    """<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><link href="main.css" type="text/css" rel="stylesheet"/><title>Page one</title></head><body><div id="line1" class="red-font">Ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς μάλα πολλὰ</div><div id="line2">πλάγχθη, ἐπεὶ Τροίης ἱερὸν πτολίεθρον ἔπερσε·</div></body></html>"""
    |> Encoding.UTF8.GetBytes
    |> MemoryStream

let chapter1 = {
    FileName = "chapter1.xhtml"
    Title = "Chapter 1"
    Input = ContentInput.Raw chapter1Stream
    // Setting navigation to `Some` so that this document appears in the table of contents
    Navigation = Some Linear
    Landmark = None
    // Associate a SMIL file for audio synchronization
    // Notice references to div IDs of the chapter file above, and audio references to the file added in the manifest below
    Smil = Some {
        Duration = Choice2Of2 (TimeSpan.FromSeconds 5.0)
        Input = SmilInput.ParNodes ("chapter1.mp3", [
            {
                TextFragmentReference = "#line1"
                ClipBegin = Choice2Of2 TimeSpan.Zero
                ClipEnd = Choice2Of2 (TimeSpan.FromSeconds 2.5)
            }
            {
                TextFragmentReference = "#line2"
                ClipBegin = Choice1Of2 "00:00:02.500"
                ClipEnd = Choice2Of2 (TimeSpan.FromSeconds 5.0)
            }
        ])
    }
}

let manifest = {
    // Usually used by e-book readers as the book thumbnail
    CoverImage = None
    // Table of contents will be generated for us, with English headings
    NavigationFile = Autogenerated NavLabels.English
    TitlePage = titlePage
    ContentFiles = [ chapter1 ]
    CssFiles = [
        // The file will be stored in the archive under this name
        // It's also what you use to reference the stylesheet in XHTML
        { FileName = "main.css"; Input = css }
    ]
    OtherFiles = [
        { FileName = "chapter1.mp3"; MediaType = "audio/mpeg"; Input = audioStream; Compress = false }
    ]
    // Left to the reading system
    PageProgressionDirection = None
}

use fs = File.OpenWrite "odyssey.epub"
do! Write.write fs metadata manifest
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.5.1 70 11/12/2026
0.5.0 63 11/12/2026
0.4.0 200 3/8/2026
0.3.0 690 8/16/2022
0.2.0 600 8/16/2022
0.1.0 587 8/16/2022