Documentation Storyweave

StoryWeave Theme – Complete Documentation

Version 1.0.0
License: GPLv2 or later

1. Introduction

StoryWeave is a modern, literary WordPress theme crafted for storytellers, bloggers, and content creators who value elegance, readability, and a warm, inviting aesthetic. Inspired by the timeless charm of printed books, it combines a clean, serif‑driven typography with subtle textures and refined spacing. Whether you are writing personal essays, serialised fiction, or long‑form journalism, StoryWeave provides an immersive reading experience that puts your words at the centre.

The theme is Gutenberg‑ready and comes with custom block styles, block patterns, and full support for wide alignments. It also includes dark mode with system preference detection, a sticky header with navigation and social links, and five distinct blog layouts – from a classic list to an advanced asymmetric Bento grid.

2. Key Features

  • Dark Mode – toggle between light and dark themes; respects system preferences and remembers your choice.

  • 5 Blog Layouts – Classic List, Grid, Bento (asymmetrical grid), Story Timeline, and Chapter.

  • Content Layout Options – choose between “With Sidebar” (65/35 split) or “Full Width”.

  • Accent Colour Picker – personalise links, buttons, and borders via the Customizer.

  • Sticky Header – always‑visible header with logo, primary navigation, dark mode toggle, and social icons.

  • Custom Header Image – upload a full‑width header image with position control (top/centre/bottom).

  • Full Gutenberg Compatibility – block styles, align‑wide support, and custom block patterns.

  • Mobile‑Friendly – responsive design with a hamburger menu on small screens.

  • Translation Ready – all strings are translatable; includes a .pot file.

3. Installation

From WordPress Dashboard

  1. Go to Appearance → Themes.

  2. Click Add New → Upload Theme.

  3. Choose the storyweave.zip file and click Install Now.

  4. After installation, click Activate.

Manual (FTP)

  1. Unzip the storyweave.zip file.

  2. Upload the storyweave folder to /wp-content/themes/.

  3. Go to Appearance → Themes and activate StoryWeave.

Child Theme (for advanced customisation)

Create a new folder, e.g., storyweave-child, and add a style.css with:

css
/*
Theme Name: StoryWeave Child
Template: storyweave
*/

Then enqueue the parent styles in functions.php. See the WordPress Child Theme documentation.

4. Theme Customisation

4.1 Customizer (Appearance → Customize)

 
 
Section Settings
Site Identity Logo, Site Title, Tagline, Site Icon.
Colors Accent Color – changes links, buttons, and borders.
Header Image Upload a custom header image and set its position (Top Left, Center, etc.).
Blog Layout Choose one of the five layouts: Classic, Grid, Bento, Timeline, Chapter.
Content Layout Select “With Sidebar” or “Full Width”.
Social Links (Fallback) enter a comma‑separated list of social media URLs (if no social menu is set).
Additional CSS Add your own custom CSS.

4.2 Menus (Appearance → Menus)

  • Primary Menu – the main navigation bar.

  • Social Links Menu – appears in the header and footer. Add custom links to your social profiles (e.g., https://twitter.com/yourhandle). To show icons, you can add CSS classes (like twitter, facebook) – the theme does not bundle icon fonts, but you can easily add Font Awesome or Dashicons via a plugin or custom CSS.

4.3 Widgets (Appearance → Widgets)

 
 
Widget Area Location
Sidebar Appears on the right (when “With Sidebar” is selected).
Footer 1, 2, 3 Three column areas at the bottom of the page.

Add any WordPress widgets (Recent Posts, Categories, Search, etc.) to these areas.

5. Blog Layouts Explained

The theme offers five distinct layouts for your blog index (homepage, archive, search results). All layouts are fully responsive.

5.1 Classic List

  • Vertical list of posts.

  • Each post shows the title, date, author, featured image (if set), excerpt, and read‑more link.

  • Simple, clean, and traditional.

5.2 Grid

  • Posts displayed in a responsive CSS grid (auto‑fill with minmax(280px, 1fr)).

  • Each post is a card with a shadow, hover lift effect, and a 16:9 featured image.

  • Perfect for visual portfolios and image‑heavy blogs.

5.3 Bento (Asymmetric Grid)

  • Uses grid-auto-flow: dense to create a magazine‑style layout.

  • Posts automatically get one of three span classes: featured (2×2), tall (2 rows), or wide (2 columns).

  • The first post becomes featured, the second tall, the third wide, and subsequent posts get random spans.

  • Creates an eye‑catching, irregular grid layout.

5.4 Story Timeline

  • A vertical timeline with a central line and circular markers.

  • Each post is a “milestone” with date, title, and excerpt.

  • Ideal for narratives, travel logs, or historical blogs.

5.5 Chapter

  • Each post is styled as a “chapter” with a large title prefixed with “Chapter”.

  • Dashed separators between chapters.

  • Great for serialised fiction or long‑form series.

6. Dark Mode

Dark mode is available globally and can be toggled via the sun/moon icon in the header.

  • System preference detection: If no manual choice is made, the theme will automatically switch to dark mode when your operating system uses dark mode.

  • Persistence: Your preference is stored in a cookie for one year, so it persists across sessions.

  • CSS Custom Properties: All colour variables are defined in :root and updated via CSS classes (dark-mode/light-mode). This makes it easy to customise.

To manually override: Add the class dark-mode or light-mode to the <body> tag via a filter or custom JavaScript.

7. Gutenberg Compatibility

StoryWeave is fully integrated with the WordPress block editor.

  • Editor Styles: The theme loads style.css as the editor style, giving you a WYSIWYG experience.

  • Block Styles: Core blocks (paragraphs, headings, quotes, buttons, etc.) inherit the theme’s typography and colours.

  • Wide Alignment: Supports alignwide and alignfull for cover blocks, images, and groups.

  • Block Patterns: A “StoryWeave Hero” pattern is pre‑registered. You can add more via register_block_pattern().

8. Custom Header Image

The theme supports a custom header image that appears as a background behind the header bar.

  • Upload: Go to Appearance → Customize → Header Image and upload an image (recommended size: 1920×400px).

  • Position: Choose the focal point (Top Left, Center, Bottom Right, etc.) – the image will be cropped/positioned accordingly.

  • Text Colours: The site title and tagline colours can also be set here.

  • Overlay: A subtle dark overlay improves text readability over the image.

Developer Notes

The custom header is registered in inc/custom-header.php. If you want to remove the overlay, override the CSS rule for .site-header::before.

9. Developer Hooks & Filters

The theme provides several filters and actions for advanced customisation.

 
 
Filter Description
storyweave_content_width Default 820px – change the maximum content width (in pixels).
storyweave_body_classes Filter the array of classes added to the <body> tag.
storyweave_post_classes Filter the post classes (useful for changing Bento span assignments).
storyweave_custom_header_args Modify the custom header arguments (size, default image, etc.).

Example: Make the Bento layout always assign the first post as featured:

php
add_filter( 'storyweave_post_classes', function( $classes ) {
    global $wp_query;
    if ( 0 === $wp_query->current_post ) {
        $classes[] = 'featured';
    }
    return $classes;
} );

10. Frequently Asked Questions

Q: How do I set up social icons?
A: Create a custom menu and assign it to the Social Links Menu location. Add custom links to your social profiles. Optionally, you can also enter a fallback text in the Customizer (under Social Links).

Q: The header image is not showing.
A: Ensure you have uploaded an image in Customize → Header Image. Also, check that your <header> element has a minimum height (add custom CSS if needed). The theme outputs the image as a background; if you see a blank header, try adding min-height: 150px; to .site-header.

Q: Can I use my own fonts?
A: Yes. In a child theme, override the CSS custom properties --sw-font-body and --sw-font-headings. You can also enqueue Google Fonts via functions.php.

Q: The sidebar is not visible.
A: Make sure you have added widgets to the Sidebar widget area. Also, ensure the Content Layout is not set to “Full Width”. If both are correct, check that the sidebar template file (sidebar.php) is not overridden by a child theme.

Q: How do I change the accent colour for dark mode?
A: The accent colour is a single global colour – it applies to both light and dark modes. To have different accent colours per mode, add custom CSS that overrides --sw-color-primary inside the dark-mode class.

Q: Does the theme support RTL?
A: Yes. The theme includes RTL support via wp_style_add_data( 'storyweave-style', 'rtl', 'replace' ) in functions.php. Your WordPress language setting should automatically load the correct styles.

11. Changelog

1.0.5 – Initial public release

  • All core features implemented.

  • Dark mode, five blog layouts, customizer options, custom header, Gutenberg support.

  • Passed Theme Review guidelines.

12. Credits

  • Underscores (_s) – starter theme (GPLv2) – underscores.me

  • Dashicons – included with WordPress (GPLv2) – used for menu toggle and dark mode icon.

  • All other code and design by the WordPress Theme Team.

Thank you for choosing StoryWeave. Happy storytelling!