This documentation is about the Fictioneer theme. If you need help with WordPress in general, take a look at the [official documentation](https://wordpress.org/support/category/basic-usage/) or search the Internet for one of the many tutorials. For the installation, look [here](INSTALLATION.md) first and then come back once you are done.
You may want to set up a front page like the demo site or make it a landing page in case of a single-story site. Both can be achieved with blocks, shortcodes, and some custom CSS or HTML if necessary. Obviously, you can always add a custom page template in your child theme if you have the skill for that, which can look like pretty much anything.
Under **Settings > Reading**, set **Your homepage displays** to "A static page" and assign your **Homepage** and **Posts page**. Create new pages if you did not already, give them sensible names. For your **Homepage**, choose the "No Title Page" or "Story Page" page template.
The "Story Page" template is for single-story sites and has more shortcode options, plus meta fields for the story ID and header. Alternatively, you can choose the "Story Mirror" template, which will mirror the story post of the specified story ID. If you want to treat your Homepage as singular page and not show the actual story post, you can set a redirect in the story to your base address (enable the advanced meta fields in the settings).
For simplicity, here is the copied content of the [demo homepage](https://fictioneer-theme.com/) and [demo story page](https://fictioneer-theme.com/story-page/). Put that into the code editor view and adjust it as needed (the IDs will be obviously different for you). When you switch back to the visual editor, everything should be properly formatted as blocks.
<p>Nightmares and hallucinations have plagued Heather Morell all her life, relics of schizophrenia and childhood bereavement.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>Until she meets Raine and Evelyn, that is — self-proclaimed bodyguard and bad-tempered magician — and learns she’s not insane at all. The spirits and monsters she sees are all too real, the god-thing in her nightmares is teaching her how to surpass human limits, and her twin sister who supposedly never existed could still be alive, somewhere Outside, beyond the walls of reality.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>Heather plunges into a world of eldritch magic and fanatic cultists, trying to stay alive, stay sane, and deal with her own blossoming attraction to dangerous women. But being ‘In The Know’ isn’t all terror and danger. Sometimes the monsters wear nice dresses and stick around for afternoon tea. Sometimes you find you have more in common with them than you think. Perhaps this is Heather’s chance to be something more than the defeated husk she’d grown up as, to find real friendship and meaning among things like herself – and perhaps, out there on the rim of the possible, to bring her twin sister back from the dead.</p>
<p>Katalepsis is an Ancient Greek word which means ‘comprehension’, or perhaps more accurately, ‘insight’.<br><br>Katalepsis is a serial web novel about cosmic horror and human fragility, urban fantasy and lesbian romance, set in a sleepy English university town.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>New chapters are currently posted once a week, on Saturdays.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>If you just finished the official ebook or audiobook of Volume I, the story resumes <ahref="https://katalepsis.net/2019/09/07/no-nook-of-english-ground-5-1/">here</a>.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>If you are enjoying the story and want to see more, please consider <ahref="https://www.patreon.com/hazelyoung">donating via the Patreon page!</a></p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>Front cover art by <ahref="https://noctilia.artstation.com/">Noctilia</a>, header art by <ahref="https://www.deviantart.com/yivels">Yivel</a>.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p><em>Disclaimer/warning: Please note that Katalepsis is intended for a mature audience. This is a horror story, after all. For more information, see the FAQ <ahref="https://katalepsis.net/faq/">here</a>.</em></p>
The demo story page uses some [custom page CSS](#extra-meta-fields) to change the page background. You can also do this globally under **Appearance > Customize**, but this is one way to modify individual pages.
The theme has two menu locations: Navigation and Footer Menu. You can create and assign menus under **Appearance > Menu**; they do not exist by default. For detailed instructions, refer to the [WordPress Codex Menu User Guide](https://codex.wordpress.org/WordPress_Menu_User_Guide). Note that the mobile menu will unfold nested menus, while the mobile navigation bar will display only the top-level items, depending on the mobile style you have chosen. The footer menu is not configured for nested items. Too many top-level items may look bad or break the layout.
**Optional CSS classes:**
*`not-in-mobile-menu` - Prevents menu items from showing up in the mobile menu.
*`static-menu-item` - Makes the menu item unclickable; good for submenu headers.
*`only-admins|-editors|-moderators|-authors` - Restricts the menu item to certain roles.
*`hide-if-logged-in` - Hides the menu item if the user is logged in.
*`hide-if-logged-out` - Hides the menu item if the user is logged out.
In addition to the Taxonomies page template, you can also add a submenu for each taxonomy in the main navigation. This works for categories, tags, genres, fandoms, characters, and warnings. To do this, add a custom link as a menu item with `#` as the link, then assign it **one** of the following trigger CSS classes (check the screen options if you cannot see the input). This should work on all levels, but it is recommended to keep it at the top level. The menu link and submenu will only be visible on desktop viewports.
Due to its size, the taxonomy submenu can cause layout issues depending on where the parent item is placed. There are too many cases to consider individually, so here is some CSS for you to modify as needed. Add this CSS to the [Custom CSS section](https://wordpress.org/documentation/article/customizer/#additional-css) in the Customizer, and only keep the properties you actually change.
You can enable the optional sidebar under **Appearance > Customize > Layout**, choosing either left or right alignment along with other options. Typically, this also requires some manual adjustments to the layout. Increasing the site width is recommended to accommodate the new column; 1036px is a good start for a 256px wide sidebar (leaving 700px content space). Note that the sidebar will only show up once you add widgets to it.
Enabling the sidebar also reduces the default page padding, which can be overridden further down with custom layout properties. If space becomes an issue, consider reducing the horizontal page padding to zero and turning off the page background for an open site appearance.
Stories are added under **Stories > Add New**. Required fields are the short description, status, and age rating. You should be thorough with the setup, especially the taxonomies if you have more than a few stories on your site, because they can be searched for. Just avoid adding excessive lists of tags. Also note that stories are not supposed to be used like chapters, for example as oneshot, because they lack all chapter features, including comments.
The layout will adjust itself if certain fields are left empty, such as the cover image or taxonomies. With a blank title, the date and time will be used instead. Cover images are displayed with an aspect ratio of 2:3, although the image itself does not need to follow these dimensions as it will be cropped from the center.
The share, feed, and action buttons are displayed depending on your theme settings. The Blog tab lists 160 characters long excerpts of the latest posts associated with the story via category. Up to four custom pages can be added as extra tabs, with any content, which requires them to have the short name field. Chapters assigned to the story can be added and sorted in the editor, but chapter groups and icons are assigned in the chapters.
**Subscribe:** Opens a popup menu with links to any support campaigns (Patreon, Ko-fi, and SubscribeStar) as well as the RSS aggregator services [Feedly](https://feedly.com/) and [Inoreader](https://www.inoreader.com/). There is no default email subscription system.
**Follow & Read Later:** These buttons belong to the optional Follows and Reminders features, allowing logged-in subscribers to better track stories. This is mainly for sites that host a large number of stories.
Story cards are more compact story displays meant for browsing, collapsed even further on small viewports. Instead of the content, only the *first paragraph* of the short description will be shown. Make sure to write something appealing, it may be the only chance your story gets to catch attention. Tags are normally not rendered to save space, but you can change that in the settings.
Story cards are used in the Stories [page template](https://wordpress.org/support/article/pages/#page-templates), collections, search, and featured lists in posts.
<sup>**(A)** for Advanced: These meta fields are hidden unless you check the "Enable advanced meta fields" option under **Fictioneer > General > Compatibility.** Most sites just do not need these.</sup>
A manually uploaded eBook will always supersede an automatically generated ePUB on the site, as this is a deliberate action. Which also means you need to keep it up-to-date yourself and there are no download statistics. If you want the generated ePUB, you need to fill the Preface content for the story, which should contain copyrights and disclaimers. Because once a file is on the Internet, it will stay on the Internet. Make sure everything is legally sound before that.
**Supported:** Epubs only support paragraphs, headings, lists, tables, blockquotes, pullquotes, images, spacers, and custom HTML at your own peril. Anything else will be filtered out, such as videos.
**Sensitive Content:** You can mark sensitive content in chapters and provide an alternative, which users can choose from. Generated ePUBs always use the sensitive (uncensored) content, not the alternative if provided.
> This is a work of fiction. Names, characters, businesses, events and incidents are the products of the author’s imagination. Any resemblance to actual persons, living or dead, or actual events is purely coincidental.
> This is a work of fan fiction and not written for profit. Names, characters, businesses, events and incidents are the products of the author’s imagination. Any resemblance to actual persons, living or dead, or actual events is purely coincidental. Any trademarked characters and elements used belong to their respective copyright holders, who bear no responsibility for this work.
> Original Content Copyright © `AUTHOR`. All rights reserved.
## Chapters
Chapters are added under **Chapters > Add New**. The only required field is the chapter icon, which is pre-selected by default (book). But you need to select a story if you want the chapter to show up in said story’s chapter list. This is not limited to your own stories, so you can publish guest chapters for others, although the owners still need to list them. As with stories, you should be thorough with the setup.
The display of a chapter listed on a story page is controlled from within the chapter. The icon, warning, and chapter group are assigned here, although icons can be disabled globally or per story. Make sure to spell the chapter group correctly each time, because there is no hand-holding and different names result in different groups. Groups can also cause chapters to be reordered if not in sequence, but the order within a group is still derived from the story’s chapter list. You need at least two groups for groups to be displayed and ungrouped chapters will be collected under "Unassigned".
**Checkmarks:** These icon buttons belong to the optional Checkmarks feature, allowing logged-in subscribers to mark chapters and stories as read. This is mainly for sites that host a large number of stories.
The fullscreen toggle is not available on iOS, which at the time of writing does not support the fullscreen API. The navigation buttons are derived from the story’s chapter list. You can open the paragraph tools by clicking on a paragraph; Bookmarks, Suggestions, and Text-to-Speech (TTS) must be enabled in the settings first. Bookmarks are per chapter and linked to a paragraph, the color is only a gimmick and does _not_ indicate you have more than one.
**Formatting Modal:** Opened with the Formatting button. Allows readers to customize how chapters are displayed, including: site brightness, site saturation, site width, font size, letter spacing, line height, paragraph spacing, font saturation, font family, font color, and font weight as well as toggles for text indent, text justify, light/dark mode, paragraph tools, author notes, comments, and sensitive content.
This notice appears above the title if you add a chapter warning, not to be confused with the content warning taxonomy. The warning is also shown in the chapter list of the story. Keep it short, there is not much space. You can change the color and add an additional explanation as well. The toggle allows to hide any sensitive content marked with the `sensitive-content` CSS class and show an alternative marked with `sensitive-alternative` if provided.
### Meta Fields
| Field | Type | Explanation
| :-- | :-: | :--
| Story | Select | The story the chapter belongs to. Required if you want it listed.
| Card/List Title | String | Alternative title meant to be suitable for cards and lists with little space.
| Group | String | Chapter group assignment. Mind the spelling and order of chapters.
<sup>**(A)** for Advanced: These meta fields are hidden unless you check the "Enable advanced meta fields" option under **Fictioneer > General > Compatibility.** Most sites just do not need these.</sup>
As you can take away from the meta fields, there are several optional chapter titles and title-related fields. This can be confusing, so here is where and how these fields are actually used. Blank fields are obviously not rendered.
* **Small Cards (Shortcodes):** List Title *or* Title
* **Large Chapter Cards (List Templates):** Title *and* List Title (on mobile)
* **Large Story Cards (List Templates):** List Title *or* Title
* **Chapter Index (Popup/Mobile):** List Title *or* Title
* **Chapter Lists (Story/Shortcode):** Prefix + Title
Must be enabled in the settings and is started from the paragraph tools. Makes use of the free [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API) that all modern browsers support, which can be wonky at times but produces surprisingly decent results. Primarily meant as accessibility feature for the reading-impaired. Absolutely _not_ fail-proof and depends on the browser and operating system; additional permissions may be necessary on the playback device (this is outside your control).
**Supported:** Only first level children of the content container are read, and only paragraphs and headings. If you want tables, quotes, and more to be read, add the desired output as paragraph with the `hidden` CSS class.
**Note:** Browsers have only one instance of this engine. That means if you have another one running in a different tab, perhaps a different site altogether, they will interfere with each other. You can even control the output of other sites.
Collections are added under **Collections > Add New**. Required fields are the short description and items featured in the collection, which may include posts, pages, stories, chapters, recommendations, and even other collections. The purpose is to group different items with a common context, such as sequels or stories set in a shared universe.
| Taxonomies (Various) | List | Genres, fandoms, characters, warnings, tags, and categories (include story name).
| Collection Cover Image | Image | Cropped to an aspect ration of 2:3 from the center.
## Recommendations
Recommendations are added under **Recommendations > Add New**. Required fields are the author of the recommended story, primary URL, general URLs, and "one sentence" abbreviation as description on small cards. Large cards use the normal excerpt. Recommendations are meant to be personal promotions of great stories by your fellow authors and to shine light on hidden gems.
| Support | Text | Special formatted list of links to support the author, one per line.
| Taxonomies (Various) | List | Genres, fandoms, characters, warnings, tags, and categories.
| Recommendation Cover Image | Image | Cropped to an aspect ration of 2:3 from the center.
### Example Sentences
Think of the sentence as elevator pitch, something you can tell within a few seconds to get the point across. Skip the details, hint at the plot, describe the concept — the story has all the time to tell itself later. Because more often than not, readers will only glimpse at a story while browsing. Recommendations are not prominently featured on _your_ site, after all.
Pages work the same as always in WordPress, just with some additional fields and template options. [Change the template](https://wordpress.org/support/article/pages/#page-templates) in the settings sidebar. You can assign these template pages to certain tasks under **Fictioneer > General > Page Assignments**.
You may want to only list selected stories, for example those belonging to a certain category. While there isn’t a convenient meta field for this due to the numerous possible parameters, you can customize the output using the [fictioneer_filter_stories_query_args](FILTERS.md#apply_filters-fictioneer_filter_stories_query_args-query_args-post_id-) filter in a child theme. Ensure that the name of your filter function is unique, or else.
These fields and options are available in most post types, which does not mean they make sense everywhere. Some require certain feature to be enabled and set up, such as the Patreon integration.
Metadata for search engine results, schema graphs, and social media embeds. If left blank, defaults will be derived from the post content. You can use `{{title}}`, `{{site}}`, and `{{excerpt}}` as placeholders. Titles should not exceed 70 characters but this is not enforced. The Open Graph image is either set manually (click on the box) or defaults to the post thumbnail, parent thumbnail, or site default in that order. Whether these services actually display the offered data is entirely up to them. After all, you could write anything in there.
A collection of optional support links: Patreon, Ko-fi, SubscribeStar, PayPal, and a generic donation link for anything else. They are displayed in several places, such as under each chapter unless disabled. You can set different links per chapter and story, defaulting to the parent or author profile if left empty.
You can add additional CSS classes to paragraphs and other blocks for extra styles and functions. Just select a block in the editor and scroll down to the **Advanced** section in the [block settings](https://wordpress.org/support/article/working-with-blocks/#block-settings) panel. This can be your own or classes provided by the theme, which are highlighted in the editor as shown in the image.
You can also apply additional classes to single words or phrases. Switch to the code editor in the options menu (the three dots in the top-right corner) and wrap the desired part like `<span class="spoiler">word</span>`. Make sure to properly close the tag and do not span over multiple blocks unless you know what you are doing, in which case you would not need this guide.
The custom HTML block is the best way to add special elements to the content, such as status screens in [litRPGs](https://en.wikipedia.org/wiki/LitRPG). The preview option in the editor helps if you are just dabbling. This can be further enhanced with inline styles or custom CSS classes, but you need to account for the dark/light mode and generated ePUBs as well. The following example is baked into the theme and sure to work, just change the content or remove what you do not need.
You can grant logged-in users access to password-protected content via Patreon membership, either by selected tiers or pledge thresholds or both. See [installation guide](INSTALLATION.md#patreon-integration) for more details. Prices are stored in **cents** (¢100 to $1), independent of your campaign currency. You still need to set a password for the post and stories **do not** pass down gates to chapters due to technical reasons.
**Caching:** If you use a cache plugin, make sure that password-protected posts are not cached or this might not work properly. The LiteSpeed Cache, WP Super Cache, and W3 Total Cache plugins should be fine, but anything else might need additional configuration.
**Free Tier:** If you want to gate content behind the free tier (only following, not paying), you can just add the tier alongside the others. If that is too inconvenient because you got too many tiers, you can use the pledge threshold to include any tier equal to or above a certain amount in cents (e.g. 300 for $3.00), either globally or post by post.
You can grant logged-in users access to password-protected content by unlocking specific posts. Just open the admin profile page of the user, search for the posts you want to unlock, add them and save. Chapters inherit the unlock of the story. Roles other than administrators require both the **Edit Users** and **Unlock Posts** capabilities to assign unlocked posts to users, which can be assigned in the role manager.
**Caching:** If you use a cache plugin, make sure that password-protected posts are not cached or this might not work properly. The LiteSpeed Cache, WP Super Cache, and W3 Total Cache plugins should be fine, but anything else might need additional configuration.
**Patreon Gate:** Post unlocks are normally independent of Patreon, but you can gate them behind a global pledge threshold in cents to limit the feature to paying patrons only. This is in addition to any other Patreon gates.
[Shortcodes](https://wordpress.org/support/article/shortcode-block/) are bracket-enclosed keywords placed within the content that WordPress automatically interprets into code, adding features or objects without the need for programming. This should be done inside a _shortcode_ block, although it would work outside too. Since most elements created by shortcodes have no margins, the _spacer_ block can be a good addition before and/or after.
**Attention!** Shortcode queries are cached as [Transients](https://developer.wordpress.org/apis/transients/) to reduce their performance impact, especially if you have more than one per page. This means they will not update immediately (except if you have a cache plugin active, which disabled this feature). By default, the Transients expire after 300 seconds (5 minutes), which can be changed via the `FICTIONEER_SHORTCODE_TRANSIENT_EXPIRATION` constant in a child theme. You can disable the Transients by setting the constant to `-1`.
Renders the action row of the specified story. All buttons and links will work as if on the story post, aside from the sharing modal which always refers to the current page. This only works on pages with the "Story Page" template set and is intended to create a single-story-centric front page.
* **story_id:** The ID of the story.
* **class:** Additional CSS classes, separated by whitespace.
* **follow:** Whether to render the Follow button (if enabled). Default `true`.
* **reminder:** Whether to render the Reminder button (if enabled). Default `true`.
* **subscribe:** Whether to render the Subscribe button (if enabled). Default `true`.
* **download:** Whether to render the ePUB/eBook download button (if enabled). Default `true`.
* **rss:** Whether to render the RSS link (if enabled). Default `true`.
* **share:** Whether to render the Share modal button (if enabled). Default `true`.
Renders the chapters, groups, and tabs of the specified story. It will look just as if on the story post. This only works on pages with the "Story Page" template set and is intended to create a single-story-centric front page.
* **story_id:** The ID of the story.
* **class:** Additional CSS classes, separated by whitespace.
* **tabs:** Whether to render the tabs (if any). Default `false`.
* **blog:** Whether to render the blog tab. Default `false`.
* **pages:** Whether to render the custom page tabs. Default `false`.
* **scheduled:** Whether to render the scheduled chapter note. Default `false`.
Renders the button to load the collective comments made on chapters in the story. Not to be confused with the comments you can make on the page, which are completely separate. This only works on pages with the "Story Page" template set and is intended to create a single-story-centric front page.
* **story_id:** The ID of the story.
* **class:** Additional CSS classes, separated by whitespace.
* **header:** Whether to render the heading with count. Default `true`.
Renders a single datum from the specified story, such as the **word count** or **age rating**. You can use this to show your own self-updating statistics. Just omit the shortcode block and write it directly into the text.
* **data:** The requested data, singular. Choose between `word_count`, `chapter_count`, `status`, `icon` (status), `age_rating`, `rating_letter`, `comment_count`, `id`, `date`, `time`, `datetime`, `categories`, `tags`, `genres`, `fandoms`, `characters`, and `warnings`.
* **story_id:** The ID of the story. Defaults to current post ID.
* **format:** Special formatting for some data. Mostly used for counts, use `short` or `raw`.
* **date_format:** Formatting string for the date. Defaults to your WordPress settings.
* **time_format:** Formatting string for the time. Defaults to your WordPress settings.
* **separator:** String between list items, such as tags. Defaults to `", "` (comma + whitespace).
* **tag:** Wrapping HTML tag. Defaults to `span`.
* **class:** Additional CSS classes, separated by whitespace.
* **inner_class:** Additional CSS classes for nested elements (if any), separated by whitespace.
* **style:** Inline CSS style applied to the wrapping element.
* **inner_style:** Inline CSS style applied to nested elements (if any).
```
The example story Katalepsis has [fictioneer_story_data story_id="13" data="chapter_count"] chapters featured on this site, containing a total of [fictioneer_story_data story_id="13" data="word_count"] words.
```
```
You can format the word count with "raw" ([fictioneer_story_data story_id="13" data="word_count" format="raw"]) or "short" ([fictioneer_story_data story_id="13" data="word_count" format="short"]).
```
```
Katalepsis has the following tags: [fictioneer_story_data story_id="13" data="tags" separator=" | " inner_style="color: var(--red-500);"].
```
### Subscribe Button Shortcode
Renders a subscribe button for the specified story.
* **story_id:** The ID of the story the button is for.
* **class:** Additional CSS classes, separated by whitespace.
Renders a *free* [Font Awesome](https://fontawesome.com/) icon, which you could technically do manually in the code editor as well. Somewhat more convenient, I guess? Just omit the shortcode block and write it directly into the text. This shortcode also works if your role lacks the shortcode capability.
Renders a multi-column grid of paginated medium cards ordered by publishing date, descending. Unless you provide the **count** parameter, only add this once per page since it uses the main query page argument. The thumbnail is either the **Landscape Image** or **Cover Image**, depending on the aspect ratio and availability, with chapters defaulting to the parent story.
* **post_type:** Comma-separated list of post types to query. Default `post`.
* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool.
* **per_page:** Number of posts per page. Defaults to theme settings.
* **count:** Limit articles to any positive number, disabling the pagination.
* **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`.
* **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters).
* **ignore_sticky:** Whether sticky posts should be ignored or not. Default `false`.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
Renders paginated blog posts akin to the main blog page, but with options. Only add this once per page since it uses the main query page argument, avoid combining it with the Article Cards shortcode.
Renders a multi-column grid of small bookmark cards, ordered by date of creation. The bookmarks are stored in the browser and appended to the document via JavaScript. You can combine this with the `show-if-bookmarks hidden` additional CSS classes, displaying a headline or other element only if bookmarks are present.
Renders a list of chapters identical to those on story pages, ordered by sequence in the source. Must have either the **story_id** or **chapter_ids** parameter, but not both.
Renders a contact form with various (optional) fields. Submissions are validated, sanitized, have basic spam protection, and are checked against the WordPress disallow list under **Settings > Discussions**. If all steps are passed, the submission is sent to the email addresses listed under **Fictioneer > General > Contact Form Receivers**, which are never revealed to the public. If empty, the admin email address is used instead.
* **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`.
* **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters).
* **spoiler:** The excerpt is obfuscated, set `true` if you want to reveal it. Default `false`.
* **source:** Set `false` to hide the author and story nodes. Default `true`.
* **aspect_ratio:** CSS [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) value for the image (X/Y; vertical only). Default `3/1`.
* **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`.
* **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters).
* **aspect_ratio:** CSS [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) value for the image (X/Y; vertical only). Default `3/1`.
* **count:** Limit stories to any positive number, although you should keep it reasonable. Default `4`.
* **type:** Either `default` or `compact`. The compact variant is smaller with less data.
* **author:** Only show stories of a specific author. Make sure to spell the _username_ right.
* **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`.
* **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters).
* **aspect_ratio:** CSS [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) value for the image (X/Y; vertical only). Default `3/1`.
* **aspect_ratio:** CSS [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) value for the image (X/Y; vertical only). Default `3/1`.
Renders dynamic grid of thumbnails with title, showing the latest eight posts of the specified type ordered by publishing date, descending. Requires **for** parameter. The thumbnail is either the **Landscape Image** (if available) or **Cover Image**, with chapters defaulting to the parent story.
* **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`.
* **orderby:** The default is `date`, but you can also use `rand` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters).
Renders the theme sidebar (not displayed anywhere by default). Requires the "Disable all widgets" theme setting to be off. Note that the sidebar has next to no styling.
If you have the Elementor plugin installed, consider using the [Fictioneer 002 Elementor Control](https://github.com/Tetrakern/fictioneer/blob/main/INSTALLATION.md#recommended-must-use-plugins) plugin if you only need it for the Canvas page templates. If you have the Pro version and want to use the theme builder, this may not be an option, but you can customize the following locations: `header`, `footer`, `nav_bar`, `nav_menu`, `mobile_nav_menu`, `story_header`, and `page_background`.
This location can be confusing. The page background is actually a separate element in the theme, positioned under the content container and made inaccessible. This allows for various styling shenanigans without ever affecting the content, such as clip-paths and masks applied to an inner `::before` pseudo-element. The page styles from the Customizer make heavy use of this. If you overwrite this location, you must ensure to properly move it to the background. The base default CSS is as follows:
You can upload images and other media either in the Media Library or directly via drag-and-drop into the editor, as explained in the [official documentation](https://wordpress.org/support/article/media-library-screen/). Make sure to scale and compress your images, because 20 MB of header art will slow down your site to a crawl. There is not much else to add except for one vital concept many new website owners are unaware of: **never hotlink images** unless you have explicit permission. Normal links that need to be clicked are fine.
**Hotlinking:** Refers to embedding images (or other media) that are hosted on an external server, offloading the work and stealing bandwidth. This can cause high cost for the victim and get you into legal trouble, although many servers block hotlinking preemptively for that reason. Imagine this happening to you, having to pay for people merrily posting your images everywhere (copying and re-uploading excluded).
If you are now concerned, you can take a breather. This issue will most likely not immediately (or ever) affect you unless you plan to serve many images per post, page, or chapter. Managed hosts normally also take care of this themselves to save bandwidth, and content delivery networks (CDN) offer their own solutions if necessary. Just keep it in mind and do not become an offender yourself.
## Users & OAuth
Fictioneer offers the option to enable user authentication via the OAuth 2.0 protocol, which you probably know as the annoying "Log in with Google" popover. There are no annoying popovers here, but the functionality remains the same. Instead of username/email and password, you authenticate with a social media account: Discord, Google, Patreon, or Twitch (if [set up](INSTALLATION.md#connections-tab)).
This automatically creates and connects a subscriber account, which makes commenting convenient and allows subscribers to track their progress with Checkmarks, Follows, and Reminders. You also most likely do not need any of that or the potential headache that comes with user management. Unless you host dozens to hundreds of stories, perhaps from several authors, you are better off without. Even then, be aware that a community site requires more server resources, which translates to either bad performance or higher cost.
**Note:** Make sure you have a proper [Privacy Policy](PRIVACY.md) set up before you allow registrations. Fictioneer does not collect undue data and this is an informed, deliberate action. However, privacy is always an issue. This is why subscribers should have the option to self-delete their data and accounts at any time, sparing you a lot of potential trouble (i.e. "the right of erasure").
If everything is set up and the link does not work, flush your permalink structure under **Settings > Permalinks** (just save, you do not need to change anything).
Checkmarks, Follows, and Reminders are progress tracking features for logged-in subscribers that need to be enabled in the settings. But unless you host dozens or hundreds of stories, they are mostly a gimmick. Single serials do not need them and readers are quite capable of keeping track with browser features alone. Please refer to [Users & OAuth](#users--oauth) for more considerations regarding user registration. If you decide to enable these features, you should also assign a Bookshelf page in the theme settings.
**Checkmarks:** You can mark chapters and stories as being read, the latter being displayed in your Finished list. This is also reflected in card lists with a check icon in the top-right corner.
**Follows:** You can follow stories to get update notifications on the site (up to 16, not via email) and see them in your Follows list. This is also reflected in card lists with a star icon in the top-right corner.
**Reminders:** You can mark stories to be read later and see them in your Reminders list. This is also reflected in card lists with a clock icon in the top-right corner.
## Bookmarks
Bookmarks are a progress tracking feature that does not require an account. They are only processed client-side and stored locally in the browser, which means they are not available in different browsers on the same or across devices. This convenience can be achieved with an account, though. Bookmarks save the scroll position of a paragraph in a chapter, with an excerpt, thumbnail, progress in percent, and color. You can only have one bookmark per chapter, up to a maximum of 50 bookmarks total.
## User Profile
The default WordPress user profile has been extended with a new Fictioneer section. You also have the option to greatly reduce the profile of _subscribers_ under **Fictioneer > General > Security & Privacy > Reduce subscriber user profile**, getting rid of superfluous fields. Other menus are hidden by default, but it is recommended to use the frontend profile with the User Profile page template.
**Subscribers:**
* **Fingerprint:** Unique user hash used to distinguish commenters with the same nickname. Impersonation is a thing.
* **Profile Flags:** Checkboxes to always use a gravatar, disable your avatar, hide your badge, and persist comment reply notification.
* **OAuth 2.0 Connections:** Connect or disconnect social media accounts as logins: Discord, Google, Patreon, and Twitch.
* **Data:** Summary of submitted data by the user, such as comments, and the option to delete it.
**Authors:**
* **Author Page:** Show the content of a selected page in your author profile instead of the biographical info.
* **Support Message:** Customize the message above support links in chapters.
**Moderators:**
* **Moderation Flags:** Checkboxes to disable selected user capabilities, such as the avatar or commenting.
* **Moderation Message:** Custom message shown in the user’s profile. This can be something nice.
**Administrators:**
* **Badge Override:** Override a user’s badge with a custom string. Do not bully.
* **External Avatar URL:** External link to an avatar image hosted on a CDN.
You may wonder what the numbers 50-950 in the Customizer color sections are about. These refer to the variable names that hold the respective color, such as `var(--red-500)` or `var(--fg-500)`. Each color is actually a function that adapts to the user’s own settings on the frontend (saturation, lightness, etc.). So using these colors is recommended, because a simple hex code does not care for the user’s preferences.
If you ever want to apply colors with CSS, you can do it like this: `color: var(--fg-500);` or `background-color: var(--bg-700);`. The color options in the post editor are already accounted for, so you do not need to worry there. The most common prefixes are `--bg-#` for background, `--fg-#` for foreground (text), `--primary-#` for links, as well as `--red-#` and `--green-#`. More can be found in the [_properties.scss](src/scss/common/_properties.scss).
This is not an error but intentional, the theme only allows blocks that are properly integrated. But you can enable the rest under **Fictioneer > General > Compatibility > Enable all Gutenberg blocks**. There is no guarantee they will work or look good.
There are a few reserved URL slugs you must not use in permalinks, otherwise you will run into 404 error pages or infinite redirect loops. Albeit unlikely, this could happen if you choose post titles similar in name to these slugs. You can change permalinks in the [settings sidebar](https://wordpress.org/support/article/settings-sidebar/) if that ever becomes the case. Reserved slugs:
Some block settings lack styling in the theme or have been disabled because they do not work well with the layout. For example, the Latest Posts block ignores the thumbnail settings. Custom font sizes and colors should really be only used on headings or paragraphs.
