Inserable User Guide

Inserable helps you automatically standardize image naming, manage the association between images and articles, and streamline your blog writing workflow. By enforcing strict file structures, it ensures your blog content remains portable and organized for years to come.

Video QuickStart Guide

You can watch these series of short QuickStart Guide of Inserable and see how it work in actions. The first installment covers the foundational navigations within the macOS environment.

[Watch] Inserable QuickStart 1: Basic Navigations

Note: Further instructional videos are currently in production and will be released shortly.

Initialization

The initialization contains 3 essential steps to bind Inserable to your existing Hugo file structure:

• Open Inserable and click the SETTINGS button at the bottom navigation bar.
• Set Image Root Folder: Select the directory where images are stored in your Hugo site (typically static/images).
• Set Markdown Root Folders: Click Add to include your primary article directories (typically content/posts).

Only one Image folder could be chosen as the root image folder, but Markdown folders could have multiple entries.

Note: If you see a pop up notification that prevents you from selecting the root folder, refer to the Utility section. The "One-Tap Mapping" tool is designed to resolve permission or structural conflicts instantly.

After setting up the root folders, Inserable will read every existing file and identify their connections. Sessions will be created automatically, removing the need for manual mapping.

Core Concepts

Session

A Session is the core unit of Inserable, representing a unique combination of an article and its related images. Each Session corresponds to a dedicated folder under the Image Root.

By default, if you used One-Tap mapping to clean scattered image files, the organized folder naming will follow this format: <article_name>_session_folder. The relationship between a session's image folder and its corresponding Markdown is strictly bijective.

Once this relationship is established, edits in Inserable are synchronized to the Markdown file, and pasting images automatically inserts the correct relative reference path.

Standardized Naming

In initialization or automatic standardization, Inserable renames images into a unified, sequential format:

<article_title>_001.png 
<article_title>_002.png 
<article_title>.png

This ensures images are arranged in sequence, making them easy to reference in Markdown while avoiding issues caused by special characters or inconsistent naming conventions from different cameras or devices.

Sync, Mirror and Integrity

Inserable enforces a structured folder format to keep your workflow clean. When files are moved or altered outside of the application (e.g., in Finder), the system will notice the change and prompt an integrity check.

Option 1: Re-Sync

If you altered files outside of Inserable with intention, use Re-Sync. This tells the application that the current state of files and folders is the new "latest reference." This state will be backed up into Inserable’s mirror storage.

Option 2: Restore

If changes occurred unintentionally, use Restore. Inserable maintains a mirror storage of the latest synced state. Restoring reverts all files to the last state Inserable verified. Note that every operation inside Inserable is treated as a "Sync."

Option 3: Delete

Choose this to remove the session. Inserable will move the session into the trash and perform a sync to clear integrity issues. Since a Session is a bijective concept, this action moves both the Markdown file and its session folder to the trash.

Summary: View Inserable as a guardian for your blog data. It tracks your files and forces a tidy organization, serving as a secondary safety net alongside your Git workflow.

Interface Introduction

Left Side: Session List

Displays all Sessions grouped by folder hierarchy automatically. You can toggle between "list" and "folder" views to switch between a flat list or grouped classifications based on your Markdown folder structure. Green link icons indicate a verified relationship, while grey icons indicate an inactive mapping.

Right Side: Image & Markdown View

Images View: Displays all images in the Session. Supports drag-and-drop from Finder. Images are automatically renamed and indexed. Double-clicking the title allows you to rename the Session, which synchronizes all filenames and their URLs within the Markdown article.

Markdown View: A specialized editor for bound Markdown content. Image URLs are highlighted. Supports direct image pasting (Cmd+V); Inserable saves the image to the session folder and inserts the formatted reference at your cursor position.

Bottom Bar

• IN SYNC: A status indicator. Click to trigger a manual integrity check and scan for new session candidates.
• SETTINGS: Access the configuration panel for folder paths and appearance.
• COPY: Copies the current view's content. In image view, this provides a list of all URLs and an optional change log.

Basic Operations

Adding Images: Drag images directly into the right panel in Image View, or paste an image from your clipboard while editing in Markdown View.

Renaming: Double-click the title in Image View to rename the entire session (updates folders, files, and links). Double-click in Markdown View to rename only the .md file itself.

Deletion: Selecting a session and using the delete button moves both the target image session folder and the Markdown file into the system trash simultaneously.

Utilities

One-Tap Mapping

Used to reformat existing Image Root folders for compatibility. It matches image references in Markdown files and establishes bindings in one click. A detailed log and backup of altered files are saved to your ~/Downloads folder (e.g., Inserable_OneTap_2026-01-26...).

Automatic Standardization

Process all unstandardized Sessions at once. Click UTILITY → Standardize All to rename files according to the article title schema.

TextBundle Import

Transforms .textbundle files into managed sessions. Inserable extracts images and content, establishing the bijective relationship and optimizing Hugo headers.

Settings Description

• Image Root Folder: The directory containing all session folders (e.g., static/images).
• Markdown Root Folders: One or more directories containing your articles.
• Appearance: Toggle between Light/Dark themes and control dynamic background effects.
• General: Options for automatic file deletion after processing and a 5-minute Auto-Save sync.

Frequently Asked Questions

Alpha 1.0.1 Upcoming Changes