Extract Actions

Extract actions enable the creation of new documents from markdown sections (headers). IWE provides two types of extract actions:

Extract - Extracts a single section into a new file
Extract All - Extracts all direct subsections of a section into separate files

Both operations:

Create new files containing the selected content
Add block reference links (like [Section Title](new-file)) to the newly created files
Automatically adjust header levels to maintain proper document structure
Support relative path preservation

The reverse operation, known as inline, allows you to:

Embed the content back into the document via the block reference link
Remove the link and the extracted file

Extract Single Section

Basic Configuration

The extract action is configured in .iwe/config.toml under the [actions] section:

[actions]
extract = { type = "extract", title = "Extract section", key_template = "{{id}}", link_type = "markdown" }

Configuration Options

type: Must be "extract" for single section extraction
title: Display name shown in editor’s code actions menu
key_template: Template for generating the new file’s key/name (see Template Variables below)
link_type: Optional link format - "markdown" for [text](key) or "wiki" for [[key]]

Example: Basic Section Extraction

Source document (document.md):

# Main Document

## Important Section

This content will be extracted.

### Subsection

More content here.

After extraction (document.md):

# Main Document

[Important Section](extracted-123)

Extracted file (extracted-123.md):

# Important Section

This content will be extracted.

## Subsection

More content here.

Extract All Subsections

Configuration

[actions]
extract_all = { type = "extract_all", title = "Extract all subsections", key_template = "{{title}}", link_type = "markdown" }

Configuration Options

type: Must be "extract_all" for extracting all subsections
title: Display name shown in editor’s code actions menu
key_template: Template for generating new file keys/names
link_type: Optional link format - "markdown" for [text](key) or "wiki" for [[key]]

Example: Extract All Subsections

Source document (guide.md):

# User Guide

Introduction content here.

## Installation

How to install the software.

## Configuration

How to configure settings.

## Usage

How to use the application.

After extract all (guide.md):

# User Guide

Introduction content here.

[Installation](Installation)

[Configuration](Configuration)

[Usage](Usage)

Extracted files:

Installation.md:

# Installation

How to install the software.

Configuration.md:

# Configuration

How to configure settings.

Usage.md:

# Usage

How to use the application.

Template Variables

The key_template supports several template variables for flexible file naming:

Basic Variables

{{id}}: Random unique identifier (e.g., 123, 456)
{{today}}: Current date formatted using date_format from [library] section (default: %Y-%m-%d)
{{title}}: The section title being extracted (automatically sanitized for filenames)
{{slug}}: URL-friendly version of the title (lowercase, alphanumeric characters only, non-alphanumeric replaced with dashes, no consecutive dashes)

Parent Section Variables

{{parent.title}}: Title of the parent section containing the extracted section
{{parent.slug}}: URL-friendly version of the parent section title (lowercase, alphanumeric characters only, non-alphanumeric replaced with dashes, no consecutive dashes)
{{parent.key}}: Key of the parent document

Source Document Variables

{{source.key}}: Full key of the source document
{{source.file}}: Filename portion of the source document key
{{source.title}}: Title (first header) of the source document
{{source.slug}}: URL-friendly version of the source document title (lowercase, alphanumeric characters only, non-alphanumeric replaced with dashes, no consecutive dashes)
{{source.path}}: Directory path of the source document

Relative Path Behavior

IWE preserves directory structure when extracting sections. The key generation follows these rules:

Generated keys are relative to the source document’s directory
Key::combine(&key.parent(), &relative_key) creates the final path
The parent directory is automatically preserved

Example: Relative Path Extraction

Source document (docs/tutorial/basics.md):

# Basic Tutorial

## Getting Started

Content to extract.

Configuration:

extract = { type = "extract", title = "Extract", key_template = "extracted-{{title}}" }

Result:

Source: docs/tutorial/basics.md
Extracted file: docs/tutorial/extracted-Getting Started.md
Link: [Getting Started](extracted-Getting Started)

The extracted file is created in the same directory (docs/tutorial/) as the source document.

Advanced Configuration Examples

1. Simple Numeric Keys

extract = { type = "extract", title = "Extract", key_template = "{{id}}" }

Creates files like: 123.md, 456.md

2. Date-based Extraction

extract = { type = "extract", title = "Extract to today", key_template = "{{today}}" }

Creates files like: 2024-01-15.md

3. Title-based Extraction

extract = { type = "extract", title = "Extract section", key_template = "{{title}}" }

Creates files like: Getting Started.md, Configuration.md

4. Slug-based Extraction (URL-friendly)

extract = { type = "extract", title = "Extract as slug", key_template = "{{slug}}" }

Creates files like: getting-started.md, configuration.md From titles like “Getting Started”, “User’s Guide/Setup”, “API*Reference” → getting-started.md, users-guide-setup.md, api-reference.md

5. Hierarchical Extraction

extract = { type = "extract", title = "Extract with context", key_template = "{{parent.title}}-{{title}}" }

From a document with structure:

# User Guide
## Installation

Creates: User Guide-Installation.md

6. Hierarchical Extraction (URL-friendly)

extract = { type = "extract", title = "Extract with slug context", key_template = "{{parent.slug}}-{{slug}}" }

From a document with structure:

# User Guide & Setup
## Installation/Configuration

Creates: user-guide-setup-installation-configuration.md

7. Source-aware Extraction

extract = { type = "extract", title = "Extract from source", key_template = "{{source.file}}-{{title}}" }

From user-guide.md:

## Installation

Creates: user-guide-Installation.md

8. Source-aware Extraction (URL-friendly)

extract = { type = "extract", title = "Extract with source slug", key_template = "{{source.slug}}-{{slug}}" }

From User Guide & Manual.md:

# User Guide & Manual
## Installation/Setup

Creates: user-guide-manual-installation-setup.md

9. Path-based Organization

extract = { type = "extract", title = "Extract to subfolder", key_template = "extracted/{{title}}" }

From docs/guide.md, creates: docs/extracted/Installation.md

10. Wiki-style Links

extract = { type = "extract", title = "Extract (wiki)", key_template = "{{id}}", link_type = "wiki" }

Creates links like: [[123]] instead of [Section Title](123)

11. Complex Template Example

extract = { type = "extract", title = "Extract with full context", key_template = "{{source.path}}/{{today}}-{{parent.title}}-{{title}}" }

From docs/tutorials/advanced.md on 2024-01-15:

# Advanced Tutorial
## Complex Features

Creates: docs/tutorials/2024-01-15-Advanced Tutorial-Complex Features.md

Key Collision Handling

When the generated key already exists, IWE automatically appends numeric suffixes:

First attempt: extracted-section.md
If exists: extracted-section-1.md
If exists: extracted-section-2.md
And so on…

Example: Handling Collisions

Multiple sections with same title:

# Document

## Section
Content 1

## Section
Content 2

## Section
Content 3

With key_template = "{{title}}", extract all creates:

Section.md (first section)
Section-1.md (second section)
Section-2.md (third section)

Date Formatting

The {{today}} variable uses the date_format setting from the [library] section:

[library]
date_format = "%Y-%m-%d"  # Results in: 2024-01-15

[actions]
extract = { type = "extract", title = "Daily extract", key_template = "{{today}}-{{title}}" }

Common date formats:

%Y-%m-%d: 2024-01-15
%Y%m%d: 20240115
%b %d, %Y: Jan 15, 2024
%A, %B %d, %Y: Monday, January 15, 2024

Filename Sanitization

Special characters in titles are automatically sanitized using the sanitize_filename crate:

Section/With*Special:Chars → SectionWithSpecialChars
"Quoted Section" → Quoted Section
Section | With | Pipes → Section With Pipes

Inline Notes