144 lines
8.3 KiB
Markdown
144 lines
8.3 KiB
Markdown
# Epub Theme
|
|
## An epub theme for the Static Site Generator HUGO.
|
|
|
|
This is a simple ebook generator that creates a valid epub ebook from md files.
|
|
|
|
## The epub format
|
|
|
|
I use the newer [epub3 format](http://hoffmann.bplaced.net/epub/epub3.php). The file structure looks like this:
|
|
|
|
```
|
|
├── mimetype
|
|
├── META-INF
|
|
│ └── container.xml
|
|
└── OEBPS
|
|
├── chapter
|
|
│ ├── chapter-1.xhtml
|
|
│ ├── chapter-1
|
|
│ │ ├── image-1-1.jpg
|
|
│ │ └── image-1-2.jpg
|
|
│ ├── chapter-2.xhtml
|
|
│ ├── chapter-3.xhtml
|
|
│ ├── chapter-3
|
|
│ │ └── image-3.jpg
|
|
│ ...
|
|
│
|
|
├── content.opf
|
|
├── cover.jpg
|
|
├── css
|
|
│ └── stylesheet.css
|
|
├── inhaltsverzeichnis.xhtml
|
|
├── titelseite.xhtml
|
|
└── toc.ncx
|
|
```
|
|
|
|
## How the as HUGO epub theme works
|
|
|
|
* _mimetype_, _container.xml_ and _stylesheet.css_ are static files located in the _static/_ theme folder
|
|
* _cover.jpg_ is located in the _static/OEBPS_ folder
|
|
|
|
The rest of the files are dynamically generated from the **content** of the HUGO project:
|
|
|
|
```
|
|
content
|
|
├── _index.md
|
|
├── inhaltsverzeichnis.md
|
|
├── blog
|
|
│ ├── chapter-1
|
|
│ │ ├── image-1-1.jpg
|
|
│ │ ├── image-1-2.jpg
|
|
│ │ └── index.md
|
|
│ ├── chapter-2.md
|
|
│ └── chapter-3
|
|
│ ├── image-3.jpg
|
|
│ └── index.md
|
|
└── titelseite.md
|
|
```
|
|
|
|
**_index.md** creates the central files _content.opf_ and _toc.ncx_ via the configuration in _config.toml_ and the theme layout. The setting
|
|
|
|
```
|
|
cascade:
|
|
_build:
|
|
publishResources: false
|
|
```
|
|
|
|
in frontmatter ensures that only the scaled images end up in the ebook folder and the original files are not copied along with them -- which HUGO would otherwise do by default.
|
|
|
|
**table of contents.md** and **title page.md** create these necessary pages in the ebook. These files must not be deleted or renamed. The content comes from params in _config.toml_. In the frontmatter the parameter
|
|
`ebook: toc`
|
|
resp.
|
|
`ebook: cover`
|
|
ensures that the template _single.xhtml_ handles these special cases differently from the standard.
|
|
|
|
The actual theme layout under **themes/epub/layouts** consists of only three files:
|
|
|
|
```
|
|
├── _default
|
|
│ └── single.xhtml
|
|
├── index.ncx
|
|
├── index.opf
|
|
```
|
|
|
|
**single.xhtml** creates all xhtml pages, **index.ncx** is the template for _toc.ncx_ and **index.opf** creates _content.opf_. All this is controlled by _config.toml_. Normally these three files do not need to be changed.
|
|
Also, all files used in the ebook must be registered in the _manifest_ of _content.opf_. This happens automatically for all files from the content folder. But if, for example, static images are referenced in the pages, they would have to be added manually in the _manifest_. This happens in _index.opf_.
|
|
|
|
**config.toml** contains all meta data for the ebook and ensures that the correct file structure is created:
|
|
|
|
* _disableKinds_ turns off almost everything that HUGO does by default. We only generate output for _pages_ and for the root file *_index.md*.
|
|
* _permalinks_ plays an important role. Here we have to define the path for each _section_ contained in _content/_. I have predefined an entry for "blog". If there should be other or further _sections_ (these are the folders directly below _content/_), a line must be added in each case.
|
|
* _mediaTypes_, _outputFormats_ and _outputs_ define the three file formats dynamically generated by HUGO: xhtml, opf and ncx. Corresponding templates are located in the _layouts/_ directory of the theme.
|
|
* _markup_ controls the interpretation of the markdown files and can be customized as desired. The setting _xHTML = true_ must not be changed.
|
|
* _params_ contains the metadata for the ebook (book title, author, etc.). It also specifies how the images should be scaled. Older ebook readers seem to have problems with jpg files (at least my ancient Kindle).
|
|
|
|
## How to generate the epub file
|
|
|
|
See _exampleSite_. To create your own ebook, you only need to change the metadata in _config.toml_ and replace the _Page-Resources_ in the _content/blog/_ folder with your own content in markdown format.
|
|
In addition, the file _static/OEBPS/cover.jpg_ should be exchanged to your own cover (ideally in portrait format). Do not change file name and format of the cover image.
|
|
|
|
Calling `hugo` in the HUGO root directory of the project creates the demo ebook in the _public_ folder -- but still unpacked. To get the desired epub format, the contents of the _public_ directory must be zipped. The zip archive must have the extension .epub.
|
|
Important: the _mimetype_ file must be the first file in the zip archive. So the call of zip should be like this to create an ebook named _ebook.epub_ which is located in the HUGO root directory:
|
|
|
|
```shell
|
|
cd public
|
|
zip -rX ../ebook.epub mimetype OEBPS META-INF
|
|
```
|
|
To avoid having file garbage in the finished ebook, the _public/_ directory and the zip/epub file should be deleted before re-creating the ebook. For Linux enviroment, a _deploy_ bash script is included in the theme that does all the steps automatically:
|
|
|
|
deploy.sh:
|
|
```shell
|
|
#!/bin/bash
|
|
hugo --cleanDestinationDir
|
|
cd public
|
|
rm -f ../ebook.epub
|
|
zip -rX ../ebook.epub mimetype OEBPS META-INF
|
|
```
|
|
|
|
## Good to know
|
|
|
|
The theme uses [HUGO Page Bundles](https://gohugo.io/content-management/page-bundles/) to manage the **images** automatically. If you want to integrate images into your resources, you can do this with the shortcode
|
|
{{< image src="image name" caption="image caption" >}}
|
|
It is enough to specify a substring of the image name, as long as it is unique. The theme currently supports only jpg and png images. The automatic determination of the mimetype in the manifest of _content.opf_ may need some improvement and can be adjusted in _index.opf_ if needed. In general, all file and folder names should be without special characters, as this can lead to validation errors.
|
|
|
|
Who wants to embed **static images** from the _static/_ folder, must consider three things:
|
|
<br />1. the images must be in the _static/OEBPS/_ directory.
|
|
<br />2. each image file must be listed in the manifest (in the template _index.opf_). The already existing entry for _cover.jpg_ can be used as an example.
|
|
<br />3. the files must be addressed in the content relatively, e.g. ``
|
|
|
|
Epub files with **validation errors** are usually still displayed by the readers. However, it is of course better if the ebook is formally free of errors. The highly recommended ebook management software [Calibre](https://calibre-ebook.com/) offers the possibility to [edit books](https://manual.calibre-ebook.com/de/edit.html) and in this context also to check for errors and debug them. Other validators: [Epub online validator](https://www.ebookit.com/tools/bp/Bo/eBookIt/epub-validator) and [pagina EPUB checker (freeware)](https://www.pagina.gmbh/produkte/epub-checker/).
|
|
|
|
There is a **hack** in the automatic generation of the manifest in _content.opf_ and the table of contents (_single.xhtml_) for which I could not think of a better solution. HUGO would generate paths for relative URLs that look like this, for example: _../OEBPS/chapter/chapter-1.xhtml_. This is theoretically correct, but some ebook readers (and also Calibre) don't handle this well and destroy the chapter order. I therefore transform the path by a subsequent _replace_. I cut _../OEBPS/_ from the path, so that it then looks like this, for example: _chapter/chapter-1.xhtml_.
|
|
|
|
By the way, for manual **internal links** between articles, the automatic relative HUGO paths are working fine. For this, the internal [ref-shortcode](https://gohugo.io/content-management/shortcodes/#ref-and-relref) should be used.
|
|
|
|
There are also two shortcodes that generate the cover page and can be customized if needed: _cover.html_ and _covertext.html_.
|
|
|
|
## Demo ebook
|
|
|
|
[ebook.epub](https://weitblick.org/ebook.epub)
|
|
|
|
## License
|
|
|
|
<a rel="license" href="http://creativecommons.org/licenses/by/4.0/" class="license-button"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png"></a>
|
|
|
|
This Hugo theme is licensed under the [Creative Commons Attribution 4.0 License](LICENSE).
|