Indie Bookhaven Theme Documentation

Indie Bookhaven is a Shopify theme designed for independent bookstores, bookshops, author shops, gift shops, and other story-centered retailers.

It includes flexible page-building sections, bookstore-friendly product cards, a book-specific metadata band, collection filtering, store-hours-aware footer messaging, bookstore platform links, optional merchant-owned affiliate integrations, SEO-conscious product structure, and support for Shopify app blocks.

Use this documentation to set up the theme, configure bookstore-specific features, and troubleshoot common setup questions.

Getting Started

After installing Indie Bookhaven:

1. Open Online Store > Themes.
2. Find Indie Bookhaven and choose Customize.
3. Configure your global theme settings.
4. Set up your header, footer, homepage, product pages, collections, and cart.
5. Add products, collections, menus, pages, blog posts, and metafields in Shopify.
6. Review your store on desktop and mobile before publishing.

Recommended setup order:

1. Brand settings
2. Color schemes
3. Typography and buttons
4. Header and announcement bar
5. Footer, store information, and store hours
6. Product page settings
7. Book metadata mappings
8. Product condition metaobject
9. Shopify Search & Discovery filters
10. Collection and search pages
11. Cart settings
12. Homepage sections
13. Optional integrations
14. Accessibility and mobile review

Store Hours

The footer Store hours block reads store-hour values from Shop metafields.

Important: footer store hours should be created under Settings > Custom data > Shop, not under Locations.

The default Shop metafield keys are:

• custom.store_hours_set
• custom.monday_open
• custom.monday_close
• custom.tuesday_open
• custom.tuesday_close
• custom.wednesday_open
• custom.wednesday_close
• custom.thursday_open
• custom.thursday_close
• custom.friday_open
• custom.friday_close
• custom.saturday_open
• custom.saturday_close
• custom.sunday_open
• custom.sunday_close

Create the open and close fields as single line text metafields.

For each open/close time field, use this validation rule:

^(1[0-2]|[1-9]):[0-5][0-9] ?(AM|PM|am|pm)$

Supported examples:

• 9:00 AM
• 10:30 AM
• 6:00 PM
• 7:15pm

Do not use 24-hour time, words such as closed, or date ranges in these time fields.

If a day is closed, leave that day’s open and close fields blank.

The custom.store_hours_set field should be a true/false field. Set it to true when shop hours are configured.

Store Hours Setup

To use footer store hours:

1. Go to Settings > Custom data > Shop.
2. Create the store-hours metafield definitions listed above.
3. Use single line text for open and close time fields.
4. Add the recommended validation rule to each open and close field.
5. Add your store’s values to the Shop metafields.
6. Open the theme editor.
7. Go to theme settings and confirm the Store hours metafield mappings.
8. Add or enable the Store hours block in the footer.
9. Confirm the footer shows the correct weekly hours and open/closed status.

Product pickup messaging can still use matching metafields on Locations when Shopify pickup availability is shown. Footer store hours, however, use Shop metafields.

Book Metadata

Indie Bookhaven works best when book information is stored in Shopify metafields and mapped in theme settings.

Common book metadata includes:

• ISBN
• Author
• Publisher
• Publication date
• Binding
• Page count
• Language
• Genres
• Product condition
• Dimensions
• Libro.fm URL

If using ISBN Express, many of these product metafields may already be created for you. Confirm the theme’s metafield mappings match the fields used by your store.

For bookstores, the Shopify product vendor field often works best when it contains the book’s author. This gives the theme a useful fallback for product cards, product pages, search results, and collection pages.

Product Condition

Indie Bookhaven supports product condition using product or variant data. This is important for SEO, as google wants a condition to be returned for book products.

For best results, create a product condition metaobject and map the condition metafield in theme settings. This is so that the three accepted producted conditions for search engines can be mapped to the variety of conditions that bookstores typically use. Google only accepts New, Used, and Refurbished. The mapping of the metaobject allows for Used - Good and Used - Like new to both map to Google's "used" condition while still showing customers the more detailed condition information necessary to set their expectations appropriately.

Recommended condition entries include:

• New
• Used
• Refurbished
• Damaged
• Discount

If using condition for structured data, include a schema condition value such as:

• https://schema.org/NewCondition
• https://schema.org/UsedCondition
• https://schema.org/RefurbishedCondition
• https://schema.org/DamagedCondition

Shopify Search & Discovery Filters

Collection filters, search filters, Browse Genres, and Smart Product Carousel matching depend on Shopify Search & Discovery configuration.

If a carousel or filter relies on a metafield such as author, genre, binding, page count, language, publisher, or condition, that metafield should be enabled as a filter in Shopify Search & Discovery.

To configure filters:

1. Install or open Shopify’s Search & Discovery app.
2. Go to Filters.
3. Add the product metafields you want customers or theme sections to use.
4. Confirm products have values for those metafields.
5. Test collection pages, search pages, Browse Genres, and Smart Product Carousel sections.

Smart Product Carousel sections that match by author, genre, or another metafield need the corresponding Search & Discovery filter to exist. Without that filter, Shopify may not return the expected matching products.

Smart Product Carousel

Smart Product Carousel can show products based on selected sources such as:

• Manual collections
• Same author
• Same genre
• Recently viewed products
• Product recommendations

For same-author or same-genre carousels, make sure:

• The current product has the mapped metafield value.
• Other products share that value.
• The metafield is enabled as a Shopify Search & Discovery filter.
• The source collection contains eligible products.

Recently viewed products depend on customer browsing activity and may be empty for new visitors.

Optional Bookshop.org Support

Indie Bookhaven can support optional Bookshop.org buttons for merchants who want to offer Bookshop.org links.

The Bookshop affiliate setting is merchant-owned. It is blank by default.

Theme creators do not receive affiliate revenue from merchant stores. If a merchant enters their own Bookshop.org affiliate ID, that ID belongs to the merchant and is used for that merchant’s storefront links.

To use Bookshop.org links:

1. Enter your own Bookshop.org affiliate ID in theme settings.
2. Make sure products have ISBN or barcode data.
3. Enable the relevant Bookshop button settings.
4. Review product pages and product cards to confirm links appear only where appropriate.

If no affiliate ID is entered, the theme may use non-affiliate Bookshop.org search links where supported.

If you do not use Bookshop.org, leave the related settings blank or disabled.

Optional Libro.fm Support

Indie Bookhaven can show Libro.fm audiobook links when a product has a Libro.fm URL.

Recommended product metafield:

custom.librofm_url

To use Libro.fm links:

1. Create or confirm the Libro.fm URL product metafield.
2. Add Libro.fm URLs to eligible products.
3. Map the metafield in theme settings if needed.
4. Confirm audiobook buttons only appear when a URL is present.

Footer Links and Follow on Shop

The footer supports standard social links and bookstore-specific links such as:

• Bookshop.org
• Libro.fm
• StoryGraph
• Follow on Shop

Leave unused links blank. Blank links stay hidden.

Accessibility Guidance

Before publishing, review:

• Color contrast
• Mobile layout
• Keyboard navigation
• Image alt text
• Heading order
• Link text clarity
• Button text clarity
• Form labels
• App block accessibility

Merchant-customized colors, images, page content, and app blocks can affect accessibility.

Performance Guidance

For best performance:

• Use appropriately sized images.
• Avoid uploading unnecessarily large images.
• Keep homepage sections focused.
• Remove unused app blocks.
• Avoid heavy third-party apps unless needed.
• Test on mobile, not just desktop.

Troubleshooting

Store hours are not showing

Check that:

• Store hours metafields were created under Shop, not Location.
• The Store hours block is enabled in the footer.
• custom.store_hours_set exists on Shop and is set to true.
• Open and close time values exist on Shop.
• Time values match the supported format, such as 9:00 AM.
• The theme settings map to the correct namespace and key.
• Closed days have blank open and close fields.

Filters are not showing

Check that:

• Products have values for the fields you want to filter by.
• Shopify Search & Discovery filters are configured.
• The relevant metafields are enabled as filters.
• The collection or search result has products that contain those values.

Smart Product Carousel is showing unexpected products

Check that:

• The carousel source is configured correctly.
• The mapped metafield exists and has values.
• Matching products share the same metafield value.
• The matching metafield is enabled as a Shopify Search & Discovery filter.
• The source collection contains eligible products.

Book metadata is not showing

Check that:

• The product has metafield values.
• The metafields are mapped in theme settings.
• The block or section that displays metadata is enabled.
• The metafield type is compatible with the theme setting.
• The value is not blank.

Shelf talker is not showing

Check that:

• The shelf talker metafield exists.
• The product has shelf talker content.
• The shelf talker metafield is mapped in theme settings.
• The shelf talker preset is enabled.
• The preset is expected to stay hidden when the mapped field is blank.

Bookshop or Libro.fm buttons are not showing

Check that:

• The integration is enabled or configured.
• The product has the required ISBN, barcode, or URL.
• The product is eligible for the button.
• The related setting or metafield is not blank.

Support

For support, use the contact form on this page.

Please include:

• Store name
• Store URL or myshopify.com URL
• Theme version
• Page or template affected
• What you expected to happen
• What actually happened
• Steps to reproduce
• Screenshots or screen recording
• Apps involved
• Any recent changes you made

Release Notes

Version 1.0.0

Initial release of Indie Bookhaven.

Includes:

• Bookstore-focused product cards
• Flexible homepage sections
• Header and announcement bar
• Footer with store information and Shop metafield store hours
• Store-hours-aware open/closed messaging
• Store hours validation guidance
• Follow Us Everywhere bookstore platform links
• Product metadata display options
• Book-specific metadata band
• ISBN Express-friendly default metafield mappings
• Author/vendor fallback support
• Product condition metaobject support
• Collection and search filtering
• Smart Product Carousel sections
• Cart/basket experience
• Gift card support
• Optional merchant-owned Bookshop.org support
• Optional Libro.fm support
• Optional review app support
• SEO-conscious product structure
• Product structured data support
• Custom layout and rich text blocks
• Theme app block support
• Accessibility and performance-focused defaults