The Unhinged Librarian

← Back to Library Pop-Up Tools

Reading List Formatter (reading_list_formatter.py)

This tool turns a plain text list of books into a Markdown bullet list, ready to paste into email, a website, or a guide.

How It Works (In Plain Language)

  • Reads your text file line by line, ignoring any completely blank lines.
  • Tries a few simple patterns: “Title - Author”, “Author: Title”, or just “Title”.
  • Splits the line into a title and an author based on those patterns.
  • Builds a bullet list where each line looks like - *Title*: Author (or just - *Title* if no author).
  • Writes the result into a new .md file that you can open and copy into other places.

How to Use

  1. Create a simple text file (for example my_list.txt) with one book per line.
  2. Place it in this folder.
  3. Open Terminal and run: cd ~/Desktop/library_pop_up_tools
  4. Then run: python reading_list_formatter.py my_list.txt reading_list.md
  5. Open reading_list.md to copy and paste the bulleted list.
library_pop_up_tools % python reading_list_formatter.py my_list.txt reading_list.md
Formatted reading list written to: reading_list.md

Optional: Adjust Line Patterns

The tool currently understands three simple patterns: Title - Author, Author: Title, or just Title. You can change these if your lists follow a different style. 

def parse_line(line: str) -> tuple[str, str]:
    raw = line.strip()
    if not raw:
        return "", ""

    if " - " in raw:
        title, author = raw.split(" - ", 1)
        return title.strip(), author.strip()

    if ":" in raw:
        author, title = raw.split(":", 1)
        return title.strip(), author.strip()

    return raw, ""

If your notes use a different separator (for example Title | Author), you can adjust this function in reading_list_formatter.py.

Full Python Source (Optional)

Click to show the full script 
#!/usr/bin/env python3
"""
reading_list_formatter.py

Pop-up tool to turn a messy text list of titles/authors into a simple,
clean reading list in Markdown.

Input: a plain text file, one item per line.
Formats supported:
    - Title - Author
    - Author: Title
    - Just a title

Output: a Markdown file with bullet points.

Example:
    python reading_list_formatter.py raw_list.txt reading_list.md
"""

import sys
from pathlib import Path


def parse_line(line: str) -> tuple[str, str]:
    raw = line.strip()
    if not raw:
        return "", ""

    if " - " in raw:
        title, author = raw.split(" - ", 1)
        return title.strip(), author.strip()

    if ":" in raw:
        author, title = raw.split(":", 1)
        return title.strip(), author.strip()

    return raw, ""


def format_reading_list(input_path: Path, output_path: Path) -> None:
    lines = input_path.read_text(encoding="utf-8").splitlines()
    output_lines: list[str] = []

    for line in lines:
        title, author = parse_line(line)
        if not title:
            continue
        if author:
            output_lines.append(f"- *{title}*: {author}")
        else:
            output_lines.append(f"- *{title}*")

    output_path.write_text("\n".join(output_lines) + "\n", encoding="utf-8")


def main(argv: list[str]) -> int:
    if len(argv) != 3:
        print("Usage: python reading_list_formatter.py raw_list.txt reading_list.md")
        return 1
    input_path = Path(argv[1]).expanduser()
    output_path = Path(argv[2]).expanduser()
    if not input_path.exists():
        print(f"Input file not found: {input_path}")
        return 1
    format_reading_list(input_path, output_path)
    print(f"Formatted reading list written to: {output_path}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

← Back to all tools