DEV Community: Vigoss Luke

Why I Replaced NotebookLM with a Self-Hosted Alternative (After 2 Weeks of Daily Use)

Vigoss Luke — Mon, 29 Jun 2026 08:29:23 +0000

Why I Replaced NotebookLM with a Self-Hosted Alternative (After 2 Weeks of Daily Use)

I've been a heavy Google NotebookLM user for over a year. The audio overviews, the document chat, the research notebooks — it's genuinely great software. But after hitting its limits one too many times, I finally switched. Here's what pushed me over the edge, and why I'm not going back.

The Three Dealbreakers

1. "Source limit reached" — again.

I was researching a complex topic for a client project and needed to load about 80 sources — PDFs, YouTube transcripts, release notes, API docs. NotebookLM told me I'd hit the 50-source cap. So I deleted some older notes to make room. Then I hit the 500K word limit. This is the worst kind of friction — you're in the middle of deep work, and the tool yanks you out.

2. "Wait, my proprietary design docs are on Google's servers?"

This one hit me during a late-night work session. I'd uploaded internal architecture documents into NotebookLM to generate a podcast overview for the team. Then I realized: all of this — our intellectual property — is sitting on Google's infrastructure with no option to keep it local. For a personal study guide, fine. For actual work? That's a harder conversation with legal.

3. Gemini-only lock-in

NotebookLM is excellent — but it's excellent at what Gemini can do. When Gemini misinterprets technical jargon, there's no "retry with Claude." When the audio overviews sound robotic, there's no "generate with ElevenLabs." You get what Google gives you, end of story.

Enter Open Notebook

I found Open Notebook (formerly Open Notebook LM) while searching for "self-hosted notebooklm alternative" on GitHub. 31K stars. MIT license. Docker setup in two minutes. I was skeptical but figured I'd give it a weekend test.

That weekend turned into two weeks of daily use. Here's what sold me:

1. Docker in 2 minutes. I'm not exaggerating.

mkdir open-notebook && cd open-notebook
curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml
sed -i 's/change-me-to-a-secret-string/YOUR-ENCRYPTION-KEY/' docker-compose.yml
docker compose up -d

Browse to localhost:8502, add your API keys in the Models panel, and you're working. It genuinely takes less time than ordering coffee.

2. Model routing is a superpower I didn't know I needed

This is the feature I use the most. Open Notebook lets you assign different AI models to different tasks:

Summaries → GPT-4o-mini (cheap, fast)
Deep analysis → Claude 3.5 Sonnet or Opus
Private/internal docs → Local Ollama with Qwen 3.6 or Mistral (data never leaves your machine)
Embeddings → text-embedding-3-small (or qwen3-embedding for zero-cost local embeddings)

My API bill for two weeks of heavy use: $6.37. That's less than a NotebookLM Plus monthly sub, and I processed about 3x more content.

3. Multi-speaker podcasts that actually sound different

NotebookLM gives you two AI hosts doing a "deep dive" conversation — which is great until you've heard the same format 50 times. Open Notebook supports 1 to 4 speaker profiles with customizable voices and persona prompts. I can set one speaker as "skeptical technical reviewer," another as "domain expert," and the third as "curious newcomer" — and the resulting conversation actually reflects those perspectives.

4. REST API on port 5055

This is the programmable angle. Need to batch-process 200 PDFs overnight? curl to the API. Want to generate weekly podcasts from a knowledge base automatically? Script it. Something NotebookLM simply cannot do.

curl -X POST http://localhost:5055/api/notebook/process \
  -H "Content-Type: application/json" \
  -d '{"source": "repository", "action": "generate_podcast"}'

The Trade-offs

I won't pretend it's all roses. Here's where NotebookLM still wins:

Citations — NotebookLM's inline citations with exact passage highlighting are much better. Open Notebook gives basic references, but they're working on it.
Zero-setup polish — NotebookLM works the moment you sign in. Open Notebook requires Docker and API keys.
Mobile app — NotebookLM has native apps. Open Notebook's UI works on mobile browsers but isn't optimized.

But for me — a developer working with sensitive documents who needs more than 50 sources and wants to choose my models — these trade-offs are worth it.

Who Should Switch

Developers who hit NotebookLM's source limits regularly
Anyone working with proprietary/confidential documents
Teams who want to choose their AI providers and control costs
People who need to automate document processing via API
Anyone who wants to self-host for data sovereignty

Who Should Stay with NotebookLM

Casual users with fewer than 50 documents
People who need citation-perfect research
Anyone who doesn't want to touch a terminal or Docker
Users who value simplicity over control

After two weeks, I've kept both. NotebookLM for quick public-research throwaway stuff. Open Notebook for everything that matters — client work, internal docs, anything I wouldn't paste into a Google textbox.

If you're a developer who's been frustrated by NotebookLM's limits, give Open Notebook a spin. Docker setup takes two minutes. What you do with it after that is up to you.

🔗 https://localnotebook.dev — Self-hosted NotebookLM alternative, 31K+ GitHub stars, MIT license.

I Tested 5 Open-Source NotebookLM Alternatives — Here's What Actually Works

Vigoss Luke — Sun, 28 Jun 2026 17:59:19 +0000

Google's NotebookLM is great. But handing your research notes, PDFs, and meeting transcripts to Google's cloud is a hard sell for a lot of people — especially when those documents contain client data, unpublished research, or internal strategy.

So I spent a weekend testing five open-source alternatives. Three things mattered: can I docker compose up in under 10 minutes, does the podcast feature actually work offline, and what breaks first?

Here's what I found.

The Contenders

Project	Deploy Time	Min VRAM	True Offline	License
Open Notebook (lfnovo)	~8 min	8 GB	Yes	MIT
Notex (smallnest)	~3 min	4 GB	Yes	Open source
KnowNote (MrSibe)	~2 min	4 GB	Yes	Open source
NotebookLM-Local (nagaforcloud)	~15 min	8 GB	Qwen-3 4B bundled	Open source
InsightsLM (phsphd)	~30 min	8 GB	Yes	N8N SUS license

1. Open Notebook — The One to Beat

git clone https://github.com/lfnovo/open-notebook
cd open-notebook
docker compose up -d

Eight minutes from git clone to the web UI on localhost:3000. It ships with 18+ model providers pre-configured — Ollama, OpenAI, Claude, DeepSeek, Gemini, all selectable per notebook. The podcast generator supports 1-4 speakers with different voices, and it runs entirely offline when you point it at an Ollama backend.

What works:

Document ingestion is fast — SurrealDB's vector + full-text index handles 200-page PDFs without choking
Model switching is genuinely useful — Claude for deep analysis on one notebook, local Qwen for quick summaries on another
Podcast quality with 2 speakers is close to NotebookLM's. 4 speakers is still rough.

What breaks:

Citation highlighting is still being rebuilt (work in progress as of June 2026)
Single-user only — no team/workspace isolation built in
Docker required. No native binary.

2. Notex — Single Binary, Zero Dependencies

Notex is written in Go. You download a single binary (~25MB) and run ./notex. That's it. No Docker, no Python venv, no database setup. It supports PDF, TXT, MD, DOCX, HTML, audio, and YouTube/Bilibili URLs as sources.

Best for: people who want the absolute minimum infrastructure. If Docker is a dealbreaker, Notex is your pick.

What breaks:

Still v0.3.1 — the podcast feature generates a script, not audio. You'll need a separate TTS step.
Smaller community, fewer config examples floating around.

3. KnowNote — Desktop App, No Server

Electron app with SQLite storage. Download, install, open — no terminal needed. Cross-platform (Windows + macOS). If you're setting this up for a non-technical colleague who just wants a "NotebookLM on my laptop," this is the closest to that experience.

Best for: solo users who want zero setup and don't need a web interface.

What breaks:

Desktop-only — no API, no server mode, no sharing.
Early stage — rough edges in the UI, occasional Electron quirks.

4. NotebookLM-Local — The Truly Offline Option

Bundles Qwen-3 4B directly so it runs 100% offline with zero API keys. Uses llama.cpp with Metal acceleration for Apple Silicon. The flat-file vector store means no database to manage.

Best for: privacy maximalists who want everything on-device and don't mind slower inference.

What breaks:

Qwen-3 4B is not Claude. Summaries are functional but shallow compared to cloud models.
macOS/Apple Silicon recommended. CPU-only on Linux works but is very slow.

5. InsightsLM — Powerful but Heavy

Built on Supabase + N8N + React. The no-code workflow engine (N8N) means you can build custom document processing pipelines, auto-tagging, webhook triggers — things the others can't do.

Best for: teams that need programmable document workflows, not just a notebook.

What breaks:

Setup takes 30+ minutes with multiple services. This is not "docker compose up and done."
N8N's Sustainable Use License is not fully open-source for commercial SaaS use. Read the license before building a product on top of it.

What None of Them Handle Well

Production hardening. All five are dev-server default configs:

No HTTPS out of the box
No authentication (single-user, exposed to localhost only)
No backup automation
No monitoring or health checks
No CI/CD for model updates

If you're just exploring for personal use, the defaults are fine. If you're sharing it with your team or depending on it for daily research, you need:

nginx reverse proxy with TLS (Let's Encrypt automated renewal)
restart: unless-stopped + health checks that verify the model is loaded, not just the port
Automated daily backups with off-site storage (B2/S3)
Per-team instance isolation if you have multiple groups

I wrote up the full production deployment flow at localnotebook.dev — the free deployment guide covers getting started, and the Production Manual covers the hardening steps above (10 chapters, Docker Compose → monitoring → 30+ error fixes).

Bottom Line

Want one docker compose up and done? → Open Notebook
Docker is a dealbreaker? → Notex
Setting this up for a non-technical person? → KnowNote
No API keys, no cloud, period? → NotebookLM-Local
Need programmable workflows? → InsightsLM

All five are better than uploading your research to Google. Pick based on your tolerance for Docker and how much you care about podcast quality.

This comparison was done in June 2026. Projects are moving fast — especially Open Notebook which ships updates weekly. Check their repos for the latest.

I Tested 5 Open-Source NotebookLM Alternatives — Here's What Actually Works

Vigoss Luke — Sat, 27 Jun 2026 18:33:22 +0000

Here's what I found.

The Contenders

Project	Deploy Time	Min VRAM	True Offline	License
Open Notebook (lfnovo)	~8 min	8 GB	Yes	MIT
Notex (smallnest)	~3 min	4 GB	Yes	Open source
KnowNote (MrSibe)	~2 min	4 GB	Yes	Open source
NotebookLM-Local (nagaforcloud)	~15 min	8 GB	Qwen-3 4B bundled	Open source
InsightsLM (phsphd)	~30 min	8 GB	Yes	N8N SUS license

1. Open Notebook — The One to Beat

git clone https://github.com/lfnovo/open-notebook
cd open-notebook
docker compose up -d

What works:

Document ingestion is fast — SurrealDB's vector + full-text index handles 200-page PDFs without choking
Model switching is genuinely useful — Claude for deep analysis on one notebook, local Qwen for quick summaries on another
Podcast quality with 2 speakers is close to NotebookLM's. 4 speakers is still rough.

What breaks:

Citation highlighting is still being rebuilt (work in progress as of June 2026)
Single-user only — no team/workspace isolation built in
Docker required. No native binary.

2. Notex — Single Binary, Zero Dependencies

Best for: people who want the absolute minimum infrastructure. If Docker is a dealbreaker, Notex is your pick.

What breaks:

Still v0.3.1 — the podcast feature generates a script, not audio. You'll need a separate TTS step.
Smaller community, fewer config examples floating around.

3. KnowNote — Desktop App, No Server

Best for: solo users who want zero setup and don't need a web interface.

What breaks:

Desktop-only — no API, no server mode, no sharing.
Early stage — rough edges in the UI, occasional Electron quirks.

4. NotebookLM-Local — The Truly Offline Option

Bundles Qwen-3 4B directly so it runs 100% offline with zero API keys. Uses llama.cpp with Metal acceleration for Apple Silicon. The flat-file vector store means no database to manage.

Best for: privacy maximalists who want everything on-device and don't mind slower inference.

What breaks:

Qwen-3 4B is not Claude. Summaries are functional but shallow compared to cloud models.
macOS/Apple Silicon recommended. CPU-only on Linux works but is very slow.

5. InsightsLM — Powerful but Heavy

Built on Supabase + N8N + React. The no-code workflow engine (N8N) means you can build custom document processing pipelines, auto-tagging, webhook triggers — things the others can't do.

Best for: teams that need programmable document workflows, not just a notebook.

What breaks:

Setup takes 30+ minutes with multiple services. This is not "docker compose up and done."
N8N's Sustainable Use License is not fully open-source for commercial SaaS use. Read the license before building a product on top of it.

What None of Them Handle Well

Production hardening. All five are dev-server default configs:

No HTTPS out of the box
No authentication (single-user, exposed to localhost only)
No backup automation
No monitoring or health checks
No CI/CD for model updates

If you're just exploring for personal use, the defaults are fine. If you're sharing it with your team or depending on it for daily research, you need:

nginx reverse proxy with TLS (Let's Encrypt automated renewal)
restart: unless-stopped + health checks that verify the model is loaded, not just the port
Automated daily backups with off-site storage (B2/S3)
Per-team instance isolation if you have multiple groups

Bottom Line

Want one docker compose up and done? → Open Notebook
Docker is a dealbreaker? → Notex
Setting this up for a non-technical person? → KnowNote
No API keys, no cloud, period? → NotebookLM-Local
Need programmable workflows? → InsightsLM

All five are better than uploading your research to Google. Pick based on your tolerance for Docker and how much you care about podcast quality.

This comparison was done in June 2026. Projects are moving fast — especially Open Notebook which ships updates weekly. Check their repos for the latest.

Beyond pip install: MarkItDown in Production

Vigoss Luke — Thu, 11 Jun 2026 04:39:07 +0000

Beyond pip install: MarkItDown in Production

MarkItDown is Microsoft's open-source library for converting documents to Markdown. A single pip install markitdown and you're converting DOCX, PDF, PPTX, and XLSX files in seconds.

But between "it works on my machine" and "it works in production," there's a gap the official docs don't cover.

What Breaks in Production

Silent failures: Encrypted PDFs return empty strings — no error, no warning
No timeout: Large PDFs can hang your pipeline with no way to cancel
Table scrambling: Merged cells and complex layouts lose structure
PDF noise: CID markers, duplicate sentences, zero heading hierarchy
Dependency fragility: Unpinned versions can silently break

What Helps

Batch processing: Reuse a single MarkItDown() instance across hundreds of files
Docker + FastAPI: Production-ready API with file size limits and timeout handling
PDF cleanup pipeline: Python script that strips noise, deduplicates, and restores structure
Right LLM for images: Claude 4 Sonnet wins on detail, GPT-4o wins on chart accuracy

MCP Server Integration

Turn MarkItDown into a Claude Desktop tool — paste a file path in chat and get clean Markdown instantly. No terminal, no scripts.

Full production guide with code, Docker setup, and LLM comparison. Also see the MarkItDown vs Unstructured vs LlamaParse comparison.

MoneyPrinterTurbo — 72K GitHub Stars, Is It Actually Usable?

Vigoss Luke — Thu, 11 Jun 2026 04:37:46 +0000

MoneyPrinterTurbo — 72K GitHub Stars, Is It Actually Usable?

When a GitHub repo hits 72,000 stars by promising "one-click AI video generation," it's worth a closer look. But stars don't tell the whole story.

What It Does

MPT takes a topic, generates a script via LLM, creates voiceover with TTS, pulls stock footage from Pexels, and stitches everything together with subtitles and background music. The result is a polished slideshow-style video — not Sora-style AI generation, but good enough for faceless YouTube channels.

What the Hype Doesn't Tell You

Latest version has no GUI. v1.2.9 is API-only. Beginners need v1.1.0.
Two terminal windows. Backend (FastAPI) + frontend (Streamlit) run separately.
Dependencies break. moviepy 2.0 kills the install. edge-tts renamed half its API.
Free AI providers die. The g4f config everyone recommends no longer works.

The Numbers

Cost per video: $0 (g4f + Edge TTS + Pexels)
Time to produce 1-min video: ~60 seconds
Setup time (reality): 2–4 hours

Verdict

For faceless content channels at zero cost, it's unbeatable. Just don't expect a smooth setup. Follow a guide that covers the real pitfalls.

Full MoneyPrinterTurbo review with 18 documented bugs and fixes, plus a 10-minute setup guide.

DiffusionGemma: Run Google's 4x Faster Diffusion LLM Locally (Full Setup Guide)

Vigoss Luke — Thu, 11 Jun 2026 02:40:03 +0000

DiffusionGemma: Run Google's 4x Faster Diffusion LLM Locally

Google DeepMind just open-sourced DiffusionGemma — and it's not just another Gemma model. It's a fundamentally different way to generate text: diffusion instead of autoregression.

Here's what you need to know to run it on your own machine.

What Makes It Different

Standard LLMs (GPT, Llama, Qwen) generate text one token at a time, left-to-right. Each token depends on all previous tokens, and once it's generated, it's permanent.

DiffusionGemma works like a text version of Stable Diffusion: it fills in 256 tokens at once through iterative denoising. Every token in that block can attend to every other token. If the model loses confidence in a token mid-generation, it can go back and fix it — something autoregressive models fundamentally cannot do.

Tech specs:

26B parameters total, 3.8B activated (Mixture of Experts)
256K context window, 140+ languages
Apache 2.0 license — truly open, no usage restrictions
Multimodal: text + image + video inputs

The Speed Difference

Hardware	Tokens/s	Quantization	Source
H200	1,288	BF16	vLLM (verified)
H100	~1,000+	BF16	Google (self-reported)
RTX 5090	~700+	NVFP4	Google (self-reported)
RTX 4090	~200-400	Q4_K_M	Community estimate

⚡️ This is a fundamentally different speed tier from autoregressive models — a 26B-class model running at 700+ tokens/s on a single GPU.

3 Ways to Run It

Method 1: vLLM (Fastest)

pip install vllm>=0.12.0

from vllm import LLM, SamplingParams

llm = LLM(
    model="google/diffusiongemma-26B-A4B-it",
    trust_remote_code=True,
    tensor_parallel_size=1,
    max_model_len=65536,
)

sampling_params = SamplingParams(temperature=0.7, max_tokens=2048)
outputs = llm.generate(["Explain how diffusion language models work."], sampling_params)

vLLM has day-zero optimized support with dedicated block-denoising kernels. This is the gold standard for production inference.

Method 2: llama.cpp (For GGUF quantization)

llama.cpp support is via PR #24427 — not merged yet, but functional:

git clone https://github.com/ggml-ai/llama.cpp
cd llama.cpp
git fetch origin pull/24427/head:diffusiongemma
git checkout diffusiongemma
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

Then download a GGUF quantized weight and run:

./build/bin/llama-cli \
  -m DiffusionGemma-26B-A4B-it-Q4_K_M.gguf \
  -p "Explain how diffusion language models work." \
  -n 512 -ngl 99

Method 3: HuggingFace Transformers (Simplest)

pip install transformers>=4.55.0 accelerate

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model = AutoModelForCausalLM.from_pretrained(
    "google/diffusiongemma-26B-A4B-it",
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

Quantization Guide

Method	VRAM	Quality	Best For
NVFP4	~15GB	Near-lossless	RTX 5090 / Blackwell only
Bitsandbytes 4-bit	~16GB	Good	RTX 3090/4090
GGUF Q4_K_M	~16GB	Good	llama.cpp users
BF16	~52GB	Full	H100/A100

The Honest Tradeoffs

What it's great at:

Short-form generation (1-2 paragraphs): quality competitive with Gemma 4
Summarization and translation (140+ languages)
Data augmentation / synthetic text: throughput >> autoregressive
Real-time interactive applications: sub-100ms latency feels instant

Where it falls short:

Complex reasoning (math, logic, multi-hop): significantly below Gemma 4
Long-form writing (3+ paragraphs): coherence degrades after block boundaries
Code generation: functional for snippets, struggles with multi-file code

Hardware caveat: The speed advantage requires high-compute GPUs (RTX 3090+). Apple Silicon Macs and entry-level GPUs won't see the 4x speedup — Google explicitly warns about this in their blog.

Should You Try It?

✅ Yes, if you have RTX 4090/5090 and need high-throughput generation
✅ Yes, if you're generating synthetic data at scale
✅ Yes, if you're curious about diffusion LLMs as a research direction

❌ No, if you need top-tier reasoning or code quality
❌ No, if you're on Apple Silicon (the speed advantage evaporates)
❌ No, if you need Ollama support (not available yet)

Full Guide

I built a complete deployment guide with hardware requirements, troubleshooting, and honest benchmarks at diffusiongemma.dev — 4 deployment methods with copy-paste commands.

Published 2026-06-11. Model released by Google DeepMind under Apache 2.0.

I Built a World Cup 2026 Interactive Venue Map with Leaflet.js — Here's the Code

Vigoss Luke — Tue, 09 Jun 2026 08:32:10 +0000

I Built a World Cup 2026 Interactive Venue Map with Leaflet.js — Here's the Code

World Cup 2026 kicks off in 3 days. 48 teams, 16 stadiums across the US, Canada, and Mexico. I wanted to see where all the matches were happening — not on a static image, not in a slow third-party iframe, but on a fast, zoomable, clickable map that I actually built myself.

So I spent an afternoon with Leaflet.js and Cloudflare Pages. Here's what came out of it.

Why Another Map?

I searched "World Cup 2026 stadiums map" and found:

A Mapme embed that took 4 seconds to load
A ZeeMaps link with ads all over it
A bunch of JPG images with tiny text

None of them let you click a stadium and see all the matches happening there. None were fast. None felt like they were built by someone who actually wanted to use them.

So I built my own. The goal: load in under 500ms, run on a phone, and let you tap any stadium to see every match.

The Stack: Leaflet.js, JSON, and Nothing Else

No React. No Next.js. No API. No backend.

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

That's it. Two CDN links, a single HTML file, a JSON blob of stadiums and matches, and Cloudflare Pages to serve it.

The Stadium Data

I structured everything as a flat JSON array. Each stadium has coordinates, capacity, and its match list:

const stadiums = [
  {
    name: "MetLife Stadium",
    city: "East Rutherford, NJ",
    coords: [40.8136, -74.0744],
    capacity: 82500,
    matches: [
      { date: "2026-07-19", stage: "Final", time: "15:00 ET" },
      { date: "2026-06-13", stage: "Group C", teams: "Brazil vs Morocco" },
      { date: "2026-06-22", stage: "Group I", teams: "Norway vs Senegal" },
      { date: "2026-07-05", stage: "Round of 32", teams: "TBD" },
      { date: "2026-07-05", stage: "Round of 16", teams: "TBD" }
    ]
  },
  // ... 15 more stadiums
];

The JSON is about 4KB. That's the entire data layer. No database, no API calls, nothing to go down.

The Map Init

Leaflet makes this embarrassingly simple:

const map = L.map('map').setView([39.8, -98.5], 4);

L.tileLayer('https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png', {
  attribution: '&copy; OpenStreetMap contributors',
  maxZoom: 18
}).addTo(map);

Centered on middle America at zoom 4 so all three countries fit on screen. CartoDB's light tiles keep it clean — no visual noise competing with the stadium markers.

Adding the Markers

For each stadium, I create a custom marker with a football emoji and bind a popup:

stadiums.forEach(stadium => {
  const icon = L.divIcon({
    html: '⚽',
    className: 'stadium-marker',
    iconSize: [32, 32],
    iconAnchor: [16, 16]
  });

  const matchList = stadium.matches.map(m =>
    `<div class="match-row">
      <span class="match-date">${m.date}</span>
      <span class="match-stage">${m.stage}</span>
      <span class="match-teams">${m.teams || m.stage}</span>
    </div>`
  ).join('');

  const marker = L.marker(stadium.coords, { icon })
    .bindPopup(`
      <div class="stadium-popup">
        <h3>${stadium.name}</h3>
        <p class="stadium-location">${stadium.city} · ${stadium.capacity.toLocaleString()} seats</p>
        <div class="match-schedule">${matchList}</div>
        <a class="popup-link" href="https://www.fifa.com/en/tournaments/mens/worldcup/canadamexicousa2026/scores-fixtures" target="_blank">
          Full schedule →
        </a>
      </div>
    `)
    .addTo(map);
});

The divIcon with an emoji is a cheat code — no custom image assets, no sprite sheet, just one character that renders perfectly at any zoom level.

Mobile Matters

The one CSS tweak that made a real difference:

.stadium-marker {
  font-size: 28px;
  text-align: center;
  line-height: 32px;
  cursor: pointer;
  -webkit-tap-highlight-color: transparent;
}

.leaflet-popup-content {
  min-width: 240px;
  max-width: 320px;
  font-size: 14px;
}

.match-row {
  display: flex;
  justify-content: space-between;
  padding: 4px 0;
  border-bottom: 1px solid #eee;
  font-size: 13px;
}

On desktop, it's a map. On a phone, it's still a functional tap-to-explore experience. The 32×32px tap target on markers is right at the recommended minimum — I didn't want to inflate them and lose precision when markers are close.

What I Learned

You don't need a framework to ship a useful interactive tool in an afternoon.

The entire project is:

1 HTML file (147 lines)
1 JSON data file (4KB)
2 CDN links
Deployed to Cloudflare Pages in 30 seconds

No build step. No npm install. No state management to debug. Just a map that loads fast and does exactly one thing well.

The real lesson: Leaflet.js in 2026 is still the best tool for this kind of project. It hasn't had a major version bump in years, and that's a feature — the API is stable, the docs are complete, and it just works.

The Bigger Picture

I've been on a kick lately of building lightweight, single-purpose tools. If you're into that kind of thing, I've also been writing about:

TokenCut — practical ways to cut your AI coding token costs by 30-50%, including a breakdown of why Markdown is 3-8x more token-efficient than HTML for LLM pipelines
MarkItDown Pro — batch-converting hundreds of documents to clean Markdown for LLM ingestion, using Microsoft's open-source converter

The common thread: build small, ship fast, and let the tool do one thing really well.

World Cup kicks off June 11. If you want to build your own map, grab the full code from the companion repo below. You've got 3 days — that's 2.5 more than you need.

GitHub: github.com/Jakeshadow/world-cup-venue-map
Live map: wc26-map.pages.dev
More tools: tokencut.org · markitdown-pro.com

How I Batch-Convert 100+ Documents to Markdown for LLM Ingestion — 3 Practical Scripts

Vigoss Luke — Tue, 09 Jun 2026 06:31:45 +0000

How I Batch-Convert 100+ Documents to Markdown for LLM Ingestion — 3 Practical Scripts

I had 300 PDFs, 50 DOCX files, and a pile of PPTX decks sitting in a directory — all the internal docs from three years of client projects. I needed clean Markdown for my LLM pipeline, and "open one by one and copy-paste" wasn't going to cut it.

Here's how I got it done in an afternoon with MarkItDown and three scripts.

Why Markdown Matters for LLMs

Before showing the code, let's talk about why this matters. LLMs charge by the token. Here's what that looks like in practice:

# HTML — 23 tokens just for the boilerplate
'<h1 class="title" id="intro">Introduction</h1>'

# Markdown — 3 tokens for the same heading
'# Introduction'

That's a 7.6x efficiency gap on every heading, every paragraph wrapper, every table cell. When you're processing hundreds of documents into an LLM context window, the difference between raw HTML and clean Markdown can mean 3–8x fewer tokens. That translates directly to lower API costs, faster inference, and more documents fitting into a single context window.

MarkItDown is Microsoft's open-source document-to-Markdown converter — 140K+ GitHub stars, MIT licensed, and gaining ~200 stars a day. It handles PDF, DOCX, PPTX, Excel, and 10+ other formats, all converting to clean, consistent Markdown.

Script 1: batch_convert.py — Recursive Directory Converter

This is the workhorse. Point it at a directory, and it recursively finds every supported file, converts it, and drops the .md next to the original.

#!/usr/bin/env python3
"""Batch convert documents to Markdown using MarkItDown."""
import argparse
import sys
from pathlib import Path
from markitdown import MarkItDown

SUPPORTED_EXTENSIONS = {
    '.pdf', '.docx', '.pptx', '.xlsx', '.html', '.htm',
    '.csv', '.json', '.xml', '.zip', '.msg', '.eml',
    '.rtf', '.odt', '.ods', '.odp', '.epub',
}


def collect_files(root: Path) -> list[Path]:
    """Recursively collect all supported files."""
    files = []
    for path in root.rglob('*'):
        if path.is_file() and path.suffix.lower() in SUPPORTED_EXTENSIONS:
            files.append(path)
    return files


def convert_file(md: MarkItDown, input_path: Path, output_path: Path) -> bool:
    """Convert a single file to Markdown. Returns True on success."""
    try:
        result = md.convert(str(input_path))
        output_path.write_text(result.text_content, encoding='utf-8')
        return True
    except Exception as e:
        print(f"  ✗ {input_path.name}: {e}", file=sys.stderr)
        return False


def main():
    parser = argparse.ArgumentParser(
        description="Batch convert documents to Markdown"
    )
    parser.add_argument('directory', type=Path,
                        help='Root directory to scan recursively')
    parser.add_argument('--output-dir', type=Path, default=None,
                        help='Output directory (mirrors source structure)')
    parser.add_argument('--dry-run', action='store_true',
                        help='List files without converting')
    args = parser.parse_args()

    if not args.directory.is_dir():
        print(f"Error: {args.directory} is not a directory", file=sys.stderr)
        sys.exit(1)

    files = collect_files(args.directory)
    if not files:
        print(f"No supported files found in {args.directory}")
        return

    print(f"Found {len(files)} file(s) to convert:")
    for f in files:
        print(f"  {f.relative_to(args.directory)}")

    if args.dry_run:
        return

    md = MarkItDown()
    success = 0
    for input_path in files:
        rel = input_path.relative_to(args.directory)
        if args.output_dir:
            output_path = args.output_dir / rel.with_suffix('.md')
            output_path.parent.mkdir(parents=True, exist_ok=True)
        else:
            output_path = input_path.with_suffix('.md')

        print(f"Converting {rel}...", end=' ')
        if convert_file(md, input_path, output_path):
            print("✓")
            success += 1

    print(f"\nDone: {success}/{len(files)} converted successfully.")


if __name__ == '__main__':
    main()

Usage is dead simple:

pip install markitdown
python batch_convert.py ./client-docs --output-dir ./markdown-output

Point it at a directory, it recursively finds every PDF, DOCX, PPTX, Excel, HTML, CSV, JSON, XML, email, RTF, ODF, and EPUB file, converts each one, and mirrors the directory structure in the output folder.

Script 2: server.py — When You Need an API Instead of CLI

Sometimes you're building a pipeline and need to trigger conversions via HTTP — from an n8n workflow, a Zapier webhook, or your own frontend. Here's a FastAPI wrapper that exposes MarkItDown as a REST API:

#!/usr/bin/env python3
"""FastAPI server wrapping MarkItDown for API-based conversion."""
import tempfile
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile, File, HTTPException
from fastapi.responses import PlainTextResponse
from markitdown import MarkItDown

app = FastAPI(title="MarkItDown API", version="1.0.0")
converter = MarkItDown()

SUPPORTED_CONTENT_TYPES = {
    'application/pdf', 'application/vnd.openxmlformats-officedocument.'
    'wordprocessingml.document', 'application/vnd.openxmlformats-officedocument.'
    'presentationml.presentation', 'application/vnd.openxmlformats-officedocument.'
    'spreadsheetml.sheet', 'text/html', 'text/csv', 'application/json',
    'text/xml', 'application/zip', 'message/rfc822', 'text/rtf',
    'application/epub+zip', 'application/vnd.oasis.opendocument.text',
}


@app.post("/convert", response_class=PlainTextResponse)
async def convert_file(file: UploadFile = File(...)):
    """Upload a document, get back Markdown."""
    if file.content_type and file.content_type not in SUPPORTED_CONTENT_TYPES:
        raise HTTPException(
            status_code=415,
            detail=f"Unsupported type: {file.content_type}"
        )

    suffix = Path(file.filename).suffix if file.filename else '.tmp'
    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
        shutil.copyfileobj(file.file, tmp)
        tmp_path = Path(tmp.name)

    try:
        result = converter.convert(str(tmp_path))
        return result.text_content
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
    finally:
        tmp_path.unlink(missing_ok=True)


@app.get("/health")
async def health():
    return {"status": "ok", "formats": sorted(SUPPORTED_CONTENT_TYPES)}


if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Now any service in your stack can POST a file and get Markdown back:

curl -X POST http://localhost:8000/convert \
  -F "file=@report.docx"

Script 3: pdf_cleanup.py — Post-Processing for Messy PDFs

PDF conversion is where things get ugly. Scanned documents come out as empty strings, multi-column layouts produce jumbled text, and watermarks get scattered through the output. This script cleans up the most common artifacts:

#!/usr/bin/env python3
"""Post-process MarkItDown output for cleaner LLM-ready text."""
import re
import sys
from pathlib import Path


def clean_markdown(text: str) -> str:
    """Apply a pipeline of cleanup operations."""

    # Collapse 3+ blank lines into 2
    text = re.sub(r'\n{3,}', '\n\n', text)

    # Strip trailing whitespace on each line
    text = re.sub(r'[ \t]+$', '', text, flags=re.MULTILINE)

    # Remove lines that are entirely non-alphanumeric (watermarks, separators)
    text = re.sub(
        r'^\s*[^a-zA-Z0-9\u4e00-\u9fff]{3,}\s*$',
        '',
        text,
        flags=re.MULTILINE
    )

    # Fix broken hyphenation: "con-\nvert" → "convert"
    text = re.sub(r'(\w)-\n(\w)', r'\1\2', text)

    # Merge single-line-break paragraphs that aren't actually separate
    # (keeps intentional blank-line paragraph separators)
    text = re.sub(
        r'([^\n])\n([^\n#\-\*\d\s])',
        r'\1 \2',
        text
    )

    # Normalize Unicode quotes and dashes
    text = text.replace('\u2018', "'").replace('\u2019', "'")
    text = text.replace('\u201c', '"').replace('\u201d', '"')
    text = text.replace('\u2013', '--').replace('\u2014', '---')

    return text.strip()


def main():
    import argparse
    parser = argparse.ArgumentParser(
        description='Clean up MarkItDown output for LLM use'
    )
    parser.add_argument('files', type=Path, nargs='+',
                        help='Markdown files to clean')
    parser.add_argument('--in-place', action='store_true',
                        help='Modify files in place')
    parser.add_argument('--output-dir', type=Path, default=None,
                        help='Write cleaned files to a separate directory')
    args = parser.parse_args()

    for filepath in args.files:
        if not filepath.suffix == '.md':
            print(f"Skipping non-markdown file: {filepath}")
            continue

        raw = filepath.read_text(encoding='utf-8')
        cleaned = clean_markdown(raw)

        if args.output_dir:
            out = args.output_dir / filepath.name
            out.write_text(cleaned, encoding='utf-8')
        elif args.in_place:
            filepath.write_text(cleaned, encoding='utf-8')
        else:
            print(f"=== {filepath.name} ===")
            print(cleaned)
            print()

        savings = len(raw) - len(cleaned)
        if savings > 0:
            print(f"  {filepath.name}: removed {savings} chars ({savings * 100 // len(raw)}%)")


if __name__ == '__main__':
    main()

Run it after batch_convert to clean up all your output:

python pdf_cleanup.py ./markdown-output/*.md --in-place

Docker Option: One Command, Zero Setup

If you don't want to deal with Python environments (looking at you, PDF dependencies), everything's containerized:

git clone https://github.com/Jakeshadow/markitdown-batch-examples.git
cd markitdown-batch-examples

# Mount your documents and run
docker compose run --rm -v /path/to/docs:/input converter \
  python batch_convert.py /input --output-dir /input/markdown

The Docker image includes all the heavy dependencies (pdfminer, python-docx, openpyxl) so you don't fight with system libraries.

MarkItDown vs Unstructured.io: When to Use Which

I evaluated both before committing to MarkItDown. Here's the quick breakdown:

MarkItDown: MIT license, Python-native, dead simple API (md.convert("file.pdf")), produces clean semantic Markdown. Best for batch conversion pipelines where you want LLM-ready output with zero configuration.
Unstructured.io: Apache 2.0, supports more esoteric formats (JPG OCR, EML parsing with metadata), but heavier dependencies and more complex setup. Better if you need structured chunking metadata alongside the text.

For my use case — batch converting internal docs for LLM pipelines — MarkItDown won on simplicity and output quality. No configuration files, no partitioning strategies to configure. Just point it at a file and get Markdown.

Full comparison with code examples on both sides: MarkItDown vs Unstructured.io.

The Takeaway

Three scripts, one afternoon, and 300+ documents went from a mess of proprietary formats to clean, token-efficient Markdown. The whole pipeline is:

batch_convert.py — mass conversion of everything in a directory
pdf_cleanup.py — post-process to fix PDF artifacts
server.py — REST API when you need programmatic access

The full guide with installation walkthroughs, Docker setup, and performance benchmarks is at markitdown-pro.com. All three scripts plus Docker Compose files are in the GitHub companion repo.

Stop opening files one by one. Let the scripts do it.

Deploying Hermes WebUI with Docker — The 8 Errors I Hit and How to Fix Them

Vigoss Luke — Tue, 09 Jun 2026 06:28:42 +0000

Deploying Hermes WebUI with Docker — The 8 Errors I Hit and How to Fix Them

I needed a web UI for the Hermes Agent. Docker Compose looked simple. Eight errors later, I had a working deployment — and a collection of scars I'm about to save you from.

What's Hermes WebUI?

Hermes WebUI is a self-hosted web interface for the Hermes Agent — an open-source AI agent framework with 140K+ GitHub stars and 2.9 trillion daily tokens served through OpenRouter. It's the browser-based dashboard you need to chat with your agent, manage conversations, and monitor usage, all from a Docker container.

The 5-Minute Happy Path

Before we dive into the errors, here's what should happen:

git clone https://github.com/Jakeshadow/hermes-webui-docker-examples.git
cd hermes-webui-docker-examples/single-container
# Create a .env file with your API keys (see .env.example)
docker compose up -d

Open http://localhost:3000, and you're chatting with your Hermes Agent. This actually works for most people on Linux. But if you're on macOS, RHEL, or doing anything slightly custom — buckle up.

Error #1: UID/GID Mismatch (The Silent Killer)

Symptoms: Container starts fine. You mount a volume for persistent data. The container can't write to it — permission denied, or worse, it writes but you can't see the files on your host.

Root cause: The Docker container runs as user UID 1000 (standard Linux user). macOS users run as UID 501. Linux users might be UID 1000, but their GID could be anything. When the container writes files with UID 1000, your host user can't read them.

The fix — set WANTED_UID and WANTED_GID in your .env file:

# .env
WANTED_UID=501
WANTED_GID=20

On macOS, check your UID/GID:

id -u   # usually 501
id -g   # usually 20

On Linux:

id -u   # usually 1000
id -g   # usually 1000

The entrypoint script picks up these variables and creates a matching user inside the container. No more permission whack-a-mole.

Error #2: Empty Mounted Directories

Symptoms: You mount ./data:/app/data, the container starts, but ./data on your host stays empty even though the app seems to be running fine.

Root cause: Docker volume mounts work in one direction at container creation. If you mount an empty host directory to a non-empty container path, the empty host directory wins — it overlays and hides whatever was in the container.

The fix: Pre-create the expected directory structure on the host first, or let the entrypoint script handle initialization after the mount. With Hermes WebUI, the companion repo includes a scripts/init-data.sh that handles this. Run it once:

./scripts/init-data.sh
docker compose up -d

For a deep dive on Docker volume mounting behavior, check out the detail page on hermesdocker.com.

Error #3: `docker_mount_cwd_to_workspace` Permission Errors

Symptoms: You're using the three-container production setup, and the workspace mount throws errors like Permission denied: /workspace. The gateway container can't access files that clearly exist on the host.

Root cause: This one is a double-whammy. First, the UID/GID issue from Error #1 applies here too. Second, the Docker socket proxy doesn't inherit the right file permissions when the mount crosses container boundaries in the three-container setup.

The fix: Make sure .env has matching UID/GID across all containers, not just the web UI. In the three-container setup:

# Applies to webui, gateway, AND hermes-agent containers
WANTED_UID=1000
WANTED_GID=1000

Then rebuild:

docker compose down
docker compose up -d --build

Error #4: SELinux on RHEL/Fedora

Symptoms: Everything looks right, but the container can't access any mounted volumes. Logs show avc: denied messages.

Root cause: SELinux labels on the host directory block container access.

The fix — add :Z to your volume mounts in docker-compose.yml:

volumes:
  - ./data:/app/data:Z
  - ./workspace:/workspace:Z

The :Z flag tells Docker to relabel the directory for container access. Use :z if multiple containers share the same volume, :Z if it's exclusive to one container.

Why I Chose This Over Open WebUI

I compared Hermes WebUI with Open WebUI before committing. The short version: Open WebUI is feature-rich but heavy — it bundles RAG, document parsing, and a web search engine into one container. Hermes WebUI is focused: it does the agent chat interface and does it well, with three deployment modes that scale from a single Docker command to a production-grade multi-container setup.

The three modes matter:

Single-container: One docker compose up -d, perfect for testing
Dual-container: Separates the web UI from the gateway for cleaner isolation
Three-container: Full production setup with isolated gateway, agent runtime, and web UI

If you want the full comparison breakdown, there's a dedicated page on Hermes WebUI vs Open WebUI.

The Takeaway

Docker makes deployment look deceptively simple — until you hit a permission error at 11 PM. The eight errors I hit all boil down to three root causes: user ID mismatches between host and container, volume mount directionality, and SELinux on enterprise distros. Fix those three and you're golden.

All the working Docker Compose files (single, dual, and three-container modes) are in the GitHub companion repo. Clone it, set your .env, and skip the debugging I already did for you.

Happy deploying.

5 Ways to Reduce Token Usage (That Actually Work)

Vigoss Luke — Wed, 03 Jun 2026 14:45:48 +0000

5 Ways to Reduce Token Usage (That Actually Work)

Your AI coding tool is burning tokens on things you don't need. Here's how to cut 30–50% of your token spend — each method includes a real tool you can use today.

Why Token Usage Is Eating Your Budget

Every prompt, every file read, every thinking step costs tokens. Most developers bleed money on three invisible leaks: routing expensive models to trivial tasks, letting context balloon past 80%, and re-reading the same files repeatedly.

The 5 Methods

01 — Route Cheap Models to Simple Tasks
90% of your daily AI work doesn't need Opus. File lookups, variable renames — that's Haiku. Set your default to Sonnet, subagents to Haiku. Savings: 20–50%.

02 — Compact Before Context Explodes
Default compaction threshold is 95% — way too late. Drop it to 50%. Savings: 10–20%.

03 — ECC (Recommended)
Everything Claude Code automates all optimizations: model routing, thinking token caps (10K vs 32K default), compaction triggers. 182K+ GitHub stars, Anthropic Hackathon winner. One install covers Methods 01 and 02 out of the box. Savings: 30–50%.

04 — Trim Your CLAUDE.md
Every line loads into every conversation. Cut from 500 to 10. Savings: 10–30%.

05 — Search First, Read Later
Use grep/glob to locate, Read only what you need. Savings: 20–40%.

The Numbers

Method	Effort	Token Savings	Works With
01 Model Routing	5 min config	20–50%	CC, Cursor, Codex
02 Strategic Compaction	2 min config	10–20%	Claude Code
03 ECC (Recommended)	1 min install	30–50%	CC, Cursor, Codex, Gemini, Copilot
04 Trim Rules	30 min audit	10–30%	Any AI coding tool
05 Search First	Behavior change	20–40%	CC, Cursor, Codex

Pro tip: Start with ECC — it automates the first two methods out of the box.

Full guide with code snippets and FAQ: https://tokencut.org/

DEV Community: Vigoss Luke

Why I Replaced NotebookLM with a Self-Hosted Alternative (After 2 Weeks of Daily Use)

Why I Replaced NotebookLM with a Self-Hosted Alternative (After 2 Weeks of Daily Use)

The Three Dealbreakers

Enter Open Notebook

1. Docker in 2 minutes. I'm not exaggerating.

2. Model routing is a superpower I didn't know I needed

3. Multi-speaker podcasts that actually sound different

4. REST API on port 5055

The Trade-offs

Who Should Switch

Who Should Stay with NotebookLM

I Tested 5 Open-Source NotebookLM Alternatives — Here's What Actually Works

The Contenders

1. Open Notebook — The One to Beat

2. Notex — Single Binary, Zero Dependencies

3. KnowNote — Desktop App, No Server

4. NotebookLM-Local — The Truly Offline Option

5. InsightsLM — Powerful but Heavy

What None of Them Handle Well

Bottom Line

I Tested 5 Open-Source NotebookLM Alternatives — Here's What Actually Works

The Contenders

1. Open Notebook — The One to Beat

2. Notex — Single Binary, Zero Dependencies

3. KnowNote — Desktop App, No Server

4. NotebookLM-Local — The Truly Offline Option

5. InsightsLM — Powerful but Heavy

What None of Them Handle Well

Bottom Line

Beyond pip install: MarkItDown in Production

Beyond pip install: MarkItDown in Production

What Breaks in Production

What Helps

MCP Server Integration

MoneyPrinterTurbo — 72K GitHub Stars, Is It Actually Usable?

MoneyPrinterTurbo — 72K GitHub Stars, Is It Actually Usable?

What It Does

What the Hype Doesn't Tell You

The Numbers

Verdict

DiffusionGemma: Run Google's 4x Faster Diffusion LLM Locally (Full Setup Guide)

DiffusionGemma: Run Google's 4x Faster Diffusion LLM Locally

What Makes It Different

The Speed Difference

3 Ways to Run It

Method 1: vLLM (Fastest)

Method 2: llama.cpp (For GGUF quantization)

Method 3: HuggingFace Transformers (Simplest)

Quantization Guide

The Honest Tradeoffs

Should You Try It?

Full Guide

I Built a World Cup 2026 Interactive Venue Map with Leaflet.js — Here's the Code

I Built a World Cup 2026 Interactive Venue Map with Leaflet.js — Here's the Code

Why Another Map?

The Stack: Leaflet.js, JSON, and Nothing Else

The Stadium Data

The Map Init

Adding the Markers

Mobile Matters

What I Learned

The Bigger Picture

How I Batch-Convert 100+ Documents to Markdown for LLM Ingestion — 3 Practical Scripts

How I Batch-Convert 100+ Documents to Markdown for LLM Ingestion — 3 Practical Scripts

Why Markdown Matters for LLMs

Script 1: batch_convert.py — Recursive Directory Converter

Script 2: server.py — When You Need an API Instead of CLI

Script 3: pdf_cleanup.py — Post-Processing for Messy PDFs

Docker Option: One Command, Zero Setup

MarkItDown vs Unstructured.io: When to Use Which

The Takeaway

Deploying Hermes WebUI with Docker — The 8 Errors I Hit and How to Fix Them

Deploying Hermes WebUI with Docker — The 8 Errors I Hit and How to Fix Them

What's Hermes WebUI?

The 5-Minute Happy Path

Error #1: UID/GID Mismatch (The Silent Killer)

Error #2: Empty Mounted Directories

Error #3: docker_mount_cwd_to_workspace Permission Errors

Error #4: SELinux on RHEL/Fedora

Error #3: `docker_mount_cwd_to_workspace` Permission Errors