# Documentation
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.
Click the outline toggle in the top-right corner to see the table of contents.
## Front Page
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.
Demo Homepage
```html
[fictioneer_latest_posts count="1"]
[fictioneer_article_cards per_page="2" ignore_sticky="true"]
Latest Stories
[fictioneer_latest_stories count="10"]
Latest Updates
[fictioneer_latest_updates count="6"]
Latest Chapters
[fictioneer_latest_chapters count="6"]
Latest Recommendations
[fictioneer_latest_recommendations count="6"]
Bookmarks
[fictioneer_bookmarks count="10"]
```
Demo Story Page
```html
Nightmares and hallucinations have plagued Heather Morell all her life, relics of schizophrenia and childhood bereavement.
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.
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.
Katalepsis is an Ancient Greek word which means ‘comprehension’, or perhaps more accurately, ‘insight’.
Katalepsis is a serial web novel about cosmic horror and human fragility, urban fantasy and lesbian romance, set in a sleepy English university town.
New chapters are currently posted once a week, on Saturdays.
If you just finished the official ebook or audiobook of Volume I, the story resumes here.
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 here.
```
## Patreon Gate
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.
## Unlock Posts
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
[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`.
### Story Actions Shortcode
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`.
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_story_actions story_id="106"]
```
```
[fictioneer_story_actions story_id="182" follow="0" reminder="0" share="0"]
```
### Story Section Shortcode
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`.
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_story_section story_id="106"]
```
```
[fictioneer_story_section story_id="182" tabs="true" pages="true"]
```
### Story Comments Shortcode
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`.
```
[fictioneer_story_comments story_id="13"]
```
```
[fictioneer_story_comments story_id="13" header="0"]
```
### Story Data Shortcode
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.
```
[fictioneer_subscribe_button story_id="228"]
```
### Font Awesome Shortcode
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.
* **class:** Font Awesome CSS classes, separated by whitespace. You can custom ones, too.
```
Have some [fictioneer_fa class="fa-solid fa-mug-hot"]
```
### Article Cards
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`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author:** Only show recommendations by a specific author. Make sure to use the url-safe nice_name.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool.
* **genres:** Comma-separated list of genre names (case-insensitive), if you want to pick from a curated pool.
* **characters:** Comma-separated list of character names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **seamless:** Whether to remove the gap between the image and frame. Default `false` (Customizer setting).
* **thumbnail:** Whether to show the thumbnail/cover image. Default `true` (Customizer setting).
* **lightbox:** Whether clicking on the thumbnail/cover image opens the lightbox or post link. Default `true`.
* **terms:** Either `inline`, `pills`, or `none`. Default `inline`.
* **max_terms:** Maximum number of shown taxonomies. Default `10`.
* **date_format:** String to override the [date format](https://wordpress.org/documentation/article/customize-date-and-time-format/). Default `''`.
* **footer:** Whether to show the footer (if any). Default `true`.
* **footer_author:** Whether to show the post author. Default `true`.
* **footer_date:** Whether to show the post date. Default `true`.
* **footer_comments:** Whether to show the post comment count. Default `true`.
* **aspect_ratio:** CSS [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) value for the image (X/Y). Default `3/1`.
* **class:** Additional CSS classes, separated by whitespace.
* **splide:** Configuration JSON to turn the grid into a slider. See [Slider](#slider).
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_article_cards]
```
```
[fictioneer_article_cards post_type="post" per_page="4" ignore_sticky="true"]
```
```
[fictioneer_article_cards post_type="story, chapter" count="8" ignore_protected="true"]
```
```
[fictioneer_article_cards post_type="story, chapter" seamless="true" aspect_ratio="4/1"]
```
### Blog
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.
* **per_page:** Number of posts per page. Defaults to theme settings.
* **ignore_sticky:** Whether sticky posts should be ignored or not. Default `false`.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author:** Only show posts of a specific author. Make sure to use the url-safe nice_name.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **class:** Additional CSS classes, separated by whitespace.
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_blog]
```
```
[fictioneer_blog class="foo bar baz" per_page="5" exclude_cat_ids="1,23,24" categories="news"]
```
```
[fictioneer_blog categories="uncategorized"]
```
### Bookmarks
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.
* **count:** Limit bookmarks to any positive number. Default `-1` (all).
* **show_empty:** Whether to show a "no bookmarks" note or nothing if empty. Default `false`.
* **seamless:** Whether to remove the gap between the image and frame. Default `false` (Customizer setting).
* **thumbnail:** Whether to show the thumbnail/cover image. Default `true` (Customizer setting).
```
[fictioneer_bookmarks]
```
```
[fictioneer_bookmarks count="8" show_empty="true"]
```
```
[fictioneer_bookmarks count="8" seamless="true" thumbnail="0"]
```
### Chapter List
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.
* **story_id:** ID of a single story. You need either this or **chapters**.
* **chapter_ids:** Comma-separated list of chapter IDs. You need either this or **story**.
* **count:** Limit chapters to any positive number. Default `-1` (all).
* **offset:** Skip a number of chapters, which can make sense if you query all.
* **heading:** Show a heading with collapse toggle above the list.
* **group:** Only show chapters with a specific group name, which can transcend stories.
* **class:** Additional CSS classes, separated by whitespace. `no-auto-collapse` prevents default group collapsing (if set).
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_chapter_list story="69"]
```
```
[fictioneer_chapter_list class="foobar no-auto-collapse" story="69" count="10" offset="2"]
```
```
[fictioneer_chapter_list chapters="13,21,34" heading="Pigs are a lot bigger than you expect" group="You could ride it"]
```
### Contact Form
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.
* **title:** Title of the form shown in emails. Defaults to "Nameless Form".
* **submit:** Label of the submit button. Defaults to "Submit".
* **privacy_policy:** Whether the privacy policy must be accepted. Default `false`.
* **required:** Whether all fields must be filled out. Default `false`.
* **email:** Sender email address for replies.
* **name:** Sender name for personal replies.
* **text_[1-6]:** Custom text fields 1 to 6, e.g. **text_1** to **text_6**.
* **check_[1-6]:** Custom checkboxes 1 to 6, e.g. **check_1** to **check_6**.
* **class:** Additional CSS classes, separated by whitespace.
```
[fictioneer_contact_form]
```
```
[fictioneer_contact_form email="Email Address (required)" check_1="Totally not a robot" title="Human Test" privacy_policy="true" required="true"]
```
```
[fictioneer_contact_form email="Email Address (optional)" name="Your Name (optional)" text_1="Topic (optional)" title="Privacy Policy Contact Form" privacy_policy="true"]
```
### Cookie Buttons
Renders two buttons to deal with cookies, "Reset Consent" and "Clear Cookies". Best used in the Cookies section of your Privacy Policy.
```
[fictioneer_cookie_buttons]
```
### Latest Chapters
Renders a multi-column grid of small cards, showing the latest four chapters ordered by publishing date, descending. Note that the `list` type behaves a bit different with the parameters.
* **count:** Limit chapters to any positive number, although you should keep it reasonable. Default `4`.
* **type:** Either `default`, `simple`, `compact`, or `list`. The other variants are smaller with less data.
* **author:** Only show chapters of a specific author. Make sure to use the url-safe nice_name.
* **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:** Whether to show the author and story nodes. Default `true`.
* **post_ids:** Comma-separated list of chapter post IDs, if you want to pick from a curated pool.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool.
* **genres:** Comma-separated list of genre names (case-insensitive), if you want to pick from a curated pool.
* **characters:** Comma-separated list of character names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **vertical:** Whether to render the cards with the image on top. Default `false`.
* **seamless:** Whether to remove the gap between the image and frame. Default `false` (Customizer setting).
* **thumbnail:** Whether to show the thumbnail/cover image. Default `true` (Customizer setting).
* **lightbox:** Whether clicking on the thumbnail/cover image opens the lightbox or post link. Default `true`.
* **infobox:** Whether to show the info box and toggle on compact versions. Default `true`.
* **date_format:** String to override the [date format](https://wordpress.org/documentation/article/customize-date-and-time-format/). Default `''`.
* **footer:** Whether to show the footer (if any). Default `true`.
* **footer_author:** Whether to show the chapter author. Default `true`.
* **footer_words:** Whether to show the chapter word count. Default `true`.
* **footer_date:** Whether to show the chapter date. Default `true`.
* **footer_comments:** Whether to show the chapter comment count (not in `list`). Default `true`.
* **footer_status:** Whether to show the chapter story status. Default `true`.
* **footer_rating:** Whether to show the chapter age rating. 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`.
* **class:** Additional CSS classes, separated by whitespace.
* **splide:** Configuration JSON to turn the grid into a slider. See [Slider](#slider).
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_latest_chapters]
```
```
[fictioneer_latest_chapters genres="adventure, historical" characters="indiana jones"]
```
```
[fictioneer_latest_chapters count="10" type="compact" author="Tetrakern" order="asc" orderby="modified" spoiler="true" source="false" chapters="1,2,3,5,8,13,21,34"]
```
```
[fictioneer_latest_chapters source="false" vertical="true" seamless="true" aspect_ratio="5/1"]
```
```
[fictioneer_latest_chapters type="list" count="2"]
```
```
[fictioneer_latest_chapters type="list" orderby="rand" count="2" source="false" footer_status="false"]
```
### Latest Posts
Renders the last blog post or a list of blog posts, ignoring sticky posts, ordered by publishing date, descending.
* **count:** Limit posts to any positive number, although you should keep it reasonable. Default `1`.
* **author:** Only show posts of a specific author. Make sure to use the url-safe nice_name.
* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **class:** Additional CSS classes, separated by whitespace.
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_latest_posts]
```
```
[fictioneer_latest_posts count="16" tags="world building, characters" categories="blog, tutorials" rel="or"]
```
```
[fictioneer_latest_posts count="4" author="Tetrakern" posts="1,2,3,5,8,13,21,34"]
```
### Latest Recommendations
Renders a multi-column grid of small cards, showing the latest four recommendations ordered by publishing date, descending.
* **count:** Limit recommendations 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 recommendations by a specific author. Make sure to use the url-safe nice_name.
* **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).
* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool.
* **genres:** Comma-separated list of genre names (case-insensitive), if you want to pick from a curated pool.
* **characters:** Comma-separated list of character names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **vertical:** Whether to render the cards with the image on top. Default `false`.
* **seamless:** Whether to remove the gap between the image and frame. Default `false` (Customizer setting).
* **thumbnail:** Whether to show the thumbnail/cover image. Default `true` (Customizer setting).
* **terms:** Either `inline`, `pills`, or `none`. Default `inline`.
* **max_terms:** Maximum number of shown taxonomies. Default `10`.
* **lightbox:** Whether clicking on the thumbnail/cover image opens the lightbox or post link. Default `true`.
* **infobox:** Whether to show the info box and toggle on compact versions. 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`.
* **class:** Additional CSS classes, separated by whitespace.
* **splide:** Configuration JSON to turn the grid into a slider. See [Slider](#slider).
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_latest_recommendations]
```
```
[fictioneer_latest_recommendations genres="isekai" fandoms="original, fanfiction"]
```
```
[fictioneer_latest_recommendations count="10" type="compact" author="Tetrakern" order="asc" orderby="rand" recommendations="1,2,3,5,8,13,21,34"]
```
```
[fictioneer_latest_recommendations vertical="true" seamless="true"]
```
### Latest Stories
Renders a multi-column grid of small cards, showing the latest four stories ordered by publishing date, descending. Note that the `list` type behaves a bit different with the parameters.
* **count:** Limit stories to any positive number, although you should keep it reasonable. Default `4`.
* **type:** Either `default`, `compact`, or `list`. 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).
* **post_ids:** Comma-separated list of story post IDs, if you want to pick from a curated pool.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool.
* **genres:** Comma-separated list of genre names (case-insensitive), if you want to pick from a curated pool.
* **characters:** Comma-separated list of character names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **source:** Whether to show the author node. Default `true`.
* **vertical:** Whether to render the cards with the image on top. Default `false`.
* **seamless:** Whether to remove the gap between the image and frame. Default `false` (Customizer setting).
* **thumbnail:** Whether to show the thumbnail/cover image. Default `true` (Customizer setting).
* **lightbox:** Whether clicking on the thumbnail/cover image opens the lightbox or post link. Default `true`.
* **infobox:** Whether to show the info box and toggle on compact versions. Default `true`.
* **date_format:** String to override the [date format](https://wordpress.org/documentation/article/customize-date-and-time-format/). Default `''`.
* **terms:** Either `inline`, `pills`, or `none`. Default `inline`.
* **max_terms:** Maximum number of shown taxonomies. Default `10`.
* **footer:** Whether to show the footer (if any). Default `true`.
* **footer_author:** Whether to show the author. Default `true`.
* **footer_chapters:** Whether to show the chapter count (not in `list`). Default `true`.
* **footer_words:** Whether to show the word count. Default `true`.
* **footer_date:** Whether to show the date. Default `true`.
* **footer_status:** Whether to show the status. Default `true`.
* **footer_rating:** Whether to show the age rating. Default `true`.
* **footer_comments:** Whether to show the post comment count. Default `false`.
* **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`.
* **class:** Additional CSS classes, separated by whitespace.
* **splide:** Configuration JSON to turn the grid into a slider. See [Slider](#slider).
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_latest_stories]
```
```
[fictioneer_latest_stories genres="adventure, cyberpunk" characters="Rebecca" rel="or"]
```
```
[fictioneer_latest_stories count="10" type="compact" author="Tetrakern" order="asc" orderby="modified" stories="1,2,3,5,8,13,21,34"]
```
```
[fictioneer_latest_stories count="2" author="Hungry" seamless="true"]
```
```
[fictioneer_latest_stories type="compact" vertical="true" aspect_ratio="3/2"]
```
```
[fictioneer_latest_stories type="list"]
```
```
[fictioneer_latest_stories type="list" footer_status="false" footer_rating="false" terms="pills" aspect_ratio="2/3"]
```
### Latest Updates
Renders a multi-column grid of small cards, showing the latest four updated stories ordered by date of the last chapter change, descending. Note that the `list` type behaves a bit different with the parameters.
* **count:** Limit updates to any positive number, although you should keep it reasonable. Default `4`.
* **type:** Either `default`, `simple`, `single`, `compact`, or `list`. The other variants are smaller with less data.
* **single:** Whether to show only one chapter item (included in type `single`). Default `false`.
* **author:** Only show updates of a specific author. Make sure to use the url-safe nice_name.
* **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`.
* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool.
* **genres:** Comma-separated list of genre names (case-insensitive), if you want to pick from a curated pool.
* **characters:** Comma-separated list of character names (case-insensitive), if you want to pick from a curated pool.
* **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`.
* **source:** Whether to show the author node. Default `true`.
* **vertical:** Whether to render the cards with the image on top. Default `false`.
* **seamless:** Whether to remove the gap between the image and frame. Default `false` (Customizer setting).
* **thumbnail:** Whether to show the thumbnail/cover image. Default `true` (Customizer setting).
* **lightbox:** Whether clicking on the thumbnail/cover image opens the lightbox or post link. Default `true`.
* **infobox:** Whether to show the info box and toggle on compact versions. 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`.
* **words:** Whether to show the word count of chapter items. Default `true`.
* **date:** Whether to show the date of chapter items. Default `true`.
* **date_format:** String to override the [date format](https://wordpress.org/documentation/article/customize-date-and-time-format/). Default `''`.
* **nested_date_format:** String to override any nested [date formats](https://wordpress.org/documentation/article/customize-date-and-time-format/). Default `''`.
* **terms:** Either `inline`, `pills`, or `none`. Default `inline`.
* **max_terms:** Maximum number of shown taxonomies. Default `10`.
* **footer:** Whether to show the footer (if any). Default `true`.
* **footer_author:** Whether to show the story/chapter author. Default `true`.
* **footer_chapters:** Whether to show the story chapter count (not in `list`). Default `true`.
* **footer_words:** Whether to show the story word count. Default `true`.
* **footer_date:** Whether to show the story date. Default `true`.
* **footer_status:** Whether to show the story status. Default `true`.
* **footer_rating:** Whether to show the story age rating. Default `true`.
* **footer_comments:** Whether to show the post comment count. Default `false`.
* **class:** Additional CSS classes, separated by whitespace.
* **splide:** Configuration JSON to turn the grid into a slider. See [Slider](#slider).
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_latest_updates]
```
```
[fictioneer_latest_updates genres="romance, drama" fandoms="original"]
```
```
[fictioneer_latest_updates count="10" type="simple" author="Tetrakern" order="asc" stories="1,2,3,5,8,13,21,34"]
```
```
[fictioneer_latest_updates type="compact" order="asc" post_ids="13,106" seamless="true"]
```
```
[fictioneer_latest_updates type="compact" vertical="true" seamless="true"]
```
```
[fictioneer_latest_updates type="simple" single="true" date="0"]
```
```
[fictioneer_latest_updates type="list" count="2" nested_date_format="m/d/Y"]
```
```
[fictioneer_latest_updates type="list" count="2" seamless="true" date="false" words="false" footer_rating="false" terms="pills"]
```
### Search Form
Renders the search form with advanced options (if not disabled in the settings).
* **simple:** Set `true` to hide the advanced search options. Default `false`.
* **placeholder:** Change the placeholder text.
* **type:** Preselect either "any", "story", "chapter", "recommendation", "collection", or "post".
* **expanded:** Whether the advanced form is expanded. Default `false`.
* **tags:** Preselect tags as comma-separated list of term IDs.
* **genres:** Preselect genres as comma-separated list of term IDs.
* **fandoms:** Preselect fandoms as comma-separated list of term IDs.
* **characters:** Preselect characters as comma-separated list of term IDs.
* **warnings:** Preselect warnings as comma-separated list of term IDs.
```
[fictioneer_search]
```
```
[fictioneer_search simple="true" placeholder="What are you looking for?"]
```
```
[fictioneer_search tags="569" fandoms="200,199"]
```
### Showcase
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.
* **for:** Desired post type, either `stories`, `chapters`, `collections`, or `recommendations`.
* **count:** Limit posts to any positive number, although you should keep it reasonable. Default `8`.
* **author:** Only show posts for a specific author. Make sure to use the url-safe nice_name.
* **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).
* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool.
* **ignore_protected:** Whether protected posts should be ignored or not. Default `false`.
* **only_protected:** Whether to query only protected posts or not. Default `false`.
* **author_ids:** Only show posts of a comma-separated list of author IDs.
* **exclude_author_ids:** Comma-separated list of author IDs to exclude.
* **exclude_cat_ids:** Comma-separated list of category IDs to exclude.
* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude.
* **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool.
* **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool.
* **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool.
* **genres:** Comma-separated list of genre names (case-insensitive), if you want to pick from a curated pool.
* **characters:** Comma-separated list of character names (case-insensitive), if you want to pick from a curated pool.
* **no_cap:** Set `true` if you want to hide the caption.
* **aspect_ratio:** CSS [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) value for the item (X/Y).
* **height:** Override the item height. Superseded by `aspect_ratio`.
* **width:** Override the item minimum width (it will still be stretched to fill the space).
* **class:** Additional CSS classes, separated by whitespace.
* **splide:** Configuration JSON to turn the grid into a slider. See [Slider](#slider).
* **quality:** Either `'snippet'`, `'thumbnail'`, `'cover'`, `'medium'`, `'medium_large'`, `'large'`, or `'full'`. Default `'medium'`.
* **cache:** Whether the shortcode should be cached. Default `true`.
```
[fictioneer_showcase for="collections"]
```
```
[fictioneer_showcase for="collections" count="10" author="Tetrakern" order="asc" posts="1,2,3,5,8,13,21,34"]
```
```
[fictioneer_showcase for="stories" count="4" aspect_ratio="2/3" min_width="150px"]
```
### Slider
Any shortcode with the `splide` parameter can be turned into a slider. [Splide](https://splidejs.com/) is a flexible and lightweight slider that comes with [many options](https://splidejs.com/guides/options/) for customization, although applying them may be challenging if you are not familiar with [JSONs](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON). You can look up the details yourself.
The `splide` parameter only accepts JSON strings, such as `splide="{'type':'loop','perPage':3}"`. Note that you need to use **single quotes** due to the shortcode syntax. If there is even a minor error, the JSON will be rejected with a note, and the shortcode will default to its standard layout. Not all parameter combinations have been tested with Splide, so custom CSS may be required in some cases.
If you do not want to initialize a slider on page load, you can add the `no-auto-splide` CSS class via the `class` parameter in the shortcode or custom HTML (where the `splide` class is). Normally, Splide’s assets are only enqueued when a shortcode with the necessary parameter is found in the post content, but you can enable Splide globally under **Fictioneer > General > Compatibility**.
```
[fictioneer_latest_stories count="6" splide="{'type': 'loop', 'gap': '1.5rem', 'autoplay': true, 'perPage': 2, 'breakpoints': {'767': {'perPage': 1}}}"]
```
#### Custom HTML Sliders
If you enable Splide globally (or have a slider shortcode on the same page), you can use the HTML block to create your own Slider. Just copy the base [structure](https://splidejs.com/guides/structure/) and add any slides you like, although you will need to style them yourself using custom CSS. Initialize the slider with the [data attribute JSON](https://splidejs.com/guides/options/#by-data-attribute), but this time with double quotes as shown in the example. Unlike with shortcodes, navigation arrows are enabled by default but can be turned off with `"arrows:" false`.
```html
Slide 01
Slide 02
Slide 03
Slide 04
Slide 05
Slide 06
```
### Sidebar
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.
* **name:** Name of the sidebar in case you add some. Default `fictioneer-sidebar`.
```
[fictioneer_sidebar]
```
```
[fictioneer_sidebar name="other-sidebar"]
```
### Tooltip (Modal) & Footnotes
Includes a tooltip modal for the wrapped content, indicated by a dotted underline. Just omit the shortcode block and write it directly into the text. This shortcode also works if your role lacks the shortcode capability. If you enable the footnotes feature under **Fictioneer > General > Features**, the tooltips will also be appended to the content as footnotes.
**Formatting:** You can use HTML in the shortcode content attribute, as far as the post sanitizer and user role allows. However, be cautious of nested quotation marks and square brackets, as they can break the shortcode — use [HTML entities](https://developer.mozilla.org/en-US/docs/Glossary/Character_reference) instead.
**Footnotes:** There is no difference in use to append the tooltips as footnotes, complete with anchor link. Just enable the rendering globally. You can disable individual footnotes with the `footnote="false"` parameter (but not the other way around).
```
[fcnt content='This is a note.']note[/fcnt]
```
```
[fcnt header='Are you dense?' content='This typically refers to forms that are either literal skeletons or the underlying bearing *structure* of objects.']skeletal shapes[/fcnt]
```
## Elementor
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`.
**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:
```css
.main__background {
pointer-events: none;
user-select: none;
position: absolute;
inset: var(--page-inset-top, 0px) 0 0 0;
z-index: 0;
background-color: var(--page-bg-color);
box-shadow: var(--page-box-shadow);
contain: layout style;
}
```
**Hints:**
* The `nav_bar` location also overwrites the `nav_menu` location.
* Overwriting the navigation is possible but generally a poor life choice.
* Elementor disables several WordPress block styles when applied to a page...
* ... which can affect other elements, such as the Post Content header variant.
* Use the `padding-[top|right|bottom|left]` CSS classes to apply theme page padding.
* Use the `bg-[50|100|200|...|800|900|950]` CSS classes to force theme background colors.
* Use the `fg-[100|200|...|800|900|950]` CSS classes to force theme text colors.
* Use the `max-site-width` CSS class to apply the theme’s max site width.
* Use the `page-polygon` CSS class to apply the page clip-path chosen in the Customizer (if any).
* Use the `header-polygon` CSS class to apply the header clip-path chosen in the Customizer (if any).
* The grunge, layered peaks/steps, ringbook, and wave header/page masks have no utility classes.
* Some of the [content utility CSS classes](#additional-css-classes) will also work in Elementor.
* You can toggle the mobile menu with a label element targeting the `mobile-menu-toggle` ID.
* You can select the theme fonts in Elementor, grouped under "Fictioneer".
* You can use the theme shortcodes in the shortcode widget.
* The position and expected content of the header depend on your Customizer choices.
* The global Elementor text colors have been overwritten with theme colors.
* Elementor does not understand the theme’s display modes, colors, or HSL settings (use the color classes).
* Elementor makes your site slower unless you have a good cache plugin.
* Use the Canvas-type page templates if you want to drastically customize a page.
* Fictioneer is not meant for site editors; there are limitations you have to live with.
## Images & Media
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 & Reminders
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.
## Color Variables
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).
## Common Problems
Common problems and how to avoid/fix them.
### Missing Blocks
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.
### Reserved URL Slugs
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:
* oauth2
* download-epub
* fictioneer-logout
### Some block settings look bad or do nothing!
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.
