Calibre2opds Customization

User Guide Overview Building Localization Customization Issues

This section covers what facilities are available for the user to customize the look-and-feel aspects of calibre2opds. It is most likely to be of interest to those who make heavy use of the HTML versions of the catalogs.

The topics covered are:

Note that this section does not cover options that control the structure of the library such as the sections that should be generated; the rules for splitting by letter; page sizes and so on. This sort of setting is controlled by the options that the users can set within the GUI and is not amenable to change beyond what can be specified there without altering calibre2opds source code.

Reasons for wanting to docustomization can vary widely, but some of the commonest ones will be:

  • To ‘Skin’ Calibre2opds.  By changing some of the stylesheets used by the calibre2opds HTML catalogs it ispossible to supply your won color scheme and font selections.
  • Change page structure.  The HTML catalog pages are generated by using XSLT transforms on the XML file used by the OPDS version of the catalog.  Amending these transformation files can change the way that individual pages are laid out.

There is limited customization that can be done with the look-and feel of OPDS catalogs as the look-and-feel of such catalogs is largely determined by the OPDS client software. The main option that can be changed here is the icons.

The look and feel of the HTML catalogs can be customized far more highly.    You can alter the XSLT template that is used to generate the HTML from the XML catalogs, and you can also provide runtime stylesheets to replace the ones that are shipped as part of calibre2opds.

If users take advantage of this capability it would be nice if they could feed back examples of what they have achieved so that other users can see what is possible.  In fact we would be more than happy to include alternative stylesheets as part of the standard distribtion if anyone produces any interesting ones.

Adding External Links

This is covered here just to point out that it is not necessary to do any of the customization covered in this section of the documentation simply to add new external links to the top level of a calibre2opds generated catalog.   One can do this by setting up entries on the Custom Catalogs tab in the GUI based configuration.

These external links can be one any of:

  • external web pages.  There is no restriction on how such pages are formatted so the content can be anything you like.
  • other catalogs generated by calibre2opds

Calibre2Opds catalog as part of an frameset

One thing that is not strictly a calibre2opds customization feature, but that can affect how a calibre2opds HTML catalog is presented to the user is to embed the calibre2opds catalog into a pane of an HTML iframe.

An example of how one might do this is as follows:

  • Create a file called index.html and put it into the root folder of your calibre library. It could contain contents that look a bit like the following

<title>Using a frameset to embed calibre2opds catalog inside part of the page</title>
<frameset rows=”3″>
<frame src=”my_top.htm”>
<frame src=”_catalog/index.html”>
<frame src=”my_bottom.htm”>
<noframes> Sorry – this browser cannot handle frames <p> click <a src=”_catalog.index.html”>here</a> to get to the first page of the catalog

  • Create the HTML files that you want loaded into the other panes.
    For this example I created my_top.htm containing:

<title>My Top page</title>
<h1>This is content to be displayed above the calibre2odps catalog</h1>

and my_bottom.htm containing

<title>My Top page</title>
<h1>This is content to be displayed below the calibre2odps catalog</h1>

  • If you now loaded the sample index.htm that you have just set up it would look something like the following:

Where should customized files be located

Calibre2opds will search for files that are on its customizable list in the following locations:

  • Calibre2opds configuration folder
    This is the folder where calibre2opds stores user specific settings.
  • Calibre2opds install folder
    This is the folder where the calibre2opds binaries have been installed
  • Built-in
    Calibre2opds has the default versions of all customizable resources built in to the binaries.

To over-ride the built-in version the user must put their customized versions in one of the locations that are checked before the built-in versions are used.  for most cases it would make no difference whether the calibre2opds configuration or install folders are used.  Both are provided simply to allow the user to use whichever is the most convenient.

Note that whenever calibre2opd uses a user supplied resource then this information will be written to the log file.   This allows the user to check that their resource is being picked up by calibre2opds, and also allow calibre2opds support to see if the user is not using the default files (and thus possibly causing an error in calibre2opds).

Files that can be customized

The following specifies which files can be customized to over-ride the calibre2opds built-in versions.

Filename Description
catalog.xsl This is the XSL template that is used to transfrom the XML format catalog pages into the equivalent HTML format pages.
fullentry.xsl  This is the XSL template that is used to transform the XML entry for a Book’s details into the equivalent HTML page.
allbooks.png  The icon used to indicate the ‘allbooks’ catalog entry or catalog section.  Is also used elsewhere when a ‘books’ type icon would be appropriate.
authors.png The icon used to indicate an ‘authors’ catalog entry or catalog section
custom.png The icon used to indicate a ‘custom catalog’ catalog entry
external.png The icon used to indicate an ‘external catalog’ catalog entry
featured.png The icon used to indicate a ‘featured books’ catalog entry
ratings.png The icon used to indicate a ‘ratings’ catalog entry or catalog section
search.png The icon used to indicate a ‘search’ catalog entry
recent.png The icon used to indicate a ‘Recent Books’ catalog entry
series.png The icon used to indicate a ‘series’ catalog entry or catalog section
tags.png The icon used to indicate a ‘tag’ catalog entry or catalog section
catalog.css  The main stylesheet affecting the runtime look-and-feel aspects of the HTML.It is expected that in addition to this stylesheet there will also be either the ‘desktop’ or ‘mobile’ stylesheets active
destop.css A stylesheet that is invoked to provide formatting specific to a desktop browser.  A browser is determined to be a desktop version by testing for the maximim screen resolution that is supported.
mobile.css A stylesheet that is invoked to provide formatting specific to a mobile browser.  A browser is determined to be mobile by testing for the maximim screen resolution that is supported.
functions.js  Provides some common support f8nctions

The master copies of these files (i.e. the ones that are built into calibre2opds) can be obtained from the calibre2opds source code repository. These can be used as the starting point for any customization changes that you might be considering.

CAUTION:  Any time that a new version of calibre2opds is made available then any customization changes that have been made should be reviewed against the new master copies of the files that have been changed. It is possible some change to the calibre2opds features might have meant that changes were made in the master copies of the files that mean that the user custoization files need amending appropriately.

Information about specific file types


Icons are the little images displayed against entries in the different catalog sections.   The images are particular to the section they are being used in, and the type of entry.

Icons are expected to be in .png format and have a resolution of 48×48 pixels.

Note: Customized icon will only be used if the user has specified the use of External icon files in the Dvanced tab of the calibre2opds settings. If this setting is not active then the built-in default icons will always be used.

XSL templates

The XSL templates are used internally by calibre2opds during a generation run to generate the HTML versions of files from their corresponding XML variants.   The XSL templates are used to do a XSLT tranform on the XML files.

One needs to be very careful when changing these files as change that causes an error at runtime will cause a calibre2opds run to fail.

CSS Stylesheets

The CSS stylesheets are only used with HTML catalogs.   They only take effect when the user is attempting to browse a catalog that has been generated by calibre2opds and have no effect on the generation process itself.    They are used to determine many of the the look-and-feel aspects of the HTML catalogs.


The Javascript support functions are used to carry out tasks that can not easily be done diretly in either HTML or CSS type stylesheets

  1. 04/06/2016 at 14:07


    there is no configuration folder in my folderlist. If I generate it and copy the stylesheet in it, the changes of the file don’t change the output.

    How it works?

    thank you

    • itimpi
      05/06/2016 at 05:44

      Not quite sure what you are saying? There is always a configuration folder if you are running the calibre2opds GUI. It’s location can be found by using the entry on the Tools menu to open the configuration folder. It is typically a folder with the name “.calibre2opds” located in your home folder (although you can over-ride the default). Depending on your OS level settings you may need to enable the option to show hidden files/folders. If you mention what OS and File Manager you are using then guidance can be given on how to do this

      BTW: it is easy for comments posted here to get missed. It is typically better to post to the calibre2opds forum, or to the Calibre forum on mobile in the Tools section. Also, this is not the latest documentation – the latest documentation is at

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: