Twenty messy documents, one command, and the front page I actually wanted

Twenty documents went into a folder. One command later, twenty clean Markdown files and a single index page came out, in 1.29 seconds on my laptop. That's the headline, and the bit I'm proudest of.

Weekend Projects is my Monday series about small builds I do at home, usually on a Sunday while the washing pile pretends not to exist. This one started with a problem I've hit in content work for years. Someone sends you a pile of files. A brief in Word, a keyword sheet in Excel, a monthly update as a slide deck, some notes as a PDF, an old web page. Before you can do anything useful with them you spend an hour opening, copying, renaming and tidying.

So I took an open-source document converter as the base and wrote a small batch tool on top. I didn't change the base code at all. My add-on just calls it, then cleans up what comes back. I used coding tools to help with the build, which mostly means I described what I wanted and argued with the output until it stopped surprising me.

What it does, in plain steps

You point it at a folder. The base converter handles each file in turn. Word documents keep their headings, bullets and tables. Spreadsheets become Markdown tables. Slide decks keep their titles and speaker notes. PDFs give up their text, and web pages get stripped back to the content.

The base does that part well. But raw conversion has rough edges. Some Word tables come out with an empty header row, so the real column names end up sitting in the first line of data. There's no front matter. And the files keep whatever names they arrived with, which in my experience is something like "FINAL v3 use this one".

My add-on fixes those things for every file. It promotes the real column names into the table header. It finds a sensible title (the Word title, the first slide title, the sheet name, the first web heading, or a tidied file name if all else fails) and makes it the single H1. It sorts the headings so there's exactly one H1 and no skipped levels. It clears out stray blank lines. Then it adds front matter at the top with the title, a description capped at 155 characters, a slug, the source file name, a word count, the list of headings and a short summary.

Summaries are deliberately old-school. It picks the two sentences that best represent the document, based on how often the important words turn up. Spreadsheets get a line naming the columns and the row count instead. Nothing clever, and nothing it can make up.

Last of all it writes an index: one table listing every document with its title, word count, number of headings and that one-line summary. If any file fails, it shows up in the index and the run carries on.

Mr. Mummu, who wanders into these posts now and then, once decided to sort his family's recipe forwards. Years of them. Photos of handwritten cards, voice notes, a PDF of a screenshot of a PDF. He printed every one, punched holes and filed them in a binder labelled "Urgent", which is where important things in his house go to be lost. It took him a whole Saturday. On Sunday his partner asked for the coconut chutney. Mummu opened the binder with real ceremony and turned pages for twenty minutes. Chutney was in there three times: under C, under K for kobbari, and under "Aunty, Tuesday". In the end he rang the aunty, who sent the same photo again in four seconds. Mummu shut the binder and said quietly, "So the binder needs a front page." He wrote that in his notebook, just under "milk".

Which is this project in one story. Converting is the easy bit. The front page is what saves you.

The timed run

For the test I made up twenty documents for four fictional businesses: a coffee shop, a bike shop, a yoga studio and a bakery, five file types each. Nothing from a real client. Twenty converted, none failed, 1.29 seconds. It all runs locally with no paid service and no API keys, so the weekend cost me nothing except a cold cup of tea.

Mostly I treat that number as a sanity check. If twenty small files took minutes, something would be wrong. Under two seconds told me the path was boring in a good way.

Honestly, the index is the bit I open first. One page, every document, a rough idea of what each one says. You can scan the pile before you open anything, which is exactly what Mummu's binder was missing.

There's a second reason I like clean Markdown. If you want to hand a stack of documents to a chatbot or a search tool, plain text with tidy headings beats a heap of binary files, in my experience anyway.

Where it falls short

Those summaries are simple picks, not finished copy. I'd read every description before anything went live. Scanned PDFs that are really just photos of pages give almost no text, because there's no OCR in this build. Title detection follows rules, so it will guess wrong sometimes. And tidy Markdown is a starting shape. It won't make a page rank on its own.

I've put the full demo, with the raw output, the cleaned front matter, the index and the twenty-file run, on my YouTube channel, in the Weekend Projects series.

If a chunk of your week is still copy and paste between documents and a website, this kind of small local tool is worth a Sunday afternoon. Just write the front page first.