kiosque 0.1.0

Save newspaper articles in textual format

kiosque

A unified tool for news article extraction and bookmark management.

What is Kiosque?

Kiosque combines three essential capabilities:

1. Article Extractor (CLI/API) - Download full-text articles from several paywalled news websites as Markdown
2. Bookmark Manager (TUI) - Browse and manage bookmarks from Raindrop.io and GitHub Stars in a beautiful terminal interface
3. Content Aggregator - Unified tabbed interface for multiple content sources with smart context-aware actions

Quick Start

# Launch TUI (Terminal User Interface) - default
kiosque

# Extract article to file
kiosque https://www.lemonde.fr/article output.md

# Print to stdout
kiosque https://www.nytimes.com/article - | bat - -l md

# Download NYT front page PDF
kiosque nyt

Installation

# From PyPI
pip install kiosque

# Or with uv (recommended)
uv tool install kiosque

Requirements: Python 3.12+, pandoc

Core Features

📰 Article Extraction

• News Websites - Le Monde, NYT, Guardian, Mediapart, and more
• Authentication - Login support for paywalled sites
• Markdown Output - Clean, readable format with metadata
• Proxy Support - Access geo-blocked websites via SOCKS/HTTP proxies

🔖 Bookmark Management

• Raindrop.io Integration - Browse, preview, archive, delete, edit tags
• GitHub Stars - Explore starred repos, preview READMEs, unstar
• Unified Search - Filter by title, URL, tags, topics across all sources
• Beautiful Previews - Markdown rendering with syntax highlighting

🚀 Content Aggregation

• Tabbed Interface - Switch between Raindrop and GitHub
• Progressive Loading - Non-blocking, fast performance
• Smart Actions - Context-aware keybindings (e.g., star GitHub repos from Raindrop)

Configuration

Create ~/.config/kiosque/kiosque.conf:

# Website authentication
[https://www.lemonde.fr/]
username = [e-mail]
password = your_password

[https://www.nytimes.com/]
cookie_nyt_s = your_nyt_cookie_value

# Raindrop.io integration
[raindrop.io]
token = your_raindrop_api_token

# GitHub Stars integration
[github]
token = ghp_your_github_personal_access_token

# Proxy for geo-blocked sites (optional)
[proxy]
url = socks5://localhost:1080

Python API

from kiosque import Website

# Extract article as Markdown
url = "https://www.lemonde.fr/article"
markdown = Website.instance(url).full_text(url)

# Save to file
Website.instance(url).save(url, "article.md")

Documentation

📚 Full documentation: https://www.xoolive.org/kiosque

• Installation - Detailed installation guide
• Configuration - Authentication setup for all sites
• TUI Guide - Complete terminal interface reference
• Supported Sites - Full list of websites
• Authentication - Site-specific login instructions
• Adding Sites - Contributing new website support
• Troubleshooting - Common issues and solutions

TUI Keybindings

Key	Action
↑ or k / ↓ or j	Navigate entries
1 / 2	Switch tabs
/	Search
Space	Preview article/README
Enter / o	Open in browser
t	Edit tags (Raindrop)
e	Archive (Raindrop)
d	Delete (Raindrop)
u	Unstar (GitHub)
s	Star on GitHub (GitHub URLs)
r	Refresh
q	Quit

Contributing

Contributions welcome! See the Contributing Guide for:

• How to add support for new websites
• Code style and testing guidelines
• Architecture overview

License

MIT