User Guide & FAQ

Welcome to the comprehensive guide for WristTale. This document covers the supported book formats, how to organize your files, and answers to frequently asked questions.

Book Formats

WristTale adopts the industry-standard Markdown + YAML Frontmatter format for book import/export. This ensures maximum compatibility, human readability, and ease of editing.

Supported Extensions

  • Recommended: .md (Markdown)
  • Supported: .txt

Format Structure

A valid WristTale book file consists of two parts:

  1. Metadata: A YAML Frontmatter block at the very beginning, enclosed by ---.
  2. Content: The book text, using Markdown headings (#) to denote chapters.

Example

You can download a sample file here: The Little Prince

---
title: The Little Prince
author: Antoine de Saint-Exupéry
chapters: 27
---

# Chapter 1

Once when I was six years old I saw a magnificent picture in a book...

# Chapter 2

I lived my life alone, without anyone that I could really talk to...

Key Features:

  • Universal: Can be opened and edited in any text editor or Markdown app (Obsidian, Typora, VS Code).
  • Simple: No complex structures; just standard Markdown.
  • Robust Parsing: Explicitly identifies chapters using H1 headings (#), avoiding guessing errors.

Legacy Text Files (.txt)

Standard plain text files without metadata are still fully supported. WristTale uses smart regex pattern matching to automatically identify chapters based on common patterns (e.g., "Chapter 1").

Best Practices for .txt:

  • Ensure the file is encoded in UTF-8.
  • Use standard chapter headings like "Chapter X" on their own lines.
  • Avoid decorative borders or excessive whitespace around titles.

File Organization

WristTale organizes your library internally using a robust database, but when you export or manage files manually, understanding the structure helps.

Exporting Books

When you export a book from WristTale (via the "Export" option in the book menu), it is saved in the Markdown format (.md). This preserves all your chapter edits and metadata in a standard format.

  • Android: Files are saved to your Downloads folder.
  • iOS: Files are saved to the WristTale folder in the Files app (On My iPhone).

Importing Books

You can import books from anywhere on your device.

  • Tap the + (Import) button on the home screen.
  • Select a .md or .txt file from your device's file picker.
  • WristTale will parse the file, detect chapters, and add it to your library.

FAQ

1. Why is Garmin Connect required?

WristTale is built on the Connect IQ Companion SDK, which requires Garmin Connect Mobile to discover your watch and establish communication between your phone and watch. This is Garmin's official framework for third-party apps to sync data with watches.

2. What can I use WristTale for?

Beyond reading novels, WristTale is perfect for many scenarios:

  • Race Manuals: Store ultra-marathon course guides, aid station info, and cutoff times on your wrist for quick reference during races.
  • Study Materials: Students can keep course notes, formulas, or revision summaries accessible anytime.
  • Language Learning: Store vocabulary lists, common phrases, or grammar notes to utilize fragmented time throughout your day.
  • Reference Documents: Any text-based reference material you need quick access to.

Pro Tip: We highly recommend using AI tools (like ChatGPT or Claude) to clean up and format your documents before importing. They can:

  • Remove strange characters and formatting artifacts
  • Organize content into clear chapters
  • Improve readability for small watch screens

3. Why are my chapters not being detected correctly?

If you are importing a standard .txt file, the chapter detection relies on pattern matching. If your book uses unique or non-standard headings (e.g., "One", "Two" instead of "Chapter 1"), the automatic parser might miss them.

  • Solution: You can manually edit the chapter title in the app, or convert the file to Markdown format with explicit # chapter headings.

4. Can I edit chapter titles or content?

Yes! Long-press a book cover to open the menu, then select Book Details or simply tap the book to preview. In the preview screen, tap on a chapter to view its content. You can tap the content area to edit the text or the title bar to rename the chapter.

5. What encoding should my text files use?

WristTale is optimized for UTF-8 encoding. If your file uses a different encoding (like GBK or Windows-1252), you might see garbled text ("mojibake"). Please convert your file to UTF-8 before importing.

6. How do I understand the Storage Statistics?

The "Storage Stats" feature in the watch app displays values in bytes, not characters. This is because Garmin uses UTF-8 encoding to store data:

  • English characters/numbers: 1 byte each
  • Chinese characters: 3 bytes each (rare characters may use 4 bytes)

Therefore, if you're storing primarily Chinese content, divide the byte count by 3 to estimate the approximate character count. For example:

  • 1.5M bytes ÷ 3 ≈ 500,000 Chinese characters

7. How does sync work?

WristTale splits the book into small "chunks" to transfer them to your Garmin watch via Bluetooth.

  • Keep the app open: Both the phone app and the watch app must be open during sync.
  • Don't let the screen sleep: The phone app will try to keep the screen awake, but ensure you don't lock it manually.
  • Transfer Speed: Syncing a large book can take time due to Bluetooth Low Energy (BLE) limitations. We recommend syncing batches of 20-50 chapters at a time.

8. Why is the sync failing?

  • Watch Connection: Ensure your watch is connected to Garmin Connect Mobile.
  • App State: Force close and restart the WristTale app on both your phone and watch.
  • Beta Limit: If you are using the Beta version, there is a limit of 20 chapters per book.

9. Where are my books stored on the watch?

Books are stored in the app's private storage on the watch. You cannot access them directly via the file system (USB). To manage storage, use the Clear Storage option in the watch app's menu.

10. Does it support dark mode?

Yes, WristTale fully supports system-wide dark mode on both iOS and Android. The reading interface on the watch is also optimized for battery life, using black backgrounds on AMOLED screens.