Skip to content

FAQs

Jump to bottom Edit New page
Jim Miller edited this page Apr 12, 2024 · 44 revisions

FanFicFare FAQs

Please add site XYZ to FanFicFare?

I rarely add new sites myself anymore for several reasons.

Most, if not all, of the new sites requested these days are new fiction or translated fiction instead of fanfiction. Newer, more interactive sites are frequently more difficult to implement. And mostly, I ran out of ambition for adding sites I don't read myself years ago.

These days new sites are mostly added by other people who want to read them. Which is kinda how it should be with an open source project, IMO.

This issue comment gives a (very) brief guide on getting started adding a site.

How do I get the latest released version of FanFicFare?

Calibre Plugin:

Once you have Calibre installed and running, inside Calibre, you can go to Preferences -> Get plug-ins to enhance Calibre.

Calibre automatically notifies when an updated plugin is available, but this can be manually checked by following the above steps and choosing Check for updated plugins.

FYI, anytime there's a new version of a plugin, there's a delay before it shows up on the official list of plugins that Calibre watches.

Or you can download it from the MobileRead forum for FanFicFare and then go to Preferences -> Plug-ins -> Load plug-in from file. It's not uncommon for test versions to be posted in the forum before they are released for general update.

Command Line Interface(CLI):

The CLI is now distributed as a pip package. The most up to date instructions should be posted on the Home wiki page.

We also have a user group for all versions.

How do I get the latest test version of FanFicFare?

FanFicFare is generally released only once a month, but there are often many test versions (especially of the plugin) posted between releases. Note that these are test versions--sometimes they are buggy.

Calibre Plugin:

You can download the latest test version from the MobileRead forum for FanFicFare and then in Calibre, go to Preferences -> Plug-ins -> Load plug-in from file.

Command Line Interface(CLI):

The CLI test version is posted to testpypi. To install it, use: pip install --extra-index-url https://testpypi.python.org/pypi --upgrade FanFicFare

Why am I having errors downloading from fanfiction.net? / Why am I getting 'Cloudflare' errors downloading from fanfiction.net?

As of ~Dec 2020, the site fanfiction.net has started using the Cloudflare service for protection from automated attackers.

Unfortunately, the distinction between 'automated attacker' and 'automated download tool' (such as FanFicFare) is a fine one.

For most users, Cloudflare blocks more aggressively than can be easily automated around. That's not surprising--it is their intention, after all.

There are two features in FanFicFare to side-step the issue of Cloudflare.

The first is the Browser Cache Feature, which, once configured, will look in your browser's cache for story chapter pages. See the Browser Cache Feature wiki page for further details.

The second is the Proxy Feature, which, once you have setup and run a separate proxy process and configured FanFicFare to use it, will run your requests through a proxy that has some ability to by-pass Cloudflare. See the Proxy Features wiki page for further details.

I still strongly recommend using email notifications for updates rather than using FanFicFare update to check for new chapters on lots of books.

I've followed all the instructions in Browser Cache Feature and it isn't working / I'm getting errors--help?

Browser caches can sometimes become (mildly) corrupted and/or FFF's cache reading code is less than perfect. I suspect the answer is probably both.

Your best bet in such a case is to clear your browser cache before trying again with all steps, including visiting the pages in browser.

If that doesn't help, some users have reported success manually deleting the contents of their browser cache directory; then the browser should recreate it entirely. I'd quit the browser and back up first before trying again.

I'm having SSL/TLS certificate errors--help?

SSL(/TLS, indicated by URLs starting with https:) is becoming more and more common. But SSL certificates don't last forever.

SSL verification is a complicated process involving more than one certificate at more than one level, all of which eventually expire.

When the site's SSL certificate expires, you will also see an error visiting the site with your browser. All you can do in that case is wait for the site administrators to renew their cert. If you have a way to contact the site administrators, you could also notify them about the issue.

You can also get an error when any of the chain of 'signing' certificates expire.

Starting with FanFicFare v4: FanFicFare CLI now depends on the certifi package for certificates while FanFicFare plugin bundles its own copy of certifi in the plugin zip.

(It was a deliberate decision not to use Calibre's bundled certificates because FanFicFare still supports significantly older versions of Calibre. For example, the certificate bundle in Calibre 2.85.1 is from Jan 2017.)

Also starting with FanFicFare v4, you can set use_ssl_unverified_context:true in personal.ini for specific sites to by-pass SSL verification without impacting other sites or processes in both CLI and Plugin. This is still a security risk, but now it is a much more minor one.

Why rename the project? What was wrong with FanFictionDownLoader(FFDL)?

This project was first called fanficdownloader and later FanFictionDownLoader(FFDL). Neither name was especially distinctive--There's also a completely unrelated project out there called fanfictiondownloader.net that had the name first.

Then in March 2015, Google announced that code.google.com was going to be shutdown and all projects would have to move to other hosting.

If we were going to have to move anyway, that seemed a good time to also change the name to something a bit more unique.

What is FanFicFare supposted to mean?

'FanFic' is obvious. While FanFicFare does support a few sites that host original works, the majority is fanfiction.

The 'Fare' part refers to the 'food' definition of 'fare':

a range of food, especially of a particular type

synonyms: food, meals, sustenance, nourishment, nutriment, foodstuffs, provender, eatables, provisions

How do I report problems or ask questions?

If you haven't found an answer here, then there are a couple ways to get in touch with us.

If you are a FanFicFare Calibre Plugin user, the plugin forum on MobileRead is the most active discussion.

We also have a Google user group for all versions.

Why shouldn't I just select my entire library and use FanFicFare plugin to check for updates?

I do not recommend using FanFicFare that way. Checking for updates on dozens (or hundreds or thousands) of stories at once causes excessive traffic on the source site. fanfiction.net and archiveofourown.org in particular, have been known to block people's IP address or refuse requests if they generate too much traffic.

Instead, I highly recommend that you 'follow' stories and use the sites' email notifications to inform you about updates and then update those specific stories.

I also recommend using Update EPUB, not Overwrite, unless you have reason to believe that a particular story has changes in previous chapters. Even for Mobi file users, I recommend downloading to EPUB and converting.

I repeat, doing mass updates is not recommended.

How do I setup FanFicFare to read my story update notification emails for me?

First, you have to go into FanFicFare config on the new Email Settings tab and set your IMAP server, user, and folder. The folder must already exist. Use INBOX for your... inbox. Or the name of the label for a Gmail label. Your email account must allow IMAPS (IMAP with SSL). (I've only tested with Gmail--a Google Apps account, actually).

You can choose whether you want FanFicFare to automatically mark those emails read. It will only mark read emails it found story URLs in.

Then there will appear a new FanFicFare menu option for Get Story URLs from Email. Errors are not handled terribly gracefully, nor is there a 'busy' indicator while it's working.

If you didn't save it in config, FanFicFare asks for your email password. If you checked Remember password for session in config, it will only ask the first time you use it each session. The password is discarded when you quit calibre or when you switch libraries, since different libraries have different settings.

WARNING There's very little data protection in Python--once you've given FanFicFare your password, any plugin or other part of Calibre could potentially read it if it knows to look for it. Alternatively, if you use 2FA on Gmail you can use Google App Passwords.

Can FanFicFare download a story containing images?

Yes. You can choose whether to include the images or not, but only in the CLI and Calibre FanFicFare plugin versions and only in EPUB and HTML formats.

The following question has more details.

A book I downloaded has images (online) but they are not there in the book

The Calibre FanFicFare plugin can turn on images with the Include images in EPUBs checkbox in configuration.

Also, there are additional image options which can be set up in personal.ini. This applies to both the Plugin and CLI. See [configuring personal.ini] for how to achieve this.

Note: The include_images and related options are only available in EPUB and HTML output formats in Plugin and CLI. Images cannot be included in MOBI or TXT. I recommend that you use EPUB output in Calibre and convert to get images in other formats.

Does FanFicFare do any processing to included images?

By default, all images saved to EPUB are converted to jpeg to save size. Further, you can set what size to scale the images down to fit in. Aspect ratio is preserved and images are never scaled up, only down.

The default size, image_max_size: 580, 725 (width, height) is for my Nook STR. You can change it in your personal.ini. (If people tell me what appropriate sizes are for other book readers, I'll include them in the comments.)

You can also add grayscale_images: true to your personal.ini have them converted to grayscale for additional (minor) space savings.

By default, any transparency in the images will be filled with background_color. You can add remove_transparency: false in your personal.ini if you want keep the transparency.

The Calibre plugin includes an image processing library.

However, the CLI can only do image processing if the PIL or Pillow image processing packages are installed.

You can also explicitly disable all image processing by adding no_image_processing:true to your personal.ini.

Can FanFicFare download and set the downloaded books cover?

Yes, but only for EPUB and only in the CLI and Calibre FanFicFare plugin versions.

The plugin has an option on the Basic Configuration tab, Update Cover when Updating Metadata. When checked, the Calibre cover image will be updated every time the other Calibre metadata is updated (assuming EPUB). If there is a cover image in the EPUB, it will be used. If not, Calibre will generate the usual from EPUB format type cover, usually showing the title page.

There are three places cover images can come from.

The first is an explicit cover image from the source site. Not all sites have specific cover images.

Second, the downloader can use the first image it finds in the story with the include_images and make_firstimage_cover options in personal.ini. Then, if a story contains an image, FanFicFare will set that as the book's cover. If keep_summary_html is also true, it can come from the summary.

Third, you can set a specific image that will be used if one of the other two isn't found.

Code:

[www.adastrafanfic.com:epub]
default_cover_image:file:///C:/Users/username/Desktop/nook/images/icon.png

[www.fictionalley.org:epub]
default_cover_image:http://www.somesite.com/someimage.gif

If you want images inside the EPUB, but never want an image cover, you can use:

Code:

never_make_cover:true

You can also use the Generate Cover plugin to set a cover image. FanFicFare plugin can be configured to automatically call Generate Cover if no cover image was found.

How can I keep FanFicFare from asking me if I am an adult all the time?

Some sites require the user to confirm they are adult for adult content. You can, in your personal.ini, set is_adult:true in the [defaults] (or in specific site sections) and it will always assume you are an adult.

In the commandline version, this should go in your personal.ini, not defaults.ini.

Code:

[defaults]
is_adult:true

Can FanFicFare remember my username and password for different sites?

Some sites require login (or login for some rated stories). FanFicFare can prompt you each time, or you can save it in personal.ini. Each site's username and password have to be saved in the section for that site.

In the commandline version, this should go in your personal.ini, not defaults.ini.

Code:

[www.ficwad.com]
username:YourName
password:yourpassword

[archiveofourown.org]
username:YourAO3Name
password:yourao3password

FanFicFare does not put any effort into securing these settings. It's recommended that you don't save usernames or passwords here that are sensitive--for example, if you are also an author and post your stories under that user.

How can I edit stories after they are downloaded?

If you don't intend to ever update the book using FanFicFare, you can do whatever you want to it.

FanFicFare can only update EPUB format files. Other formats, if you attempt to 'update' with FanFicFare after editing will overwrite your changes.

If you do plan to update an EPUB again using FanFicFare, you should use a tool that doesn't change the file layout inside the EPUB. Updating an EPUB use the previous chapter texts from your edited EPUB, but the title page, TOC, etc will be regenerated.

Calibre's Edit Book feature does a good job, but the way FanFicFare creates Anthology books (using EpubMerge) can be confusing because it creates directory structured EPUBs. To see the full path file names in Edit Book, go into Edit Book's Preferences, Main Window, and enable 'Show full file paths in the Files Browser'.

Another approach is:

Use Calibre to convert the eBook to RTF format and then edit in your word processor of choice. (TXT is also a conversion option but loses any formatting and the links (url) to the story and author).

Important: Make sure that while editing, that you do not remove the link to the story in the story's title. Also, conversion to RTF loses the Title and Author metadata - these will need to be restored otherwise the next step will not match the revised story and will create a new book in Calibre.

Copy the modified story back into Calibre (or use Calibre's add books option), delete the original eBook, and convert the newly imported story to your desired eBook format.

How do I add a URL to an Calibre existing book?

FanFicFare will search inside the existing EPUB for a URL embedded in the book (in the dc: source tag).

Alternately, find the URL for the story, and do an Add from URL(s) with Update Always or Update Calibre metadata only. There is a plugin called 'Search The Internet' which is very useful for this. The easiest option is probably to search using Google with this plugin.

FanFicFare is now able to search for the story (or stories) with the URLs provided, and will match the existing story by title and author and update everything.

If you already know the URL, you can edit the 'Ids:' field in Calibre metadata and add a 'url:' identifier. Eg: url:https://www.fanfiction.net/s/1111111/1/

How do I backup FanFicFare settings?

For CLI, back up your personal.ini file as you would any other file. You're already backing up your home directory and fanfiction library, right?

For Calibre plugin, FanFicFare keeps your settings in the Calibre library database--you backup your Calibre libraries, right?

Details of how to backup Calibre libraries are given in Calibre's User Guide - http://manual.calibre-ebook.com/faq.html#how-do-i-backup-calibre

Why does the book Summary have strange HTML in it?

By default, FanFicFare keeps the summary HTML from the site. Some sites include image tags, by keeping the summary in HTML, that image can be found and used as a cover.

You can disable it by adding the parameter keep_summary_html:false to your personal.ini. In [defaults] to effect all sites, or in the section for a specific site.

How do I set the font size for a book's Summary/Description in Calibre?

This is not under FanFicFare's control, but the Summary (Description) displayed in Calibre can be set as follows:

The general answer is in Calibre's User Manual Customizing Calibre Overriding icons, templates, etcetera.

First, find your Calibre config dir by doing Preferences->Change Calibre Behaviour->Advanced->Miscellaneous->Open Calibre configuration directory. Go into resources, and make a directory named 'templates'.

Then, copy C:\Program Files (x86)\Calibre2\resources\templates\book\_details.css (or equivalent) to the templates directory you just made.

You may need to edit the preferences first to unset the read only attribute.

Edit your new book_details.css file and add the font attribute to the .comment tag:

.comment {
font-size: 12px;
}

... or whatever size you like.

How do I update the metadata for an existing book in Calibre that wasn't downloaded with FanFicFare?

You need to find the URL of the story (book) and add it to the book's listing in Calibre.

See How do I add a URL to an existing book? for how to do this.

Then you can use FanFicFare's 'Update Calibre Metadata Only' feature. Update the book, but open 'Download Options' and change 'If Story Already Exists?' to 'Update Calibre Metadata Only'.

How do I control what is sent to the Tags fields in Calibre

What metadata (category, genre, status, characters, ships, etc) gets included in the Calibre tags is controlled by the personal.ini option include_subject_tags. (The name is historical because EPUB 'tags' are placed in <dc:subject> tags.)

Note that there is an option in FanFicFare's Plugin configuration to keep existing tags (or not) and this should be checked or unchecked as appropriate. This becomes relevant when updating an existing story.

How do I change what a particular metadata value appears as in FanFicFare?

For example, when AO3 lists Captain America (Movies), you might want that to appear as just Captain America.

The answer is the replace_metadata option in personal.ini. It uses regular expressions to change metadata values.

## Note that there has to be a space at the beginning of each line in
## the replace_metadata list.
replace_metadata:
 category=>Captain America \(Movies\)=>Captain America

See the ReplaceMetadata page for more details.

How can I limit or exclude the metadata values that FanFicFare keeps?

There's a whole page, InExcludeMetadataFeature, to explain the Include/Exclude metadata feature.

I get an error saying the address is invalid. What should it be?

This often happens because the author's page is selected by mistake. Ensure the story's index page or one of the individual chapter pages is selected.

The page of Supportedsites shows examples of valid URL forms for each site.

I installed FanFicFare but can't see it in Calibre

First, try re-starting Calibre.

If FanFicFare is still not visible, then it is possible the step to choose where to display FanFicFare was missed, or an option was chosen which doesn't apply.

If it disappears when you have a device plugged in, you probably don't have FanFicFare configured to appear on 'The main toolbar when a device is connected' bar.

Go to Preferences->Toolbar (in the Interface group) and choose the location where you want to see FanFicFare. Add from the list on the left and then move up or down in the list on the right to set FanFicFare where desired.

Typically users put FanFicFare on both 'The main toolbar' and 'The main toolbar when a device is connected'.

I love FanFicFare - how can I support on-going development?

FanFicFare is completely free.

The best way you can support us is by joining the plugin forum or the user group and taking part.

We also welcome new code and documentation contributions.

I used to be able to download from a website but it no longer works

Fanfiction websites regularly modify their websites as they work to improve their service. To be fair, it is good that they respond to user requests. They are also often driven to make changes when the underlying software that hosts their website is changed.

Check the user forum to check if this has already been reported, and then notify us if it hasn't - see Where do I find the discussion forum for FanFicFare?.

Another possibility is that you've changed your 'skin' preference on that site. Many sites off several different appearances, or 'skins'. Generally, FanFicFare is only coded to work with the default skin. Try setting your skin back to the default. See Why can't I use a different skin on my favorite site?

Why can't I use a different skin on my favorite site?

Many sites support more than one 'skin' that changes the appearance of the site. On many sites the changes are minor, different images and colors, but the same structure and labels. Sometimes, however, the skin changes the layout of the site's pages enough that FanFicFare cannot parse it using the same code.

For most sites, FanFicFare only supports the default skin. Supporting additional skins would add a lot more coding and testing--comparable to the effort needed to add a new site, depending on the skin.

('Default' is defined as the skin that appears to users who aren't logged in, or the skin that was first assigned to the developer's user when it was created.)

Is it possible to automatically accept the 'Proceed with updating your library' dialog in Calibre?

The 'proceed with updating?' dialog can't be skipped without risking corrupting your library DB. The official way to enforce sequential updates in Calibre is with that 'proceed with updating?' dialog.

It has to do with limitations of the library DB. It wasn't designed with concurrent access in mind, so there isn't appropriate locking, transaction support, etc.

Suppose you'd kicked off an FanFicFare download and at the same moment it finished and was updating the DB, you were also updating the DB from some other plugin or action. The DB cache can be corrupted in that case.

So until the Calibre DB gets concurrent access, we're stuck with it.

Is it possible to show the completion status of a downloaded story in Calibre?

Yes, FanFicFare downloads story status from most sites, that may be in progress and the status (In-Progress or Completed) can be made visible in Calibre.

Metadata 'Status' is included in FanFicFare. By default, it shows up on the story's title page and is either In-Progress or Completed (or similar according to each website's settings).

FanFicFare also comes default configured to put In-Progress or Completed on each story as a tag. Assuming, of course, that you have the plugin update metadata.

In Calibre, you can create a custom column of one of the text types or a Yes/No column, and then configure FanFicFare to update it automatically from the Custom Columns tag of FanFicFare config.

In steps:

  1. Go to Calibre Preferences->Add your own columns (in the Interface group), and add a column (Text type or Yes/No).

  2. You will be prompted to re-start Calibre.

  3. After re-start, check the display and drag the new column to where desired,

  4. Open FanFicFare's configuration and go to the 'Custom Columns' tab - the new field should be listed. Select a value to populate this field with from the drop down list, presumably 'Status:Completed'.

  5. Next time you update a book, it's Status will be populated in that column.

Note that this status can also be displayed on a book's cover if using the Generate Cover plugin.

Where is this personal.ini I keep reading about?

The name personal.ini is a reference to the file in the CLI, the earliest version of FanFicFare.

Calibre Plugin: Click FanFicFare -> Configure Plugin -> personal.ini tab -> Edit personal.ini button.

Command Line Interface(CLI): ./personal.ini or ~/.fanficfare/personal.ini. For backward compatibility to the earlier FanFictionDownLoader(FFDL), also ~/.fanficdownloader/personal.ini. You'll have to create the directory and initial file.

Is there guidance on settings for the personal.ini (configuration)?

The primary place where all the personal.ini options are documented is the defaults.ini file.

For CLI users, default.ini is installed with the package files, but that location varies depending on your OS and setup. You can always view the defaults.ini file online.

For calibre plugin users, there's a button on the personal.ini Configuration tab that will display the plugin's defaults.ini. (Note that the plugin defaults.ini is not identical to the one used by the CLI.)

My settings in personal.ini disappeared after updating the Calibre plugin - what happened?

Every library in Calibre has its own settings and the FanFicFare configuration is therefore unique to each library. If you have more than one library, this might be what happened. If you only have one library and you still believe you have lost your FanFicFare configuration, then do let us know.

Note: The first time you open the FanFicFare plugin config in a new library, it will copy the settings from the previously open library - if there was one.

Why doesn't the color / font / special formatting from the story appear in the eBook FanFicFare produces?

FanFicFare, by default, strips out style attributes, ignores site/story specific CSS and converts some HTML (like <i> and <b> tags) to other forms. It does these for three reasons:

  1. EPUB (the primary output format) only supports a subset of (X)HTML.
  2. eInk eBook Readers (the assumed target device) are gray scale and have additional limitations.
  3. To make FanFicFare output from any site and author more similar.

You can get part of the story formatting back, depending on how it was implemented in the story.

You can add add_to_keep_html_attrs:,style to your personal.ini to enable HTML like <span style="color:green;"> to be preserved. You can put under section [defaults] for all stories on all sites, or under the section for specific sites or stories.

On the other hand, if the story uses CSS styles, such as <span class="red">, you would need to add those styles to FanFicFare's output_css. For example (and it's only an example, not a panacea):

[storiesonline.net]
add_to_output_css:
 blockquote p{font-family:Courier, monospace;}
 .right,.r{text-align:right;}
 .in{text-indent:2em;}
 .center,.c{text-align:center;}
 .red{color:red;}
 .blue{color:navy;}
 .lblue{color:blue;}
 .green{color:green;}
 .i{font-style:italic;}
 .b{font-weight:bold;}
 .bi{font-weight:bold;font-style:italic;}

Why don't my CSS formatting changes in personal.ini work?

This is often caused by something minor. To quote from http://www.w3.org/TR/REC-CSS2/syndata.html#q4:

All CSS style sheets are case-insensitive, except for parts that are not under the control of CSS. For example, the case-sensitivity of values of the HTML attributes 'id' and 'class', of font names, and of URLs lies outside the scope of this specification. Note in particular that element names are case-insensitive in HTML, but case-sensitive in XML. (eg If your CSS uses <p> and the story contains <P>, then the formatting will not work).

In CSS2, identifiers (including element names, classes, and IDs in selectors) can contain only the characters [A-Za-z0-9] and ISO 10646 characters 161 and higher, plus the hyphen (-); they cannot start with a hyphen or a digit. They can also contain escaped characters and any ISO 10646 character as a numeric code (see next item). For instance, the identifier 'B&W?' may be written as 'B&W?' or 'B\26 W\3F'.

For more information, read http://www.w3.org/TR/REC-CSS2/syndata.html#q4

One common issue is that a story may not be using your CSS at all because you tried to apply everything to <p> tags and the story doesn't contain any <p> tags at all - all vertical spacing is done with <br /> tags. Applying the formatting to <div> instead of <p> might help. Some stories always have a <div> tag around the chapter content, but not all sites do. <body> is the only tag you're guaranteed will be there for all sites.

Unfortunately, CSS for exact appearance is always going to be an iffy proposition because the HTML entered by different authors varies wildly.

That's why the FanFicFare strips out so much of it. For example, some stories use <span> with style attributes for italics. The downloader strips out all the style attributes.

This means you may need to experiment with different settings until you find one that works.

What are Reading Lists in Calibre and how do I use them with FanFicFare?

The Reading List Calibre plugin allows users to keep lists of books, for example to track of which books they would like to read next, and in which order. You can have multiple lists per library.

The Reading List plugin has also allows you to synchronise list(s) to a device either manually or automatically when it is connected.

Once you've created Reading Lists for sending to your devices, you can configure FanFicFare to automatically add new/updated stories to those lists.

Reading Lists can also update custom columns automatically. Using that with a Metadata Plugboard, you can put a notation in the title of new books to read when they're sent to your device.

As a convenience, FanFicFare offers a menu option to remove stories from the to read lists after you've read them and optionally add read stories to the send to device lists again.

This is an illustrated example of how it could be used.

Please let us know if you have a better way to do this.

What is a Calibre Metadata plugboard?

Plugboards allow you to use eBook metadata to change the metadata fields inside eBooks as they are sent to your devices. This can be used to to control how eBooks appear in an eBook reader.

For example, including the Series and tags in the 'title' field so that you can see and search for series and tags in your eBook reader.

For a detailed explanation, visit the MobileRead Wiki for Calibre or the plugboards forum on MobileRead.

What is ApplicationError: 5?

This is a rather vague error that the Web Serice application gives for a variety of reasons.

This often indicates the application had problems connecting to the fan fiction website.

FanFicFare tries several times, with longer waits between attempts, when there's a failure to retrieve story data, but sometimes it still fails. Sometimes, the only answer is to try again later.

Where do I find the discussion forum for FanFicFare?

If you use the Calibre plugin, it's best to use the plugin forum. It's not uncommon for beta versions of FanFicFare to be available for testing on the plugin forum before it's released for the CLI.

The general discussion user group is available for all users, but particularly those not interested in Calibre specifics.

Which fan fiction websites are supported by FanFicFare?

There's a separate Supportedsites page dedicated to listing the supported, suggested and rejected sites.

Why doesn't FanFicFare support LiveJournal and many other popular fan fiction websites?

Downloading stories from LiveJournal and several other fan fiction websites is theoretically possible, but very difficult. Generally, the problem is picking the story out of the rest of the text. Some sites are just too complex - complex layout, embedded comments from readers, etc.

See Which fan fiction websites are supported by FanFicFare? for more information.

Is there a GUI version of FanFicFare?

Right now, the Calibre plugin is the only GUI version.

There might be a stand alone GUI version in future, but there's nothing on the drawing board yet.

How can I run the CLI version without installing Python?

It's impossible without some sort of Python available, but if you already have Calibre installed, you can install the FanFicFare plugin and then run the FanFicFare CLI:

calibre-debug -e downloader.py -- [options to downloader]

Although, if you have Calibre, I'd recommend the FanFicFare Calibre plugin.

Why doesn't the MOBI output show chapters markers on the progress bar in Kindle or include images?

FanFicFare's MOBI output is less than ideal--it doesn't include chapter markers, nor can it include images. These are complex problems because MOBI is much more difficult to work with than epub.

Given the fact that Kindle has moved on to a newer format (AZW3), it's unlikely FanFicFare's MOBI support is ever going to improve. Unless, of course, somebody who wants it gets involved as a developer and improves it.

Right now, our best suggestion is to download as EPUB and then convert to MOBI.

The Calibre plugin has an option to automatically convert new downloads or updates using Calibre's extremely good Convert feature.

Why does my Kindle never finish indexing some FanFicFare books? / Why do some FanFicFare books break search on my Kindle?

Some sites / stories have poor HTML that can cause problems with Kindle's word indexing system.

As discussed above, FanFicFare's MOBI output is less than stellar.

This post by Dylan Tomorrow on the FanFicFare PI forum describes the problem and one solution for it using kindlegen.

Why doesn't FanFicFare support other output types, like PDF?

Lack of interest by the developers, primarily. However, if someone comes forward and wants to write the code to add support for new output formats, we'd be happy to work with them.

Why didn't FanFicFare collect Series for story X?

Not all sites have series. And sometimes a site will add series after the FanFicFare code was written.

But not all sites that have series use them for series--some instead use them for reading lists or favorites lists. There are a few sites that can collect series, but are configured by default not to. You can check defaults.ini for the collect_series parameter in the site section your story is from. If it's set to false, you can add it to personal.ini to enable it.

If you've found a site that uses series, but FanFicFare doesn't collect it, let us know through the user forums - see Where do I find the discussion forum for FanFicFare?

What is an 'adapter'? What is an 'eFiction Base adapter'?

Internally, the code for a specific site in FanFicFare is called an adapter and collected together into and adapter file.

Many Fanfic sites use the eFiction story management system for hosting stories. This is a very flexible system that can be customized in many ways. That customization makes it harder for us because the metadata used and the HTML to show it can change significantly.

Back in Aug 2014, developer doe noticed that most eFiction sites don't customize the 'print' page versions nearly as much. doe contributed what we call the eFiction Base adapter code. This allows an eFiction site to be supported with much less work if it hasn't customed the print page very much.

As of Apr 2015, there are 8 sites that are supported using the eFiction Base adapter:

  • devianthearts.com
  • fannation.shades-of-moonlight.com
  • fhsarchive.com
  • libraryofmoria.com
  • lotrfanfiction.com
  • tgstorytime.com
  • thehookupzone.net
  • themaplebookshelf

Unfortunately, while a great idea for more easily adding new sites, the eFiction Base code is a bit more limited in the metadata it collects. For example, while it collects 'Series', it doesn't know what number a story is in a series. For Calibre users who collect the stories of a series in order, it probably doesn't matter. But it might for a CLI user, for example.

Is there a way to add a tag 'Oneshot' to 1 chapter completed stories?

This seems to work:

# defaults so is affects everything, but can be overridden by
# more specific sections.
[defaults]
# 'add_to_' concats on to existing param, thus the leading comma
add_to_extra_valid_entries:,oneshot
# oneshot is a copy of status because status itself isn't a list.
include_in_oneshot:status
# add oneshot to the tags that are included in epub & calibre.
add_to_include_subject_tags:,oneshot

# Change oneshot to ['Completed'] to ['Completed','Oneshot'] only when
# numChapters is exactly 1.
# with ',' instead of '\,' it would be ['Completed'] to
# ['Completed,Oneshot']--one string instead of two.
add_to_replace_metadata:
 oneshot=>Completed=>Completed\,Oneshot&&numChapters=>^1$

How do I fix the error 'utf8' codec can't decode byte 0xXX in position XX: invalid start byte?

At least one user has reported receiving this error due to their software firewall blocking the outgoing connections from FanFicFare. Disabling the firewall or white listing the calibre and calibre background processes cleared it.

How do I download a list of all of an author's stories or a user's Favorites list on fanfiction.net?

FanFicFare has a feature "Get Story URLs from Web Page" (Plugin, see CLI options list for equivalent) that you can use to get lists of URLs from author pages or favorite pages.

For fanfiction.net specifically however, it's a little more complicated. Because they use javascript on the author page to switch between author's stories vs author's favorites, you have to use the mobile URLs instead. Change the www to m. Examples:

How do I use a percent sign in personal.ini?

Percent signs are special in INI and need to be 'escaped'. To do this, double it ('%%' rather than '%'). The second one will be ignored.

This is mostly used with randomly generated passwords and size percentages in output_css. Eg:

password:ifhn%%ER4
# ...
add_to_output_css: .full { width: 100%%; }
Add a custom footer
Add a custom sidebar
Clone this wiki locally