# =====================================================================
# smarks (Smart Marks): an HTML bookmark and RSS generator
# =====================================================================
# 
# A simple, fast bookmark system that generates a static HTML page with
# tag filtering, pagination and built-in search. Everything is embedded
# in the HTML: no databases or server-side requirements.
#
# Built for personal use. Polished for others who might find it useful
# (see the script's configuration section).
#
# Works equally well offline and online - including intranet-friendly 
# support for file:/// and relative local paths. Create separate HTML
# files for different purposes: public.txt, private.txt, etc...
#
# =====================================================================
# COMPATIBILITY
# =====================================================================
# 
# Supported: Linux (tested), macOS, *BSD and Windows
# 
# Output:    bookmarks.html (works in any modern browser)
#            rss.xml        (valid RSS 2.0 feed)
#
# Required:  Python 3.6 or higher (uses only standard library)
#
# =====================================================================
# LAYOUT
# =====================================================================
# 
# The generated HTML uses a clean 3-column desktop layout that's
# optimized for 1080p (zoom-friendly for other resolutions):
# 
#   - Left:   Tags (A to SPLIT_LETTER)
#   - Center: Bookmarks (with filtering, pagination and search)
#   - Right:  Tags (SPLIT_LETTER+1 to Z)
# 
# The current default split is the letter 'K'; configurable.
#
# =====================================================================
# FILE FORMAT
# =====================================================================
# 
# Each bookmark entry uses 4 lines: URL, TITLE, Description, Tags.
#
# Separate entries with one or more blank lines.
#
# Comment lines are supported (preceded with #)
#
# URL                [remote | local | absolute | relative]
# TITLE
# Description        [supports HTML]
# tag1, tag2, tag3   [tip: Use <b>tag</b> to PIN some tags to the top]
# <empty line>
#
# Bookmarks appended to the end of the text file will appear as the
# most recent entries in bookmarks.html and the RSS feed.
#
# =====================================================================
# FILE FORMAT EXAMPLE
# =====================================================================
#
# https://www.gutenberg.org/
# Project Gutenberg
# Free eBooks - over 70,000 free classic books
# ebooks, reading, public-domain
#
# https://archive.org/
# Internet Archive
# Digital <b>library</b> of internet sites and other resources
# archive, history, media
#
# file:///home/user/docs/python-cheatsheet.html
# Python Cheat Sheet
# Local reference guide for <a href="https://python.org">Python</a>
# python, programming, local
#
# ../../notes/todo.html
# Daily todo list
# Tasks and reminders for today
# todo, schedule, local
#
# https://www.openstreetmap.org/
# OpenStreetMap
# Free editable map of the world
# maps, geography
#
# =====================================================================
# PERFORMANCE EXPECTATIONS
# =====================================================================
# 
# Designed for modest collections (a few thousand bookmarks or less).
#
# Up to 1,000 bookmarks: Instant, no noticeable delay.
# About 5,000 bookmarks: Near-instant search and tag filtering.
#
# =====================================================================
# HOW TO USE
# =====================================================================
# 
# 1. Create a bookmarks.txt file following the format above
# 
# 2. Run the script with your bookmark file:
# 
#    Default output: bookmarks.html
#      sm bookmarks.txt
#
#    Custom output: mypage.html
#      sm bookmarks.txt mypage.html
#
#    Custom output: html extension auto-added
#      sm bookmarks.txt mypage
#
#    With a directory path
#      sm path/to/bookmarks.txt anyName.html
# 
# 3. This creates the HTML file with tag filtering and search with AND logic
     (all search terms must appear in the title, description or tags).

     Additionally, an rss.xml file is created in the current directory.
#
# 4. Upload both files to your web server to share with others or use
#    bookmarks.html locally.
#
# =====================================================================
# CONFIGURATION NOTES
# =====================================================================
#
# See the CONFIGURATION section at the top of this script for details.
#
# The following can be easily customized:
#
#   - Tag columns defined using a 'split letter'
#   - Page title
#   - RSS feed title
#   - Footer links
#   - Number of bookmarks per page
#   - Column Width Adjustments
#
# =====================================================================
# RSS FEED
# =====================================================================
#
# Append new bookmarks to the end of the file.
#
# The RSS feed includes the 10 most recent bookmarks (culled from the
# bottom of your bookmarks.txt file) and is regenerated each time the
# script runs.
#
# =====================================================================
#
# Last updated: 25 August 2026
#