DEV Community: Vigoss Luke

npm v12 Just Shipped — Here's What Broke in My CI and How I Fixed It

Vigoss Luke — Thu, 09 Jul 2026 08:23:21 +0000

npm v12 hit stable on July 8. Within 12 hours, three of our CI pipelines were red. Not yellow — red. And the worst part: one of them was green for 4 hours before anyone noticed the deploy was shipping broken containers.

Here's exactly what broke, why it was silent, and how to fix each one.

The One That Scared Me: `npm ci` Exits 0, Native Modules Never Compiled

This is the trap. Your CI runs npm ci, it exits with code 0. Docker build succeeds. Container deploys. App starts. Everything looks fine — until the first request that hits a native module.

Error: Cannot find module './build/Release/sharp.node'

Here's what happened under the hood:

npm ci
# v12 behavior: encounters sharp's install script
# → script blocked (not in allowlist)
# → no error, no warning in exit code
# → npm ci exits 0
# → node_modules/sharp exists, but build/Release/ is empty

The fix isn't --allow-scripts=all in CI. That defeats the purpose. The fix is:

# Step 1: Audit your actual script needs
npm approve-scripts --allow-scripts-pending

# Step 2: This prints the real list — usually 3-8 packages, not 200
# Example output:
#   sharp (postinstall: node-gyp rebuild)
#   esbuild (postinstall: node install.js)
#   @swc/core (postinstall: node postinstall.js)

# Step 3: Approve the ones you trust
npm approve-scripts sharp esbuild @swc/core

# Step 4: Commit the allowlist
git add package.json  # allowScripts field is now populated
git commit -m "add npm v12 script allowlist"

The allowlist lives in package.json under the allowScripts key. It's scoped — if a package isn't in the list, its scripts don't run. Commit it. Your CI will pick it up from the committed package.json with no .npmrc changes needed.

But here's the subtlety: you must run the audit on the same OS and Node version as CI. node-gyp rebuild is conditional — a package might run scripts on Linux but not macOS. Run npm approve-scripts --allow-scripts-pending in a Docker container that matches your CI environment, or you'll miss scripts that only fire on Linux.

The CI Pipeline That Passed Green But Shipped Broken Code

We had a GitHub Actions workflow like this:

- name: Install dependencies
  run: npm ci

- name: Build
  run: npm run build

- name: Test
  run: npm test

All three steps passed. The problem: npm ci skipped sharp's postinstall (node-gyp rebuild), and our test suite didn't exercise image processing — it mocked the sharp module. Unit tests passed, but the running app crashed on the first real image upload.

The fix: add a smoke test after npm ci.

- name: Install dependencies
  run: npm ci

- name: Smoke test — native modules
  run: |
    node -e "
      const sharp = require('sharp');
      console.log('sharp loaded:', sharp.versions);
    " || (echo 'NATIVE MODULE NOT COMPILED — check allowlist' && exit 1)

- name: Build
  run: npm run build

- name: Test
  run: npm test

This catches silent native module failures before the build step. Do this for every native dependency that's critical to your app — sharp, bcrypt, canvas, node-sass, @swc/core, esbuild, prisma, better-sqlite3. One smoke test per native dep, run immediately after npm ci. Add it to your CI template. The first time it catches a silent skip, you'll thank yourself.

If you run monorepo CI, put this in a shared workflow or composite action. Every package that touches native deps should have its own smoke test — don't rely on the root npm ci to catch sub-package failures.

`npm-shrinkwrap.json` Is Gone — And npm Won't Tell You

If your project uses npm-shrinkwrap.json (common in CLI tools published to npm), v12 ignores it. Completely. No warning. Your lockfile is just... not the one you think it is.

# v11: shrinkwrap loaded
$ npm ci
# uses npm-shrinkwrap.json for dependency resolution

# v12: shrinkwrap silently ignored
$ npm ci
# uses package-lock.json (or generates one)
# npm-shrinkwrap.json is treated as if it doesn't exist

This is especially dangerous for published CLI packages. Your users install your tool, and under v12 they get different dependency versions than what you tested against.

Fix: switch to bundleDependencies.

{
  "name": "my-cli-tool",
  "version": "2.0.0",
  "bundleDependencies": [
    "yargs",
    "chalk",
    "ora"
  ]
}

When published with bundleDependencies, those packages are packed into the tarball. The user installing your CLI gets the exact versions you tested, regardless of npm version — no shrinkwrap needed. This works across npm 11 and 12.

If you absolutely need shrinkwrap-like behavior without bundling, rename npm-shrinkwrap.json to package-lock.json and ensure your publish workflow copies it:

cp npm-shrinkwrap.json package-lock.json
npm publish --lockfile-version=3

But honestly, bundleDependencies is the better answer for published packages. It's simpler, more portable, and works everywhere.

`npm view --json` Returns an Array Now

This one broke our release automation script. Every script that parses npm view --json output needs updating.

# v11: single result → object
$ npm view lodash@4.17.21 version --json
"4.17.21"

# v12: always array, even for single results
$ npm view lodash@4.17.21 version --json
["4.17.21"]

Our release script was doing:

LATEST=$(npm view my-package version --json)
# v11: echo $LATEST → "1.2.3" (works in jq)
# v12: echo $LATEST → ["1.2.3"] (breaks jq parsing)

If your CI, Makefile, or release scripts use npm view --json, grep for it now:

grep -r "npm view" .github/ Makefile scripts/ package.json

For each hit, check if it parses the JSON output. Every instance needs the same fix:

# Before (v11)
npm view my-package version --json | jq -r '.'

# After (v12)
npm view my-package version --json | jq -r '.[0]'

The array wrapping also hits multi-field queries:

# v11: single version → single object
$ npm view lodash@4.17.21 name version --json
{"name":"lodash","version":"4.17.21"}

# v12: single version → array with one object
$ npm view lodash@4.17.21 name version --json
[{"name":"lodash","version":"4.17.21"}]

If your script iterates with jq '.[]', it'll still work. If it expects a bare object with jq '.version', it breaks. Fix: wrap all your jq filters in .[0] or use jq '.[]' and loop.

Our full release script patch:

- PUBLISHED_VERSION=$(npm view my-package version --json | jq -r '.')
+ PUBLISHED_VERSION=$(npm view my-package version --json | jq -r '.[0]')

This one is easy to miss because it doesn't cause install-time failures. Your release just... silently publishes wrong version strings. Check your scripts before the next release.

Git Dependencies Are Blocked — And Transitive Ones Count

Your package.json might not have git deps, but one of your dependencies might. v12 blocks them at every level of the dependency tree.

# This fails in v12
npm install some-package
# Error: Git dependency "github:user/internal-lib" blocked
# (comes from some-package → its-dep → git dep, not your direct dep)

# What worked in v11:
# npm silently resolved and installed the git dep

To find hidden git deps before you migrate:

# Run while still on npm 11.16.0+
npm ls --all 2>&1 | grep -E "(git\+|ssh://|git://)"

Or audit your lockfile:

grep -r "git+" package-lock.json

If you find transitive git deps, your options, ordered by long-term stability:

Ask the dependency author to publish to npm registry — this is the real fix
Fork + publish internally — fork the git dep, publish to your private registry or npm, depend on that version
Use overrides in package.json — redirect the git dep to a registry version:

   "overrides": {
     "internal-lib": "npm:internal-lib-registry@1.0.0"
   }

Allow git globally — last resort: allow-git=true in .npmrc or --allow-git flag. Only do this if you control the full dependency chain

Overrides are the fastest fix short-term, but pin a specific version. Floating overrides ("*") will bite you on the next upgrade.

Monorepo-Specific: Workspace Protocol Doesn't Save You

If you use npm workspaces, the workspace:* protocol doesn't bypass the git/remote blocks. A workspace package that depends on a git dep still fails:

packages/
  app/         → "deps": {"shared": "workspace:*"}
  shared/      → "deps": {"internal-lib": "github:org/internal-lib#v1"}

npm install at the root fails because shared pulls a git dep transitively. The fix is the same as above — audit all package.json files in your monorepo, not just the root:

find packages -name package.json -exec grep -l "git+" {} \;

Run this in CI as a pre-flight check before npm ci. Block the build if any git deps are found and haven't been explicitly allowed.

The 24-Hour Checklist

If you're waking up to npm v12, here's the order of operations:

Audit your scripts — npm approve-scripts --allow-scripts-pending (run in CI-equivalent Docker)
Commit the allowlist — allowScripts in package.json
Add CI smoke tests — one per native dependency, right after npm ci
Check for shrinkwrap — if npm-shrinkwrap.json exists, migrate to bundleDependencies or package-lock.json
Grep for npm view --json — update jq filters from . to .[0]
Audit git deps — grep -r "git+" package-lock.json, set overrides or migrate
Check npm rebuild usage — it's also subject to script blocking; approve scripts first or pass --allow-scripts

I've been tracking v12 changes since pre.1 and maintain a full migration guide with per-environment configs at installsafe.dev.

DiffusionGemma in July 2026: What Works, What Doesn't, and When Ollama Gets It

Vigoss Luke — Tue, 07 Jul 2026 17:53:28 +0000

You've probably seen the benchmarks — 4x faster, 6x more mistakes, 273-vote threads on r/LocalLLaMA. DiffusionGemma is the most interesting image generation model to land this year. But actually running it outside of a HuggingFace notebook is a different story.

Here's the honest state of every platform as of July 2026.

The One PR Blocking Everything

Ollama, LM Studio, and native GGUF support all depend on a single pull request: llama.cpp #24423. It's been open since June 10, initially a proof-of-concept from danielhanchen, now mergeable (conflict resolved). The hold-up is design direction — one maintainer wants a general diffusion server rather than a model-specific implementation. No ETA.

What Works Today

vLLM (Recommended)

Day-zero support from the vLLM team. Single GPU works out of the box. Multi-GPU was broken until PR #46177 landed June 26 — tensor parallelism is now in main.

pip install vllm
vllm serve RedHatAI/diffusiongemma-26B-A4B --tensor-parallel-size 2

llama.cpp (Build from PR Branch)

Not in mainline yet. You need to fetch the PR branch and build with CUDA.

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
git fetch origin pull/24423/head:diffusion-gemma
git checkout diffusion-gemma
cmake -B build -DGGML_CUDA=ON
cmake --build build -j

Q4_K_M GGUF available on HuggingFace. Works, but you're on your own for build issues — no guarantees until it lands in main.

Ollama (Bridge Workaround)

No native ollama pull diffusiongemma yet. The bridge approach: build llama.cpp from the PR branch, create a custom Modelfile pointing at the GGUF, and serve through Ollama's import mechanism. Clunky but functional. Full steps at diffrun.dev/ollama.

What Doesn't Work

LM Studio — blocked on #24423. Can't bundle the engine until it's in llama.cpp mainline
GGUF in vLLM — PR #46454 fixes GGUF tied embedding loading for DiffusionGemma, mergeable but not merged. Use BF16 weights for now
nvfp4 quantization — vLLM's nvfp4 MoE kernels reject DiffusionGemma's expert intermediate size (not a multiple of 128). Separate issue, tracked in the vLLM repo

The Signal That Changes Everything

When #24423 merges, the dominoes fall fast: Ollama ships an engine update within days, LM Studio follows, and native GGUF conversion lands in mainline llama.cpp. Searches for "diffusiongemma ollama" and "diffusiongemma lm studio" will spike overnight.

I track all three PRs daily at diffrun.dev/status, with step-by-step setup guides for each platform at diffrun.dev.

npm v12 Is Landing in July — Here's Exactly What Will Break and How to Fix It Now

Vigoss Luke — Tue, 07 Jul 2026 17:47:58 +0000

TL;DR: npm v12 flips three defaults that will silently break your CI: install scripts are off, Git deps are blocked, remote tarballs are blocked. Your npm ci can exit 0 while native modules were never compiled. Here's a copy-paste migration plan.

───

The Big Picture

For 12 years, npm has let any package in your dependency tree run arbitrary code during npm install. A single compromised package with a postinstall script could exfiltrate your environment variables, SSH keys, and .npmrc tokens. The Shai Halud supply-chain attack made it impossible to ignore.

npm v12 finally fixes this. But the fix comes with pain:

Scripts are off by default — allowScripts defaults to off. Native modules (bcrypt, sharp, esbuild, node-gyp) won't compile.

Git dependencies are blocked — --allow-git defaults to none. Monorepo internal refs, forks, private repo deps — all blocked.

Remote URL deps are blocked — --allow-remote defaults to none.

You will get v12 whether you want it or not. Node.js bundles npm. When LTS releases (22, 24, 26) pick up the v12 bundle, your CI pipelines and dev environments will suddenly have different behavior.

Good news: npm 11.16.0+ already shows warnings. You can prepare today.

───

The Silent Killer: npm ci Can Succeed While Your App Is Broken

This is the most dangerous part of v12, and it's catching teams off guard:

$ npm ci # exits with code 0 ✅
$ npm test # passes ✅
$ node app.js # 💥 Cannot find module 'bcrypt'

npm v12's npm ci doesn't fail when scripts are blocked — it just silently skips them. Your native modules were never compiled, but CI went green. The app crashes at runtime.

Fix: Add a smoke test after every npm ci:

node -e "
const pkgs = ['sharp', 'esbuild', 'bcrypt'];
for (const p of pkgs) {
try { require(p); console.log('✓', p); }
catch(e) { console.error('✗', p, '— NOT COMPILED'); process.exit(1); }
}
console.log('All native modules present');
"

───

Migration Plan (15 Minutes)

Step 1: Upgrade to npm 11.16.0+ (warning mode, nothing breaks yet)

npm install -g npm@11

Step 2: See what will be blocked

npm install

You'll see warnings like:

npm warn allow-scripts 8 packages have install scripts not yet covered
npm warn allow-scripts Run npm approve-scripts --allow-scripts-pending to review

Step 3: Audit and approve

List every package that runs scripts

npm approve-scripts --allow-scripts-pending

Approve the ones you trust (most projects have 3-8)

npm approve-scripts bcrypt sharp node-gyp

Deny the rest (writes to package.json — commit this)

npm deny-scripts

Step 4: Find Git dependencies hiding in your tree

grep -r "git+" package.json package-lock.json
npm ls --all | grep -E "(git+|https://.*.tgz)"

You might be surprised — transitive dependencies often pull in Git refs. If you find any:

Quick fix: add to .npmrc

echo "allow-git=true" >> .npmrc

Better fix: migrate to registry versions

Step 5: Check for npm-shrinkwrap.json (it's gone in v12)

ls npm-shrinkwrap.json 2>/dev/null && mv npm-shrinkwrap.json package-lock.json

Step 6: Fix npm view --json parsing

v12 changes npm view --json to always return arrays. If your CI scripts do:

npm view lodash version --json | jq -r '.version'

This will break. Fix:

npm view lodash version --json | jq -r '.[0]'

───

GitHub Actions: Production-Ready Workflow

Here's a complete CI workflow for npm v12:

name: CI — npm v12 Compatible

on: [push, pull_request]

jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [18, 20, 22, 24]

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}

  # Pin npm 12 for forward-compatibility testing
  - run: npm install -g npm@12

  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: npm-${{ runner.os }}-${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}

  # Install with scripts pending, then approve known-safe ones
  - run: npm ci --allow-scripts-pending
  - run: npm approve-scripts node-gyp sharp esbuild bcrypt

  # SMOKE TEST: verify native modules actually compiled
  - run: |
      node -e "
      const pkgs = ['sharp', 'esbuild', 'bcrypt'];
      for (const p of pkgs) {
        try { require(p); console.log('✓', p); }
        catch(e) { console.error('✗', p, '— NOT COMPILED'); process.exit(1); }
      }
      "

  - run: npm test

───

Docker: Multi-Stage with C++17

npm v12 requires C++17 for native modules. Your old Docker image with gcc 7 won't cut it.

FROM node:22-slim

npm v12 needs C++17 toolchain

RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential python3 make gcc g++ \
&& rm -rf /var/lib/apt/lists/*

RUN npm install -g npm@12

WORKDIR /app
COPY package.json package-lock.json ./

Install + approve + verify

RUN npm ci --allow-scripts-pending && \
npm approve-scripts node-gyp sharp esbuild && \
node -e "require('sharp'); require('esbuild'); console.log('Native modules OK')"

COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

───

Should You Upgrade Now?

Scenario	Action
Pure JS project (no native deps)	Upgrade now — 5 minute fix
Has native deps (bcrypt, sharp, etc.)	Run the audit on npm 11.16.0+ this week, upgrade before July
Monorepo with Git deps	1 hour audit — find and migrate Git refs first
In the middle of a critical release	Stay on npm 11, but run the audit so you're ready

───

Bottom Line

npm v12 isn't a "should I upgrade?" question. It's a "when will it hit me?" question. Node.js will bundle it, your CI will inherit it, and your deployment will break at the worst possible time — unless you prepare now.

The migration takes 15 minutes for most projects. The outage it prevents is worth 15 hours.

───

This guide is based on npm 11.16.0+ behavior and the official npm v12 announcement. For more details, check out InstallSafe.dev — a free npm v12 migration guide with FAQ, CI/CD templates, and a side-by-side npm 11 vs 12 comparison.

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.

DEV Community: Vigoss Luke

npm v12 Just Shipped — Here's What Broke in My CI and How I Fixed It

The One That Scared Me: npm ci Exits 0, Native Modules Never Compiled

The CI Pipeline That Passed Green But Shipped Broken Code

npm-shrinkwrap.json Is Gone — And npm Won't Tell You

npm view --json Returns an Array Now

Git Dependencies Are Blocked — And Transitive Ones Count

Monorepo-Specific: Workspace Protocol Doesn't Save You

The 24-Hour Checklist

DiffusionGemma in July 2026: What Works, What Doesn't, and When Ollama Gets It

The One PR Blocking Everything

What Works Today

vLLM (Recommended)

llama.cpp (Build from PR Branch)

Ollama (Bridge Workaround)

What Doesn't Work

The Signal That Changes Everything

npm v12 Is Landing in July — Here's Exactly What Will Break and How to Fix It Now

List every package that runs scripts

Approve the ones you trust (most projects have 3-8)

Deny the rest (writes to package.json — commit this)

Quick fix: add to .npmrc

Better fix: migrate to registry versions

npm v12 needs C++17 toolchain

Install + approve + verify

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 One That Scared Me: `npm ci` Exits 0, Native Modules Never Compiled

`npm-shrinkwrap.json` Is Gone — And npm Won't Tell You

`npm view --json` Returns an Array Now

Error #3: `docker_mount_cwd_to_workspace` Permission Errors