miniflux-exporter 1.0.0

Export articles from Miniflux RSS reader to Markdown files

Miniflux Exporter

Export your Miniflux articles to Markdown format with full metadata preservation.

English | 中文

✨ Features

• 📄 Export to Markdown: Convert all your Miniflux articles to clean Markdown format
• 🗂️ Flexible Organization: Organize by feed, category, or keep all in one place
• 🔍 Smart Filtering: Export all articles, only unread, starred, or custom filters
• 📊 Metadata Preservation: Keep all article metadata (author, date, tags, etc.)
• 🐳 Docker Support: Run in a container without installing dependencies
• 🔄 Incremental Export: Skip already exported articles
• 🎨 Customizable: Configure filename formats, organization, and more
• 📦 Batch Processing: Efficiently handle thousands of articles
• 🌐 Cross-platform: Works on Windows, macOS, and Linux

🚀 Quick Start

Installation

pip install miniflux-exporter

Basic Usage

# Interactive setup (recommended for first time)
miniflux-export --setup

# Or use command-line arguments
miniflux-export --url https://miniflux.example.com \
                --api-key YOUR_API_KEY \
                --output ./articles

# Alternative: Run as Python module (if command not found in PATH)
python -m miniflux_exporter --setup
python -m miniflux_exporter --url https://miniflux.example.com \
                            --api-key YOUR_API_KEY \
                            --output ./articles

Using Configuration File

Create a config.yaml:

miniflux_url: https://miniflux.example.com
api_key: your_api_key_here
output_dir: miniflux_articles
organize_by_feed: true
organize_by_category: false

Then run:

miniflux-export --config config.yaml

📖 Documentation

Getting Your API Key

1. Log in to your Miniflux instance
2. Go to Settings → API Keys
3. Click Create a new API key
4. Give it a description (e.g., "Export Tool")
5. Copy the generated key

Command-Line Options

usage: miniflux-export [-h] [--version] [--config CONFIG] [--setup] [--test]
                       [--url URL] [--api-key API_KEY] [--output OUTPUT]
                       [--organize-by-feed] [--organize-by-category]
                       [--status {read,unread}] [--starred]
                       [--batch-size BATCH_SIZE] [--no-metadata] [--no-json]
                       [--quiet] [--verbose]

Export Miniflux articles to Markdown format

Optional arguments:
  -h, --help            Show this help message and exit
  --version             Show program's version number and exit
  --config CONFIG, -c CONFIG
                        Configuration file (YAML or JSON)
  --setup               Run interactive setup wizard
  --test                Test connection only (do not export)
  
Connection:
  --url URL             Miniflux instance URL
  --api-key API_KEY     Miniflux API key
  
Output:
  --output OUTPUT, -o OUTPUT
                        Output directory
  --organize-by-feed    Organize articles by feed
  --organize-by-category
                        Organize articles by category
  
Filters:
  --status {read,unread}
                        Filter by article status
  --starred             Export only starred articles
  
Advanced:
  --batch-size BATCH_SIZE
                        Number of articles to fetch per batch
  --no-metadata         Do not include metadata in files
  --no-json             Do not save metadata JSON file
  --quiet, -q           Suppress progress output
  --verbose, -v         Enable verbose logging

Configuration File Format

YAML Example

# Miniflux connection
miniflux_url: https://miniflux.example.com
api_key: your_api_key_here

# Output settings
output_dir: miniflux_articles
organize_by_feed: true
organize_by_category: false

# Filters (optional)
filter_status: null  # null, 'read', or 'unread'
filter_starred: null  # null, true, or false

# Filename format
filename_format: "{date}_{title}"  # Supports {date}, {id}, {title}

# Advanced options
batch_size: 100
include_metadata: true
save_json_metadata: true

# Markdown conversion options
markdown_options:
  ignore_links: false
  ignore_images: false
  body_width: 0
  skip_internal_links: false

JSON Example

{
  "miniflux_url": "https://miniflux.example.com",
  "api_key": "your_api_key_here",
  "output_dir": "miniflux_articles",
  "organize_by_feed": true,
  "organize_by_category": false,
  "filter_status": null,
  "filter_starred": null,
  "filename_format": "{date}_{title}",
  "batch_size": 100,
  "include_metadata": true,
  "save_json_metadata": true
}

📂 Output Structure

Organized by Feed

miniflux_articles/
├── articles_metadata.json
├── TechCrunch/
│   ├── 2024-01-15_Article_Title_1.md
│   └── 2024-01-16_Article_Title_2.md
├── Hacker_News/
│   ├── 2024-01-15_Article_Title_3.md
│   └── 2024-01-17_Article_Title_4.md
└── Blog_Name/
    └── 2024-01-18_Article_Title_5.md

Organized by Category + Feed

miniflux_articles/
├── articles_metadata.json
├── Technology/
│   ├── TechCrunch/
│   │   └── 2024-01-15_Article_Title_1.md
│   └── Hacker_News/
│       └── 2024-01-15_Article_Title_2.md
└── Programming/
    └── Blog_Name/
        └── 2024-01-18_Article_Title_3.md

Markdown File Format

Each exported file contains:

---
title: "Article Title"
author: "Author Name"
feed: "Feed Name"
category: "Category Name"
url: "https://example.com/article"
published_at: "2024-01-15T10:30:00Z"
created_at: "2024-01-15T11:00:00Z"
status: "read"
starred: false
reading_time: 5
entry_id: 12345
feed_id: 67
---

# Article Title

Article content in Markdown format...

## Section

Content here...

🐳 Docker Usage

Using Docker Hub Image

docker run -v $(pwd)/articles:/output \
           -e MINIFLUX_URL=https://miniflux.example.com \
           -e MINIFLUX_API_KEY=your_api_key \
           fisherpensieve/miniflux-exporter

Using Docker Compose

Create a docker-compose.yml:

version: '3.8'

services:
  miniflux-exporter:
    image: fisherpensieve/miniflux-exporter
    volumes:
      - ./articles:/output
    environment:
      - MINIFLUX_URL=https://miniflux.example.com
      - MINIFLUX_API_KEY=your_api_key
      - MINIFLUX_OUTPUT_DIR=/output

Then run:

docker-compose up

Building from Source

cd docker
docker build -t miniflux-exporter .

💡 Use Cases

Backup Your Articles

# Export all articles for backup
miniflux-export --config config.yaml

Export Reading List

# Export only unread articles
miniflux-export --config config.yaml --status unread

Archive Starred Articles

# Export only starred articles
miniflux-export --config config.yaml --starred

Migrate to Another Platform

# Export everything with metadata
miniflux-export --config config.yaml --output ./export

Integration with Other Tools

Export articles and:

• Import to Obsidian for knowledge management
• Import to Notion for note-taking
• Generate a static site with Hugo or Jekyll
• Analyze with custom scripts using the JSON metadata

🔧 Development

Setup Development Environment

# Clone the repository
git clone https://github.com/bullishlee/miniflux-exporter.git
cd miniflux-exporter

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Install in editable mode
pip install -e .

Running Tests

pytest tests/

Code Style

# Format code
black miniflux_exporter/

# Lint code
flake8 miniflux_exporter/
pylint miniflux_exporter/

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for more details.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Miniflux - A minimalist and opinionated feed reader
• html2text - Convert HTML to Markdown
• Python Miniflux Client - Official Python client

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

📈 Roadmap

• Web UI for easier configuration and monitoring
• Support for exporting to other formats (PDF, EPUB, HTML)
• Integration with cloud storage services
• Advanced filtering and search capabilities
• Scheduling and automation features
• Plugin system for custom processors

⭐ Star History

If you find this project useful, please consider giving it a star!

---

Made with ❤️ by the Miniflux Exporter community