Tetrakern 69fa196094 Renamed constant for consistency

Should probably stop doing that.

2023-02-18 11:04:39 +01:00

48 KiB

Raw Blame History

Installation

This guide is mainly written for people who never had their own WordPress site before and may not have the skills to figure this out by themselves. Feel free to skip ahead. That being said, there are still some parts of interest for veterans in regards to the theme.

Choosing a Host
Installing WordPress
- Configuring WordPress
- Securing WordPress
Legal Considerations
How to Install/Update the Fictioneer Theme
How to Configure the Fictioneer Theme
How to Customize the Fictioneer Theme

Choosing a Host

First, you need to choose a host for your site, the place where your site "lives". This may very well be the hardest part, because bad choices are annoying to fix and cost money. For that matter, you are encouraged to do your own research — Online Media Masters is a good place to start. If you feel completely lost, asking for help is entirely justified.

Your choice will ultimately come down to two schools: managed hosting or not. Managed hosting takes away the burden of having to, well, manage your server. Configuration, maintenance, security, and performance issues are covered by the provider — at a price. For example, on WordPress.com you would need at least the Business plan to use the Fictioneer theme. Non-managed hosting is more affordable and less restrictive, but you need a bit of technical know-how or someone helping you.

If the hosting cost are too much for you alone, there is also the option to share a site with other authors and split the bill. Typically with the administrator holding the contract. Just make sure you trust everyone and write down the obligations and rights of all participants involved. Always prepare for the fallout.

Installing WordPress

The installation process for WordPress is documented on the official site and in many guides only a quick search away. Nowadays, most hosts offer a one-click installation service as well. Note that the latter often comes with pre-installed plugins that you may want to get rid off, especially analytics plugins which tend to violate data privacy laws.

Fictioneer is best used on a fresh install due to its complexity and possible conflicts with existing plugins or customizations. Which does not mean you cannot switch or migrate, but it would be an ordeal. For example, Fictioneer has custom post types for stories and chapters, so you would need to either convert existing posts or upload them anew (which would disassociate all comments). They also have several additional settings, making automatic conversion scripts risky. Depending on how many posts you have, this may take a while.

Configuring WordPress

Everything installed? Head to Settings in the admin panel to configure your site. You can follow a guide, but this should all be fairly obvious. For the purpose of working with the theme, you are most interested in the Reading, Discussion, and Permalinks submenus.

Reading: If you want a static page like in the demo, you can set this here. Of course, you need to create the pages for blog and front page first. Best use the “No Title Page” template. Keep the number of blog posts and feed items somewhere between 8 and 20.
Discussion: Most of this is up to you, but the number and order of comments does not necessarily behave as you would expect. Comments are always nested in the theme, regardless of the checkbox, but the depth is honored and should be anywhere up to 5. Break comments into pages with 8 to 50 comments each, the first page being displayed by default, and newer comments at the top. The theme really does not work well with anything else but you are welcome to try.
- Disallowed Comment Keys: For simple yet reliable comment spam protection, you are advised to use the compiled disallow list by slorp. Just copy the content of the blacklist into the Disallowed Comment Key field. Check your comment trash occasionally as this can lead to false positives. You can search for less restrictive lists too.
Permalinks: You want the permalink structure set to "Post name". As an off-note, whenever some pages do not show up even through they clearly should, come back here and save to update the permalink structure. You would be surprised how many issues that solves.
Open Graph Default Image: Only used when you enable the SEO features and no (known) SEP plugin is running. This image will be shown in search engine results and social media embeds if no other image is provided by individual posts, such as story cover images. Can be set under Appearance > Customize > Site Identity.
Author websites: Technically not a required setting, but authors may want to fill out the website field in their profile. These are added as Open Graph author meta tags used by search engines and social media embeds. If left blank, the generated author page of the site will be used instead, which might be what you want anyway.

Securing WordPress

You can greatly improve your site security and performance by adding policies to the .htaccess file located in the WordPress root directory. Managed hosting plans normally do this for you. Make a backup and add the following lines anywhere before # BEGIN WordPress or after # END WordPress. If something goes wrong wrong, just remove everything again or restore the backup. You can also use a (cache) plugin. This is just the basics, far more is possible but please refer to a proper guide.

Example Policies

# === BEGIN FICTIONEER ===

# Disable directory browsing
Options -Indexes

# Deny POST requests using HTTP 1.0
<IfModule mod_rewrite.c>
  RewriteCond %{THE_REQUEST} ^POST(.*)HTTP/(0\.9|1\.0)$ [NC]
  RewriteRule .* - [F,L]
</IfModule>

# protect wp-config.php
<files wp-config.php>
  order allow,deny
  deny from all
</files>

# Security policies
<ifModule mod_headers.c>
  Header set Strict-Transport-Security "max-age=31536000" env=HTTPS
  Header set X-XSS-Protection "1; mode=block"
  Header set X-Content-Type-Options nosniff
  Header set X-Frame-Options SAMEORIGIN
  Header set Referrer-Policy: strict-origin-when-cross-origin
  Header set Cross-Origin-Opener-Policy "same-origin"
  Header set Cross-Origin-Resource-Policy "same-site"
  Header set Cross-Origin-Embedder-Policy "require-corp; report-to='default'"
  Header unset X-Powered-By
</ifModule>

# Add file types
AddType application/x-font-ttf .ttf
AddType application/x-font-opentype .otf
AddType application/x-font-woff .woff
AddType application/x-font-woff2 .woff2
AddType image/svg+xml .svg

# Enable compression
<IfModule mod_deflate.c>
  AddOutputFilterByType DEFLATE text/plain
  AddOutputFilterByType DEFLATE text/html
  AddOutputFilterByType DEFLATE text/xml
  AddOutputFilterByType DEFLATE text/css
  AddOutputFilterByType DEFLATE application/xml
  AddOutputFilterByType DEFLATE application/xhtml+xml
  AddOutputFilterByType DEFLATE application/rss+xml
  AddOutputFilterByType DEFLATE application/javascript
  AddOutputFilterByType DEFLATE application/x-javascript
  AddOutputFilterByType DEFLATE application/json
  AddOutputFilterByType DEFLATE application/x-font-opentype
  AddOutputFilterByType DEFLATE application/x-font-truetype
  AddOutputFilterByType DEFLATE application/x-font-ttf
  AddOutputFilterByType DEFLATE font/opentype
  AddOutputFilterByType DEFLATE font/otf
  AddOutputFilterByType DEFLATE image/svg+xml
</IfModule>

# Browser cache policies
<IfModule mod_expires.c>
  ExpiresActive on

  # Icons
  ExpiresByType image/x-icon "access plus 1 year"
  ExpiresByType image/vnd.microsoft.icon "access plus 30 days"

  # Images
  ExpiresByType image/jpg "access plus 1 year"
  ExpiresByType image/jpeg "access plus 1 year"
  ExpiresByType image/png "access plus 1 year"
  ExpiresByType image/gif "access plus 1 year"
  ExpiresByType image/webp "access plus 1 year"
  ExpiresByType image/avif "access plus 1 year"
  ExpiresByType image/tiff "access plus 1 year"
  ExpiresByType image/svg+xml "access plus 1 year"

  # Audio/Video
  ExpiresByType audio/ogg "access plus 1 year"
  ExpiresByType audio/mpeg "access plus 1 year"
  ExpiresByType audio/flac "access plus 1 year"
  ExpiresByType audio/mp3 "access plus 1 year"
  ExpiresByType video/ogg "access plus 1 year"
  ExpiresByType video/mp4 "access plus 1 year"
  ExpiresByType video/webm "access plus 1 year"
  ExpiresByType video/mpeg "access plus 1 year"
  ExpiresByType video/quicktime "access plus 1 year"

  # CSS/JS
  ExpiresByType text/css "access plus 1 month"
  ExpiresByType text/javascript "access plus 1 month"
  ExpiresByType application/javascript "access plus 1 month"
  ExpiresByType application/x-javascript "access plus 1 month"

  # Fonts
  ExpiresByType application/x-font-ttf "access plus 1 year"
  ExpiresByType application/x-font-woff "access plus 1 year"
  ExpiresByType application/x-font-woff2 "access plus 1 year"
  ExpiresByType application/x-font-opentype "access plus 1 year"

  # Others
  ExpiresByType application/pdf "access plus 1 day"
  ExpiresByType application/epub+zip "access plus 1 day"
  ExpiresByType application/x-mobipocket-ebook "access plus 1 day"
</IfModule>

# === END FICTIONEER ===

Legal Considerations

There is not much to consider aside from the data privacy issue, which depends on your country of residence and where your host server is located. However, to preempt any legal trouble, you want to assume the strictest laws apply — the GDPR and CCPA. Fictioneer is compliant with both unless you change things, but you also need to add a Privacy Policy. And forget about Google Analytics.

How to Install/Update the Fictioneer Theme

After you have set up your WordPress site, you can install the theme. Since Fictioneer is not available in the official theme library, you need to do this manually. Either by uploading the unpacked theme folder into the /wp-content/themes/ directory via FTP or by uploading the .zip file in the admin panel under Appearance > Themes > Add New > Upload Theme.

When you are done, activate the theme under Appearance > Themes. If you want to use a child theme, which is installed the same way, activate that instead (you need both the main and the child theme). Head to the newly added Fictioneer menu page in the admin sidebar afterwards. Here you need to configure the theme. You may also want to customize the look.

Updating the Theme

Updating the theme works the same as installing the theme. If done in the admin panel, you will be warned that the theme is already installed and given a quick comparison, prompting you to confirm the overwrite. Make sure you still fulfill all the requirements, namely your WordPress and PHP versions. You can find this information in the info tab on the site health screen.

Note that any changes made to the theme files will be undone — which you should not have done in the first place. Always use a child theme for modifications to avoid this issue. Your theme options and Customizer settings are preserved, however.

Optional: Install Plugin Dependencies

Fictioneer relies heavily on one developer plugin, Advanced Custom Fields (ACF). ACF is already bundled into the theme, but you may want to install it separately to stay on the latest version or use it for your own modifications — which should happen in a child theme. You cannot access the bundled version in order to prevent non-developer users from accidentally breaking the theme.

If you decide to install ACF separately, especially if only for the updates, you should consider copying the mu-plugins folder from the theme into the wp-content directory. The included plugin file by Bill Erickson disables ACF on the frontend, which grants a performance boost (the bundled version is disabled by default). You cannot use its functions in that case, however. Beware, changing the ACF fields can break the theme and there is no easy way to revert this!

Optional: Additional Plugins

The plugin ecosystem of WordPress is vast and often confusing. There are plugins for almost everything, in variants, free or premium or "freemium". You often find articles about "must-have" plugins — you are well advised to question those. Too many plugins can slow down your site, open vulnerabilities, or conflict with the theme. Fictioneer is designed as standalone solution and technically works without additional plugins. However, nothing is ever complete, so here are a few recommendations anyway.

Autoptimize: Optimization plugin to speed up your site. Best used for its aggregation and deferment of static resources, such as styles and scripts, solving browser cache issues along the way. The other options are nice if not already covered elsewhere.
Example settings
^{Assume missing options are off, empty, or left to default.}
[JS, CSS & HTML] JavaScript Options:
- - [x] Optimize JavaScript code?
- - [x] Aggregate JS-files?
[JS, CSS & HTML] CSS Options:
- - [x] Optimize CSS Code?
- - [x] Aggregate CSS-files?
- - [x] Generate data: URIs for images?
[JS, CSS & HTML] HTML Options:

If you have no caching or other HTML optimizer, you can tick "Optimize HTML Code?".

[JS, CSS & HTML] Misc Options:
- - [x] Save aggregated script/css as static files?
- - [x] Enable 404 fallbacks?
- - [x] Also optimize for logged in editors/administrators?
- - [x] Disable extra compatibility logic?
[Extra] Extra Auto-Optimizations:
- - [x] Google Fonts: Leave as is
- - [x] Remove emojis
Cloudinary: Great "plug-and-play" image CDN and optimizer with generous free plan. Offloading your images to a content delivery network improves performance and loading times. Also, your images will be properly sized and compressed.
Example settings

Follow the official guide to set up your Cloudinary account and the plugin. You do not need to "register" the CND with other optimization or cache plugins — it will just work.
^{Assume missing options are off, empty, or left to default.}
[General settings] Media Library Sync Settings:
- - [x] Sync method: Auto sync
[General settings] Cloudinary folder path:

To keep things orderly, use a folder name that relates to your site.

[General settings] Storage:
- - [x] Cloudinary and WordPress
[Image settings] Image optimization:
- - [x] Optimize images on my site.
- - [x] Image format: Auto
- - [x] Image quality: Auto
[Lazy loading] Lazy loading:
- - [x] Enable lazy loading
- - [x] Lazy loading threshold: 100px
- - [x] Pre-loader color: You decide!
- - [x] Pre-loader animation: You decide!
- - [x] Placeholder generation type: You decide!
- - [x] DPR settings: Auto (2x)
[Responsive images] Breakpoints:
- - [ ] Enable responsive images (OFF - this increases usage)
Cloudflare: Global content delivery network designed to make your site secure, private, fast, and reliable. Can be used for caching or to enhance a cache plugin further. Unfortunately, the setup is not trivial and you should refer to specific guides or ask for help.
Cache considerations

Cloudflare can be problematic if you want to capitalize on the "Cache Everything" option because without a paid plan, you cannot make exceptions for logged-in users. This means visitors might see personalized content of the first user to populate the cache — not good! Imagine your account details being leaked like that. It also does not easily cooperate with on-site caching solutions.

That being said, the free tier can be persuaded! Ditch the official plugin and install Super Page Cache for Cloudflare instead. Same as before, refer to proper guides. Make sure you have the following settings and be prepared that it might still not work! Test this!
[Plugin: Cache] Don't cache the following dynamic contents:
- - [x] Page 404 (is_404)
- - [x] Feeds (is_feed)
- - [x] Search Pages (is_search)
- - [x] Ajax Requests
- - [x] WP JSON endpoints
[Plugin: Cache] Prevent the following URIs to be cached:
^{Append to defaults. The "account" and "bookshelf" URI fragments may differ on your site (since you can name them).}
/oauth2*
/download-epub*
/account*
/bookshelf*
/*commentcode=*
[Fictioneer: General] Page Assignments:
- - [ ] Account: None (default dashboard profile)
- - [x] Bookshelf: Page with the Bookshelf AJAX template (if you need this)
[Fictioneer: General] Comments:
- - [x] Enable AJAX comment submission
[Fictioneer: General] Security & Privacy:
- - [ ] Block admin panel access for subscribers (OFF)
[Fictioneer: General] Compatibility:
- - [x] Enable cache compatibility mode
- - [x] Enable AJAX nonce deferment
- - [x] Enable AJAX comment form (best performance) ... or ... comment section (best compatibility)
Optional: Install WP Super Cache with the extreme settings. Cannot wrongly cache dynamic pages if there are none!
WPS Limit Login: Protects you from brute-force attacks by limiting the number of login attempts within a certain period of time. The sibling plugin WPS Hide Login moves the whole login page to a new URL, if you want to go one step further.

User authentication

Fictioneer does not have a frontend login form and the login page is not recommended for subscribers, so hiding it serves as additional security layer. Note that the optional OAuth 2.0 authentication system via Discord, Google, etc. is not affected by these plugins.
Sucuri Security - Auditing, Malware Scanner and Hardening: The free version is meant to complement your security posture and comes with hardening, malware scanner, core file integrity checking, event logging, email alerts for important issues, and more.

Notes

There is not much to screw up, but you should refer to a proper guide for your own peace of mind. Because Sucuri has a tendency to be overzealous with scary warnings and until you set up a whitelist, you will see many false positives. Better safe than sorry.

Typical false positives:
error_log-* (potentially any log from any plugin)
.htaccess.bk (generated backup of .htaccess)
UpdraftPlus: One of the most popular and convenient backup plugins. If your host does not offer backups or you want to stay in control, this is a good choice to keep your site safe in the event of a disaster.

Why you want backups

To quote the plugin’s own premonition: "The day may come when you get hacked, when something goes wrong with an update, your server crashes or your hosting company goes bust — without good backups, you lose everything." The free version is perfectly adequate, allowing you to schedule daily backups saved directly to a remote destination of your choice.
EWWW Image Optimizer: An optimization plugin to properly scale, compress, and (optionally) convert your images. Large file sizes reduce your website’s speed and search rank. Redundant if you use an image CDN like Cloudinary, but they can work together.
Example settings

As a matter of fact, you do not need this kind of plugin at all if you pay a modicum of attention to the images you upload. One of the most common yet easy to fix mistakes is uploading over-sized images. Obviously, if your header image is 20 MB, your loading time will go down the drain. Your site will be even faster without the overhead of this plugin if you just pre-optimize your images.
^{Follow the initial setup guide, then head to Settings > EWWW Image Optimizer to review the settings. Also take a look at the official documentation. Assume missing options are off, empty, or left to default.}
Basic settings:
- - [x] Stick with free mode for now
- - [x] Remove Metadata
- - [x] Resize Images: 1920|1920 (3840|2160 if you need 4k images)
- - [ ] Add Missing Dimensions (OFF - this can break the layout)
- - [x] Lazy Load: Improves actual and perceived loading time ...
- - [ ] Lazy Load: Automatic Scaling (OFF)
- - [ ] WebP Conversion (OFF - smaller but unreliable in quality)

Optional: Caching

Technically just another plugin, but one that will make your site significantly faster. Caching saves your posts and pages as static files to be served later instead of rendering them anew on each request. Guests see the same content anyway, so why waste resources? Only logged-in users can have individual content that must not be cached, such as their account profile. Following are a few cache plugins that have proven to work well with the theme. Do this after you configured your site.

Note: Caches require to be purged occasionally, especially after you updated the theme, settings, or plugins. Your site might show outdated pages otherwise. With known plugins, Fictioneer automatically purges post caches when you publish or edit content. Other cache plugins require some custom code or need to be purged manually. Inconvenient, but workable.

Cacheable Query Vars: Most cache plugins automatically exclude pages with query vars (/?foo=bar), because they tend to have dynamic content. However, there are some query vars that can be safely cached if the plugin recognizes them as separate URLs: pg (page), tab, and technically order as well. You may have even more.

Rule of Thumb: Is something missing or misplaced, purge the cache! Chapter order wrong? Purge the cache! Collections outdated? Purge the cache! Page flashing red? That’s right, call an exorcist and purge the cache!

WP Super Cache: Made by Automattic, a main contributor to WordPress the software and owner of WordPress.com the service (do not confuse them), this free cache plugin is a great choice if you want simple and reliable. It is also completely free.
Recommended settings

This is the "safest" advanced setup in the regard that you do not need to mess with server files. Expert mode is a tick faster and not actually complicated, but if the terms ".htaccess" and "mod_rewrite" make you feel queasy, you are perfectly fine with simple mode.
^{Assume missing options are off, empty, or left to default.}
[Advanced] Caching:
- - [x] Enable Caching
[Advanced] Cache Delivery Method:
- - [x] Simple
[Advanced] Miscellaneous:
- - [x] Cache Restrictions: Disable caching for logged in visitors
- - [x] Don’t cache pages with GET parameters.
- - [x] Compress pages so they’re served more quickly to visitors.
- - [x] Cache rebuild. Serve a supercache file to anonymous users while a new file is being generated.
[Advanced] Advanced:
- - [x] Extra homepage checks.
- - [x] Only refresh current page when comments made.
- - [x] List the newest cached pages on this page.
[Advanced] Expiry Time & Garbage Collection:
- - [x] Cache Timeout: 7200
- - [x] Timer: 600
[Advanced] Accepted Filenames & Rejected URIs:
- - [x] Feeds
- - [x] Search Pages
[Advanced] Rejected URL Strings:
^{The "account" and "bookshelf" URI fragments may differ on your site (since you can name them).}
/oauth2
/download-epub
/account
/bookshelf
Extreme settings

This is the most "aggressive" setup meant to carry membership sites on cheaper hosts, e.g. sites with many simultaneous requests by logged-in visitors who would normally not be served supercached files. Generating individual pages in large numbers within a short amount of time can overwhelm a server, leading to timeout errors. An issue you are unlikely to encounter as long as you do not have thousands of daily visitors. But in that case, just extend the recommended settings with the following ones.
^{Assume missing options are off, empty, or left to default.}
[Advanced] Miscellaneous:
- - [x] Cache Restrictions: Enable caching for all visitors
- - [x] Make known users anonymous so they’re served supercached static files.
Great, now your site is broken for logged-in users! Or rather, they are treated like guests and cannot see their personal content or post comments anymore. To resolve this, head to the Fictioneer general settings and activate the following options. Clear the cache afterwards. Yes, the admin bar is now gone. Yes, you can still get into the admin with the …/wp-admin link. No, password protected posts no longer work.

[General] Page Assignments:
- - [ ] Account: None (default dashboard profile)
- - [x] Bookshelf: Page with the Bookshelf AJAX template (if you need this)
[General] Security & Privacy:
- - [ ] Block admin panel access for subscribers (OFF)
[General] Compatibility:
- - [x] Enable public cache compatibility mode
- - [x] Enable AJAX nonce deferment
- - [x] Enable AJAX user authentication
- - [x] Enable AJAX comment form (best performance) ... or ... comment section (best compatibility)
W3 Total Cache: Comprehensive suite of caching and performance features with great compatibility regardless of host. But a rather involved setup and requires a subscription to make the most of it. Please refer to a guide for installation.

Cache exceptions

As long as you only serve cached pages to unauthenticated users, you can hardly do wrong. To make absolutely sure everything works, please add the following exceptions under Performance > Page Cache.

[Page Cache] Never cache the following pages:
^{The "account" and "bookshelf" URI fragments may differ on your site (since you can name them).}
/oauth2*
/download-epub*
/account*
/bookshelf*
LiteSpeed Cache: The most powerful of the listed cache plugins and also completely free — if you can get it running. As server-side cache, your host must support LiteSpeed, which is usually a prominent selling point so you would know.
Example settings

LiteSpeed Cache offers you far more than what is covered here, so please refer to more comprehensive guides if you want to take advantage of that. However, combined with the other recommended plugins, you can do without.
^{Assume missing options are off, empty, or left to default.}
[1 - Cache] Cache Control Settings:
- - [x] Enable Cache
- - [ ] Cache Logged-in Users (OFF)
- - [ ] Cache Commenters (OFF)
- - [x] Cache REST API
- - [x] Cache Login Page
- - [x] Cache favicon.ico
- - [x] Cache PHP Resources
- - [ ] Cache Mobile (OFF)
[2 - TTL] TTL:
- - [x] Default Public Cache TTL: 28800
- - [x] Default Private Cache TTL: 1800
- - [x] Default Front Page TTL: 604800
- - [x] Default Feed TTL: 604800
- - [x] Default REST TTL: 28800
[3 - Purge] Purge Settings:
- - [x] Purge All On Upgrade
- - [x] Auto Purge Rules For Publish/Update: All pages
- - [ ] Serve Stale (OFF)
[4 - Excludes] Do Not Cache URIs:
^{The "account" and "bookshelf" URI fragments may differ on your site (since you can name them).}
/oauth2
/download-epub
/account
/bookshelf

[4 - Excludes] Do Not Cache Query Strings:
commentcode

[4 - Excludes] Do Not Cache Roles:
- - [x] Administrator
- - [x] Moderator
- - [x] Editor
- - [x] Author
[5 - ESI] ESI Settings:
- - [x] Enable ESI
- - [x] Cache Admin Bar
- - [x] Cache Comment Form
[5 - ESI] ESI Nonces:
oauth_nonce
fictioneer_nonce
fictioneer-ajax-nonce

[5 - ESI] Vary Group:
- - [x] Administrator: 99
- - [x] Moderator: 50
- - [x] Editor: 40
- - [x] Author: 30
- - [x] Contributor: 20
- - [x] Subscriber: 0
[7 - Browser] Browser Cache Settings:
- - [x] Browser Cache
- - [x] Browser Cache TTL: 31557600

Warning: SEO Plugins

While search engine optimization plugins such as Yoast and AIOSEO are usually the way to go, they are not recommended here. Fictioneer already ships with a search engine optimization — not perfect, but tailored to the purpose. Third party plugins do not understand the theme, never mind web fictions. They assume everything to be topic-based articles or products, leading to faulty results unless you teach them and that requires custom code. They also lock essential features behind a subscription that Fictioneer provides for free.

And just to take a step back here and be real: SEO is important. Certainly. Unfortunately. But if you actually try to optimize your prose for keywords density, word complexity, sentence and paragraph length, or any other statistical insanity to beseech the great algorithm, you have a poison in your mind.

How to Configure the Fictioneer Theme

General Tab

Most of the theme’s configuration is found here, the options being largely self-explanatory. Please note that you will probably not need all the features available, such as Checkmarks or Follows. These are for sites with many authors or stories; publishing a weekly serial is better off saving the server resources. Some additional explanations:

System Email Address/Name: Used for no-reply transactional emails, such as comment reply notifications.
Contact Form Receivers: Submitted contact forms are sent to those email addresses. One per line.
Add consent wrappers to embedded content: Required to be GDPR compliant if you use embeds.
Page Assignments: Only set what you actually need. Used for breadcrumbs and menu items.
Enable OAuth 2.0 authentication: Allows visitors to register, but be aware of the privacy implications!
Enable AJAX comment form/section: If you have trouble with caching. Try the form first to save resources.
Enable AJAX nonce deferment: Nonces can conflict with caching. Use this as last resort to bypass the cache.
Disable theme comment *: If you want to use different comments. Disables most of the other comment options as well.

Connections Tab

Anything that connects with external service providers goes here, such as the Client ID and Secret for OAuth 2.0 applications. Please refer to respective tutorials on how to set them up and always, always keep those credentials confidential. If you enter a Discord webhook here, notifications about new comments will be sent directly into a channel on your server (leave free if you do not want that). This should be a hidden moderation channel because it will receive excerpts of private comments.

Phrases Tab

Allows for some minor translations and changes, such as the cookie notice banner or comment reply notification email. More customization can be achieved with the theme’s translation filter. But if you want to translate the theme into a new language, you will need to include the proper translation files or use a plugin.

ePUBs Tab

Lists all generated ePUBs with statistics, download links, and options to delete them. File names are equal to the story’s post_name, which is the slug inside the permalink and not the title. They are cleaned of any special characters and are also used to query associated stories. If you change the permalink, they will no longer match and a new ePUB will be generated, leaving the old one orphaned. This is not terrible but takes up space.

Failed ePUBs: Indicated by an empty "download" file. The generation of ePUBs can fail due to several circumstances, such as missing writing permissions along the path of wp-content/uploads/epubs or non-conform content in the story or chapters. Unfortunately, ePUBs are rather picky regarding allowed HTML and while the converter tries to sanitize the content, this is not fail-proof. Alternatively, you can just upload a file yourself instead of relying on the converter, not limited to the ePUB format.

SEO Tab

Only available if you enable the SEO features and no (known) SEO plugin is running. Lists all generated Open Graph meta data and schemas used by search engines and social media embeds, created and cached when a post is first visited until modified or purged. Whether these services actually display the offered data is entirely up to them. You cannot force Google to show your custom description, for example. After all, you could write anything in there. This tab is mostly informative, but you have the options to purge the cached meta data or schemas if that should become necessary.

Tools Tab

A collection of actions to add, update, revert, fix, or purge certain items. For example, you can add a proper moderator role that WordPress somehow lacks and fix the permissions of other roles — or revert these changes. Everything is thoroughly explained. But the only action you will most likely need more than once is Purge Story Data Caches, which should be done whenever you change chapter or story settings.

Log

A log of administrative actions performed which concern the theme.

How to Customize the Fictioneer Theme

There are two ways to customize the theme. The obvious one is the Customizer of WordPress under Appearance > Customize. Here you can upload a header image and logo, set a site title, change the color scheme, and modify the layout to some extend. The interface and live preview make this straightforward. If the color options are too demanding (and they are), you may want to stick to the hue, saturation, and lightness sliders. Also consult the many guides about WordPress customization.

The second way is to directly modify the templates, styles, and scripts. This is indefinitely more powerful but requires some developer skills — and you can easily break your site. The theme’s files can be modified under Appearance > Theme File Editor, although you should never actually do this. Always create a child theme because any code changes you make, regardless of quality, will be overwritten again when you update the theme.

Move the Title/Logo

In order to move the title or logo, you need a bit of custom CSS. This can be added directly under Customize > Additional CSS. Depending on whether you have a logo or not, you will have one of the following HTML/CSS combinations (and then some, but this is the relevant part).

What you are interested in are the position, transform, and/or text-align properties. transform changes the origin point (kinda) of the element, which is normally the top-left corner, so that it can be better offset. The text-align only works on the title. If you overwrite those values, you can move the element or text around. If you want to offset from the right or bottom, you need to add top: unset; or left: unset; or both. Make sure the title or logo still fits on mobile. See references for position, transform, and text-align.

HTML CSS

HTML	CSS
`<header class="header hide-on-fullscreen"> <div class="header__title"> <h1 class="header__title-heading"> <a href="#" class="header__title-link" rel="home">Title</a> </h1> <div class="header__title-tagline">Tagline</div> </div> </header>`	`.header__title { position: relative; top: 40%; /* ... / transform: translateY(-50%); / ... */ }`
`<header class="header hide-on-fullscreen"> <div class="header__logo"> <a href="#" class="custom-logo-link" rel="home"> <img width="x" height="y" src="#"> </a> </div> </header>`	`.header__logo { position: absolute; top: 50%; left: 50%; transform: translate3d(-50%, -50%, 0); /* ... */ }`

<header class="header hide-on-fullscreen">
  <div class="header__title">
    <h1 class="header__title-heading">
      <a href="#" class="header__title-link" rel="home">Title</a>
    </h1>
    <div class="header__title-tagline">Tagline</div>
  </div>
</header>

.header__title {
  position: relative;
  top: 40%;
  /* ... */
  transform: translateY(-50%);
  /* ... */
}

<header class="header hide-on-fullscreen">
  <div class="header__logo">
    <a href="#" class="custom-logo-link" rel="home">
      <img width="x" height="y" src="#">
    </a>
  </div>
</header>

.header__logo {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate3d(-50%, -50%, 0);
  /* ... */
}

Minimum/Maximum Values

The minimum and maximum values found in the Customizer are used to calculate clamps, which are responsible for the dynamic scaling of the site. Viewport refers to the actual screen dimensions, again with a minimum (fixed) and maximum (site width). Everything is interpolated between those values. Use the built-in responsive display modes at the bottom of the Customizer to review your changes. Do not forget to check "Use custom layout properties" or your settings will be ignored.

Menus

Fictioneer comes with two menu locations, Navigation and Footer Menu, which are precisely where you would expect. You can read up on how to create and add menus in the official documentation. The only thing of note here are the special CSS classes you can assign to menu items for certain effects (whitespace-separated). Make sure to enable the additional menu properties under Screen Options at the top.

On desktop, submenus are rendered as dropdown. On mobile, the Navigation only shows the top level menu items in a scrollable track, but the mobile menu is an unfolded list of all items if not specifically excluded with optional CSS classes.

not-in-mobile-menu: As you can guess, this will hide the menu item in the mobile menu. However, submenu items will still be shown, so you can use this to hide superfluous dropdown parents.
static-menu-item: For menu items without link. Changes the cursor and cannot be selected by keyboard (subitems can).

Constants

Some options are not available in the settings because tempering with them can break the theme or result in unexpected behavior. Those options defined via constants in the function.php. If you want to change them, you need a child child theme. Just override them in the child theme’s own function.php, but only if you know what you are doing!

define( 'CONSTANT_NAME', value );

Constant	Type	Explanation
CHILD_VERSION	string\|boolean	Version number of the child theme. Default `false`.
CHILD_NAME	string\|boolean	Name of the child theme. Default `false`.
FICTIONEER_OAUTH_ENDPOINT	string	URI slug to call the OAuth script. Default `'oauth2'`.
FICTIONEER_EPUB_ENDPOINT	string	URI slug to call the ePUB script. Default `'download-epub'`.
FICTIONEER_LOGOUT_ENDPOINT	string	URI slug to call the logout script. Default `'fictioneer-logout'`.
FICTIONEER_PRIMARY_FONT_CSS	string	CSS name of the primary font. Default `'Open Sans'`.
FICTIONEER_PRIMARY_FONT_NAME	string	Display name of the primary font. Default `'Open Sans'`.
FICTIONEER_COMMENTCODE_TTL	int	How long guests can see their private/unapproved comments in seconds. Default `600`.
FICTIONEER_AJAX_TTL	int	How long to cache certain AJAX requests locally in milliseconds. Default `60000`.
FICTIONEER_AJAX_LOGIN_TTL	int	How long to cache AJAX authentications locally in milliseconds. Default `15000`.
FICTIONEER_AJAX_POST_DEBOUNCE_RATE	int	How long to debounce AJAX requests of the same type milliseconds. Default `700`.
FICTIONEER_AUTHOR_KEYWORD_SEARCH_LIMIT	int	Maximum number of authors in the advanced search suggestions. Default `100`.
FICTIONEER_UPDATE_CHECK_TIMEOUT	int	Timeout between checks for theme updates in seconds. Default `3600`.
FICTIONEER_CACHE_PURGE_ASSIST	boolean	Whether to call the cache purge assist function on post updates. Default `true`.
FICTIONEER_RELATIONSHIP_PURGE_ASSIST	boolean	Whether to purge related post caches. Default `true`.
FICTIONEER_CHAPTER_LIST_TRANSIENTS	boolean	Whether to cache chapter lists on story pages as Transients. Default `true`.
FICTIONEER_SHOW_SEARCH_IN_MENUS	boolean	Whether to show search page links in menus. Default `true`.
FICTIONEER_THEME_SWITCH	boolean	Whether to the theme switch in child themes (back to base). Default `true`.
FICTIONEER_ATTACHMENT_PAGES	boolean	Whether to enable pages for attachments (no theme templates). Default `false`.
FICTIONEER_SHOW_OAUTH_HASHES	boolean	Whether to show OAuth ID hashes in user profiles (admin only). Default `false`.
FICTIONEER_DISALLOWED_KEY_NOTICE	boolean	Whether to show feedback for rejected comment content. Default `true`.
FICTIONEER_FILTER_STORY_CHAPTERS	boolean	Whether to filter selectable chapters by assigned story. Default `true`.
FICTIONEER_COLLAPSE_COMMENT_FORM	boolean	Whether hide comment form inputs until the textarea is clicked. Default `true`.

48 KiB Raw Blame History Unescape Escape

Installation

Table of Contents

Choosing a Host

Installing WordPress

Configuring WordPress

Securing WordPress

Legal Considerations

How to Install/Update the Fictioneer Theme

Updating the Theme

Optional: Install Plugin Dependencies

Optional: Additional Plugins

[JS, CSS & HTML] JavaScript Options:

[JS, CSS & HTML] CSS Options:

[JS, CSS & HTML] HTML Options:

[JS, CSS & HTML] Misc Options:

[Extra] Extra Auto-Optimizations:

[General settings] Media Library Sync Settings:

[General settings] Cloudinary folder path:

[General settings] Storage:

[Image settings] Image optimization:

[Lazy loading] Lazy loading:

[Responsive images] Breakpoints:

[Plugin: Cache] Don't cache the following dynamic contents:

[Plugin: Cache] Prevent the following URIs to be cached:

[Fictioneer: General] Page Assignments:

[Fictioneer: General] Comments:

[Fictioneer: General] Security & Privacy:

[Fictioneer: General] Compatibility:

Typical false positives:

Basic settings:

Optional: Caching

[Advanced] Caching:

[Advanced] Cache Delivery Method:

[Advanced] Miscellaneous:

[Advanced] Advanced:

[Advanced] Expiry Time & Garbage Collection:

[Advanced] Accepted Filenames & Rejected URIs:

[Advanced] Rejected URL Strings:

[Advanced] Miscellaneous:

[General] Page Assignments:

[General] Security & Privacy:

[General] Compatibility:

[Page Cache] Never cache the following pages:

[1 - Cache] Cache Control Settings:

[2 - TTL] TTL:

[3 - Purge] Purge Settings:

[4 - Excludes] Do Not Cache URIs:

[4 - Excludes] Do Not Cache Query Strings:

[4 - Excludes] Do Not Cache Roles:

[5 - ESI] ESI Settings:

[5 - ESI] ESI Nonces:

[5 - ESI] Vary Group:

[7 - Browser] Browser Cache Settings: