DEV Community: Emma Jansen

I draw a bar for every sentence to find the ones that run too long

Emma Jansen — Wed, 11 Nov 2026 10:53:39 +0000

Most of my editing notes to myself used to say the same thing: "this paragraph feels heavy." It took me a while to work out why. Usually the words were fine. The problem was rhythm. Either one sentence ran on for forty words and lost the reader halfway, or five sentences in a row had exactly the same length and the paragraph started to drone.

Both problems are hard to see while reading for meaning, because I'm following the argument, not counting. So I stopped trying to see them and wrote a small script that draws them for me.

What the script shows

It reads a Markdown file, splits it into paragraphs and sentences, and prints one bar per sentence. The length of the bar is the number of words. Any sentence over a limit gets flagged with its first few words, so I can find it in the draft.

The output for one paragraph looks like this:

Paragraph 4
    9 #########
   14 ##############
   38 ######################################  <- When the client sends their notes back a...
    6 ######

That 38 jumps out immediately.

The script

import re
import sys
from pathlib import Path

FENCE = "`" * 3
LIST_ITEM = re.compile(r"([-*+]|\d+\.)\s")
LIMIT = int(sys.argv[2]) if len(sys.argv) > 2 else 30


def paragraphs(text):
    in_code = False
    current = []
    for line in text.splitlines():
        stripped = line.strip()
        if stripped.startswith(FENCE):
            in_code = not in_code
            continue
        if in_code or stripped.startswith("#"):
            continue
        if LIST_ITEM.match(stripped):
            if current:
                yield " ".join(current)
            current = [stripped]
        elif stripped:
            current.append(stripped)
        elif current:
            yield " ".join(current)
            current = []
    if current:
        yield " ".join(current)


text = Path(sys.argv[1]).read_text(encoding="utf-8")
for number, para in enumerate(paragraphs(text), start=1):
    print(f"Paragraph {number}")
    for sentence in re.split(r"(?<=[.!?])\s+", para):
        words = len(sentence.split())
        line = f"  {words:3d} {'#' * words}"
        if words > LIMIT:
            line += f"  <- {sentence[:40]}..."
        print(line)

A few notes on how it works:

It skips fenced code blocks and headings, because those aren't prose and would only add noise. The fence marker is built from three backtick characters at runtime, so the script itself contains no literal fence that could confuse a Markdown renderer when I paste it into a post.
Each list item counts as its own paragraph. Bullet points often have no full stop, and without this rule a whole list gets measured as one enormous sentence.
Sentences are split after ., ! or ? followed by a space. That's crude. Abbreviations like "e.g." will create a false break now and then, which I can live with because I'm looking for patterns, not exact numbers.
The limit is 30 words by default. You can pass a different one as the second argument.

Running it

python3 sentence_map.py draft.md
python3 sentence_map.py draft.md 25

I run it once a draft is complete, never while I'm still writing. During a first draft I want long, messy sentences. Fixing rhythm too early just slows me down.

What I look for in the bars

Single spikes. A bar much longer than its neighbours is almost always two or three ideas joined with "and", "which" or a dash. I split it at the first natural break and read both halves out of context to check they still make sense.

Flat blocks. Four or five bars of nearly identical length are the drone I mentioned. The fix is not to make everything short. It's to vary: let one sentence run a bit, then follow it with a short one. Like this.

Short bars everywhere. This surprised me. When I'm tired, I overcorrect and write in choppy fragments. A page of bars under eight words reads like a list of instructions, even when it isn't one. Joining two related sentences often makes the paragraph sound more human.

What it won't tell you

The script counts words, nothing more. A 35-word sentence can be perfectly clear if it's a simple list, and a 12-word sentence can be impossible to parse. So I treat every flag as a question, not an error: is this sentence long because it needs to be, or because I didn't decide where it ends?

I also don't chase an average. There's no correct sentence length for the web, and a draft where every sentence is 15 words would be just as tiring as one full of 40-word sentences. What I want is variety, with the longest sentences reserved for places where the reader already has the context to follow them.

Running the script and fixing the worst spikes takes me a few minutes, and the paragraphs that used to feel heavy now usually just feel normal.

I keep my article drafts in Git: the five commands I actually use

Emma Jansen — Tue, 10 Nov 2026 09:11:12 +0000

Every writer I know has a story about the paragraph they deleted and then wanted back three days later. Mine was a short opening anecdote that I cut because it felt slow. Two edits later the piece had no warmth left, and the anecdote was gone. Undo history doesn't survive closing the editor.

That's the main reason my drafts now live in Git. Not for collaboration or branching strategies. I just want every saved version one command away. I use a tiny part of Git, and these five commands cover nearly all of it.

1. `git init`: once per project

Each writing project gets a folder, and each folder becomes a repository:

mkdir spring-newsletter
cd spring-newsletter
git init

Git creates a hidden .git folder for the history. My files stay as they are, and I keep writing in whatever editor I like.

2. `git add` and `git commit`: save a version with a note

When I finish a session, or before a big change I might regret, I save a snapshot:

git add draft.md
git commit -m "Move the reader question up to the second paragraph"

The message took me longest to get right. Early on I wrote "edits" and "more changes", which are useless when you're hunting for one specific version. Now I describe what changed in the text, the way I'd explain it to an editor:

"Cut the opening anecdote, start with the problem"
"Rewrite the ending as a question"
"Add second example from the interview notes"

A good message is a label on a drawer. Future me opens the right one without checking them all.

3. `git diff --word-diff`: see what I actually changed

Plain git diff works line by line, which suits code. In prose, a paragraph is often one long line, so changing one word marks the whole paragraph. The word-diff option fixes that:

git diff --word-diff

After tightening one sentence, it shows:

Most mornings I {+still+} start with [-a cup of tea and a blank page.-]{+tea.+}

Removed words sit inside [- and -], added words inside {+ and +}. Without arguments, it compares my file with the last commit, so I run it before committing to catch accidental changes. In a colour terminal, git diff --word-diff=color drops the brackets and shows the changes in red and green instead.

4. `git log`: find the version I'm looking for

To see the history of a draft:

git log --oneline -- draft.md

6da2b27 Cut the opening anecdote, start with the problem
7ddc92c Rewrite the ending as a question
3c35fc5 First full draft

This is where good messages pay off. But sometimes I only remember a phrase from what I cut. For that, -S finds commits where a piece of text was added or removed:

git log -S "my grandmother's kitchen" --oneline -- draft.md

It lists the commit that added the phrase and the one that removed it. The newer one is the cut I'm after.

5. `git show`: get an old paragraph back

With the commit in hand, I print the file as it was then, without touching my current draft:

git show 3c35fc5:draft.md

If the commit I found is the one that removed the paragraph, I add ^ to look at the version just before it:

git show 6da2b27^:draft.md

The old file appears in the terminal and I copy the paragraph across. One detail: the path after the colon is relative to the top of the repository. From a subfolder, write ./draft.md instead.

For an entire old version, there's git restore:

git restore --source=3c35fc5 draft.md

Careful: it overwrites the file in your folder, so uncommitted work is lost. I commit first, then restore, so even the version I'm replacing stays in the history.

What I skip

Branches, rebasing, tags. Useful for lots of people, but for one person writing articles they mostly added steps. The only extra I use is pushing to a private remote now and then as a backup.

The habit that matters is committing often with messages that describe the writing. Once that's in place, cutting a paragraph stops feeling risky, and I edit far more boldly.

My personal style sheet is a text file and a short Python script

Emma Jansen — Sat, 07 Nov 2026 10:50:18 +0000

Is it "email" or "e-mail"? "Log in" or "login"? "JavaScript" or "Javascript"? None of these choices matter much on their own. What matters is making the same choice every time, and that's where I used to slip. I'd write "email" in one piece and "e-mail" in the next, depending on what I'd been reading that morning.

Editors at publications solve this with a style sheet: a running list of decisions about spelling, capitalisation and terms for one project. I borrowed the idea and keep my own as a plain text file. Then I added a few lines of Python so I don't have to remember it all myself.

What goes in the file

My style sheet is a file called style.txt that sits next to my drafts. Each line holds one decision: the form I want on the left, the forms I want to catch on the right.

# preferred | variants to flag
email | e-mail, E-mail
website | web site
log in to | login to
JavaScript | Javascript, javascript
GitHub | Github, github

Lines that start with # are comments. Everything else is a rule.

I only add a word after I've caught myself being inconsistent with it. Grown like that, it stays short and personal. Mine is mostly product names, a few compound words and some British versus American spellings I keep mixing up.

Why a plain file

I've tried keeping word lists in notes apps and spreadsheets. The plain file wins for boring reasons:

It opens in any editor, so I can check it in seconds while writing
I can search it with the same tools I use for everything else
It lives in the same folder as the drafts, so it moves with the project
A script can read it without any extra libraries

A short script that reads it

Reading the list is one thing. Actually checking a draft against it by eye is tedious, and I miss things. So I wrote check_style.py:

import re
import sys
from pathlib import Path

rules = []
for line in Path("style.txt").read_text(encoding="utf-8").splitlines():
    line = line.strip()
    if not line or line.startswith("#"):
        continue
    preferred, variants = line.split("|")
    for variant in variants.split(","):
        rules.append((preferred.strip(), variant.strip()))

for path in sys.argv[1:]:
    lines = Path(path).read_text(encoding="utf-8").splitlines()
    for number, text in enumerate(lines, start=1):
        for preferred, variant in rules:
            if re.search(r"\b" + re.escape(variant) + r"\b", text):
                print(f"{path}:{number}: '{variant}' -> '{preferred}'")

It builds a list of (preferred, variant) pairs from the style sheet, then goes through every file I pass in, line by line. The \b markers mean it only matches whole words, so the rule for "web site" won't fire inside some longer word by accident. re.escape takes care of any characters in a variant that would otherwise have a special meaning in a regular expression.

I run it on a whole folder at once:

python3 check_style.py drafts/*.md

On a test draft, the output looks like this:

drafts/post.md:1: 'e-mail' -> 'email'
drafts/post.md:1: 'web site' -> 'website'
drafts/post.md:2: 'Javascript' -> 'JavaScript'
drafts/post.md:2: 'Github' -> 'GitHub'
drafts/post.md:3: 'login to' -> 'log in to'

File, line number, what it found and what I want instead. That's all I need to go and fix it.

A few things I learned using it

The match is case-sensitive on purpose. That's why "E-mail" has its own entry. I could make the search ignore case, but then a rule like "GitHub | Github" would flag the correct spelling too. Listing variants explicitly is a bit more typing and much less confusing.

Some rules need context. "Login" as a noun ("your login details") is fine in my style. "Login to your account" is not. So the rule matches "login to" rather than "login" on its own. When a word is only wrong in certain phrases, I put the phrase in the file instead of the word.

It doesn't fix anything. I like that. The script points, I decide. Sometimes a variant is correct in context, for example when I'm quoting someone, and I leave it alone.

Code blocks get flagged too. If a draft contains github.com in a code sample, the lowercase rule catches it. I just skip those lines. It hasn't bothered me enough to add code-block handling.

Keeping it alive

The style sheet only helps if it keeps growing. Whenever I hesitate over a spelling while writing, I make the decision once, add a line, and move on. The next time that word comes up, the decision is already made, and the check catches me if I forget.

It's a small habit, but my pieces read more like they came from one person now, which, well, they did.

Write twenty headlines, keep one: my plain-text headline routine

Emma Jansen — Tue, 03 Nov 2026 10:07:46 +0000

For a long time the headline was the first thing I wrote and the last thing I thought about. I'd type something at the top of a blank file so it had a name, write the whole piece underneath, and publish with that placeholder barely changed. Then I'd wonder why a piece I was happy with got so few clicks.

These days I write headlines last, and I write a lot of them. The whole routine lives in one plain text file and takes about fifteen minutes.

Finish the draft first

A headline is a promise about what the article delivers, and before the draft exists I don't know what that is. Pieces drift while I write them. A planned list of tips turns into one longer argument, or the best part ends up being an example I never planned.

So the working title stays rough on purpose. Once the draft is done, I read it once and write down, in one plain sentence, what a reader gets out of it. That sentence is not a headline, but every headline I write afterwards has to keep its promise.

Twenty lines in one file

Next to the draft I create headlines.txt and fill it with candidates, one per line. I aim for about twenty. The first five are usually obvious, and the useful ones tend to show up once the obvious ones are out of the way.

To keep from writing the same line twenty times, I rotate through a few shapes:

A plain statement of what the piece does
A question the reader might actually type into a search box
The result, without the method
The method, without the result
A version aimed at one specific reader

For this article, a few of mine looked like this:

How I draft headlines
Write twenty headlines, keep one
Why your headline is the last thing you should write
A plain-text routine for drafting headlines that say what the article is about
Headlines: a short guide

None of them is finished. They are raw material.

Sort them by length

Headlines get cut off in search results, in feeds and on narrow phone screens. I use roughly 60 characters as my own upper limit. It's a rule of thumb, not a hard line, but it stops me from writing a whole sentence and calling it a headline.

Counting by eye is hopeless, so I let awk do it. This prints every line with its length in front and sorts the list from shortest to longest:

awk '{ print length($0), $0 }' headlines.txt | sort -n

For the list above, the output starts like this:

21 How I draft headlines
24 Headlines: a short guide
32 Write twenty headlines, keep one
52 Why your headline is the last thing you should write
78 A plain-text routine for drafting headlines that say what the article is about

And this shows only the ones over the limit, with their line numbers, so I know which ones to shorten:

awk 'length($0) > 60 { print NR ": " $0 }' headlines.txt

Some versions of awk count bytes rather than characters, so accented letters can make a line look slightly longer. For a rough limit, that's fine.

Cut the ones that hide the topic

With the list sorted, I go through it and delete lines. A candidate goes if:

It's clever but someone skimming wouldn't know what the article is about
The important words come at the end, where they might get cut off
It promises more than the draft delivers
It could sit on top of a hundred other articles

"Headlines: a short guide" fails the last test. It's not wrong, it's just interchangeable. The 78-character line says the right things but needs trimming, and trimming it is often how I find the final version.

Test the survivors against the first paragraph

Usually three or four lines are left. I read each one, then my opening paragraph straight after it, the way a reader would after clicking. If the opening doesn't pick up the promise within a sentence or two, either the headline or the opening has to change. Sometimes it's the opening, which is a nice bonus.

Keep the file

I don't delete headlines.txt when the piece goes out. The rejected lines are often good subheadings, newsletter subject lines or the opening of a short social post. And when I go back months later to update an article, the list reminds me which angles I already tried.

My headlines are less of an afterthought now. They're a short writing job of their own, done when I finally know what I'm promising.

Let your computer read your draft back to you

Emma Jansen — Sat, 31 Oct 2026 10:28:38 +0000

I can reread a paragraph five times and still miss the word I typed twice. My eyes know what I meant to write, so they fill in the gaps. My ears are much less forgiving. When I hear a draft read out loud, the clumsy sentences, the missing words and the three "really"s in a row are suddenly obvious.

Reading aloud myself works, but I tend to fix things as I go and lose the flow. Letting the computer do the reading is more honest. A text-to-speech voice reads exactly what is on the page, with no idea what I meant. Most systems already have one built in, so this costs nothing to try.

Turn the Markdown into plain text first

My drafts are Markdown files, and a speech engine will happily read every asterisk, link URL and heading marker if I let it. So the first step is to strip the formatting. Pandoc does this in one line:

pandoc draft.md -t plain -o draft.txt

The plain text output keeps the words and drops most of the syntax. Links become just their text, and emphasis markers disappear. Code blocks stay in, so for a technical post I either skip those parts while listening or accept a few odd seconds of the voice reading a command.

Let the voice read it

On macOS, the say command reads a file out loud:

say -f draft.txt

You can slow it down with -r, which sets the rate in words per minute:

say -r 160 -f draft.txt

On Linux, espeak-ng does the same job. It sounds more robotic, but for catching mistakes that doesn't matter much. Its -s option sets the speed, also in words per minute:

espeak-ng -s 150 -f draft.txt

On Windows, Windows PowerShell can use the built-in speech engine:

Add-Type -AssemblyName System.Speech
$voice = New-Object System.Speech.Synthesis.SpeechSynthesizer
$voice.Speak((Get-Content draft.txt -Raw))

If you'd rather not touch the command line at all, many editors and browsers have a "read aloud" option too. The tool matters less than the habit.

Put it in one small script

Since I do this for almost every piece, I keep a tiny script called listen in my path:

#!/usr/bin/env bash
# Read a Markdown draft out loud (macOS).
set -euo pipefail

tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT

pandoc "$1" -t plain -o "$tmp"
say -r "${2:-170}" -f "$tmp"

Run it as listen draft.md, or listen draft.md 150 for a slower pace. The temporary file is removed when the script exits, so nothing piles up in my drafts folder. On Linux, swap the say line for espeak-ng -s "${2:-170}" -f "$tmp".

What to listen for

I listen with the draft open and a pen, or at least a cursor, ready. These are the things that jump out most often:

Missing or doubled words. "Save the the file" is invisible on screen and impossible to miss when spoken.
Sentences that run out of breath. If the voice reaches the end of a sentence and I've forgotten how it started, the sentence needs splitting.
Repeated words close together. Hearing "simple" three times in one paragraph is far more annoying than seeing it.
Rhythm that never changes. Five sentences of the same length in a row sound flat, even if each one is fine on its own.
Ambiguous words. If the voice stresses a word in a way that changes the meaning, a human reader might stumble on it too.

I don't stop the audio for every small thing. I make a quick mark and keep listening, then fix everything in one pass afterwards. Stopping constantly breaks the same flow I'm trying to hear.

Where it fits in my routine

Listening isn't my first edit. I do the structural work first: moving sections, cutting what doesn't belong, fixing the headings. Text-to-speech is for the late stage, when the content is settled and I want to catch the small things a spell checker won't flag because every word is spelled correctly.

It takes a few minutes per article. For something that catches mistakes my eyes have skipped over several times already, that's a trade I'm happy to make.

One article, four formats: how I repurpose long pieces without copy-paste

Emma Jansen — Thu, 29 Oct 2026 21:34:26 +0000

When I finish a long article, there's always a small voice saying it should live somewhere else too. A newsletter, a short social post, maybe a thread. For a long time I handled that by copying paragraphs out of the article and trimming them until they fit. The result read exactly like what it was: leftovers.

These days I treat repurposing as its own writing job, with a short process. It takes less time than the copy-and-trim approach, and the smaller pieces actually stand on their own.

Start from the outline, not the text

The first thing I do is ignore the finished prose and look at the skeleton. Since my drafts are Markdown files, I can pull the headings out with one command:

grep -E '^#{2,3} ' article.md

That prints every H2 and H3 line, in order. Seeing the structure without the sentences around it helps me answer one question: which of these sections could make sense to someone who never reads the full article? Usually it's two or three of them. Those become the starting points for the shorter formats.

If I want the list in a scratch file to write notes next to it, I redirect it:

grep -E '^#{2,3} ' article.md > repurpose-notes.md

Write one sentence per format first

Before I write any of the new pieces, I write a single sentence for each one that says what a reader gets from it. For an article about building a writing routine, that might look like this:

- Newsletter: why my routine only works because it's boring
- Short post: the one rule I'd keep if I dropped everything else
- Thread: five steps, one per post, each usable alone
- Comment/reply bank: two lines on picking a fixed start time

If I can't write that sentence, the format gets skipped. Not every article needs to become a thread. Forcing it is where the leftover feeling comes from.

Rewrite the opening for each audience

The article's first paragraph was written for someone who clicked a headline and is ready to read for several minutes. A newsletter reader opened an email from someone they know. A social post reader is scrolling and gives me a second, maybe two.

So each format gets a new opening, written from scratch. For the newsletter I usually start with something personal and short, like what made me write the piece. For a short post I start with the most concrete line I have, often a rule or a small result, and leave the explanation for the second sentence.

I never reuse the article's first paragraph in any of them. It's almost always the wrong length and the wrong tone.

Keep one detail, drop the rest

Long articles earn their length with examples, caveats, and side notes. Short formats can't carry all of that. My rule is to keep exactly one specific detail per short piece: one example, one command, one before-and-after sentence.

A single specific detail does more for a short post than three general points. A line like "no email before ten" is more useful to a reader than "I protect my mornings, avoid distractions and plan ahead".

Link back only when it helps

It's tempting to end every repurposed piece with "read the full article". I only do that when the short version genuinely leaves the reader with a question the article answers. If the short piece is complete on its own, I let it be complete. People notice when a post exists only to send them somewhere else.

Keep all versions together

Every repurposed version goes in the same folder as the original article, with the format in the file name:

routine-article/
  article.md
  newsletter.md
  short-post.md
  thread.md

That way, when I update the article later, I can see right away which smaller pieces might need a change too. It also stops me from repurposing the same section twice by accident.

What changed for me

The biggest difference is that I no longer think of the shorter pieces as summaries. Each one is a small, separate piece of writing that happens to share an idea with a longer one. That shift made them easier to write, and honestly more fun, because I get to approach the same idea from a slightly different side each time.

A small Python check for front matter in a folder of Markdown drafts

Emma Jansen — Tue, 27 Oct 2026 16:25:32 +0000

I keep my drafts as Markdown files with a short front matter block at the top. It holds the title, a one-line description that ends up as the meta description, and a few tags. When a piece is ready, the static site generator or the blogging platform reads those fields and builds the page from them.

The trouble is that front matter is the part I look at least. I spend hours on the body and about ten seconds on the block above it. So the mistakes pile up there: a title that grew while I was editing and is now far too long for a search result, a description I meant to write later, a tags line I left empty.

None of this is hard to fix. It's just easy to miss. So I wrote a short script that reads every draft in a folder and tells me what's missing or too long.

What it checks

I kept the rules deliberately small:

Every file starts with a front matter block between two --- lines.
title, description and tags are present and not empty.
The title is 60 characters or fewer.
The description is 155 characters or fewer.

The two length limits are rough guides, not official numbers. Search engines cut titles and snippets by display width, not by a fixed character count, so treat them as a "probably too long" warning. Change them to whatever your platform or site uses.

A draft that passes looks like this:

---
title: How I name my draft files
description: A simple naming pattern that keeps a folder of drafts easy to search.
tags: [writing, workflow]
---
Body text starts here.

The script

It uses only the standard library, so there's nothing to install.

#!/usr/bin/env python3
"""Flag Markdown drafts with missing or overlong front matter fields."""
import sys
from pathlib import Path

REQUIRED = ["title", "description", "tags"]
MAX_TITLE = 60
MAX_DESCRIPTION = 155


def read_front_matter(text):
    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        return None
    fields = {}
    for line in lines[1:]:
        if line.strip() == "---":
            return fields
        if ":" in line:
            key, value = line.split(":", 1)
            fields[key.strip()] = value.strip().strip('"').strip("'")
    return None  # no closing ---


def check(path):
    problems = []
    fields = read_front_matter(path.read_text(encoding="utf-8"))
    if fields is None:
        return ["no front matter block"]
    for key in REQUIRED:
        if not fields.get(key):
            problems.append(f"missing {key}")
    title = fields.get("title", "")
    if len(title) > MAX_TITLE:
        problems.append(f"title is {len(title)} characters (max {MAX_TITLE})")
    description = fields.get("description", "")
    if len(description) > MAX_DESCRIPTION:
        problems.append(
            f"description is {len(description)} characters (max {MAX_DESCRIPTION})"
        )
    return problems


def main():
    folder = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
    found = 0
    for path in sorted(folder.rglob("*.md")):
        for problem in check(path):
            print(f"{path}: {problem}")
            found += 1
    sys.exit(1 if found else 0)


if __name__ == "__main__":
    main()

read_front_matter returns None when there's no opening --- or no closing one, and a dictionary of fields otherwise. check turns that into a list of plain-language problems. main walks the folder recursively with rglob, prints one line per problem, and exits with status 1 if anything was found.

Running it

Save it as check_front_matter.py and point it at your drafts folder:

python3 check_front_matter.py drafts

With one good file, one file with a long title and no description, and one file without front matter, the output looks like this:

drafts/long-title.md: missing description
drafts/long-title.md: title is 83 characters (max 60)
drafts/no-front-matter.md: no front matter block

Each line starts with the file path, so in most editors' terminals you can click straight through to the file. When everything passes, it prints nothing and exits with 0.

Making it hard to forget

If your drafts live in a git repository, the exit code means you can run the check before every commit. Put this in .git/hooks/pre-commit and make it executable with chmod +x .git/hooks/pre-commit:

#!/bin/sh
python3 check_front_matter.py drafts

If the script finds a problem, git stops the commit and shows the list. When I really do want to commit a half-finished draft, git commit --no-verify skips the hook for that one commit.

I don't always want that level of strictness. On some projects I just run the script by hand before I move a file into the "ready" pile, and that's enough.

What it doesn't do

This is not a real YAML parser. It reads simple key: value lines, one per field. If you write tags as a block list:

tags:
  - writing
  - workflow

the script sees an empty tags: line and reports it as missing. If that's how you write front matter, either switch to the inline [writing, workflow] style or install PyYAML and use yaml.safe_load on the block instead of the loop.

It also can't tell whether a description is any good. It only knows that one exists and isn't too long. Writing a description that makes someone want to read the piece is still my job. The script just makes sure I don't publish without one.

That's the part I like about small checks like this. They take the boring, forgettable items off my mind, so the attention I have left goes to the writing itself.

A small Python check for front matter in a folder of Markdown drafts

Emma Jansen — Sun, 25 Oct 2026 10:11:05 +0000

None of this is hard to fix. It's just easy to miss. So I wrote a short script that reads every draft in a folder and tells me what's missing or too long.

What it checks

I kept the rules deliberately small:

Every file starts with a front matter block between two --- lines.
title, description and tags are present and not empty.
The title is 60 characters or fewer.
The description is 155 characters or fewer.

A draft that passes looks like this:

---
title: How I name my draft files
description: A simple naming pattern that keeps a folder of drafts easy to search.
tags: [writing, workflow]
---
Body text starts here.

The script

It uses only the standard library, so there's nothing to install.

#!/usr/bin/env python3
"""Flag Markdown drafts with missing or overlong front matter fields."""
import sys
from pathlib import Path

REQUIRED = ["title", "description", "tags"]
MAX_TITLE = 60
MAX_DESCRIPTION = 155


def read_front_matter(text):
    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        return None
    fields = {}
    for line in lines[1:]:
        if line.strip() == "---":
            return fields
        if ":" in line:
            key, value = line.split(":", 1)
            fields[key.strip()] = value.strip().strip('"').strip("'")
    return None  # no closing ---


def check(path):
    problems = []
    fields = read_front_matter(path.read_text(encoding="utf-8"))
    if fields is None:
        return ["no front matter block"]
    for key in REQUIRED:
        if not fields.get(key):
            problems.append(f"missing {key}")
    title = fields.get("title", "")
    if len(title) > MAX_TITLE:
        problems.append(f"title is {len(title)} characters (max {MAX_TITLE})")
    description = fields.get("description", "")
    if len(description) > MAX_DESCRIPTION:
        problems.append(
            f"description is {len(description)} characters (max {MAX_DESCRIPTION})"
        )
    return problems


def main():
    folder = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
    found = 0
    for path in sorted(folder.rglob("*.md")):
        for problem in check(path):
            print(f"{path}: {problem}")
            found += 1
    sys.exit(1 if found else 0)


if __name__ == "__main__":
    main()

Running it

Save it as check_front_matter.py and point it at your drafts folder:

python3 check_front_matter.py drafts

With one good file, one file with a long title and no description, and one file without front matter, the output looks like this:

drafts/long-title.md: missing description
drafts/long-title.md: title is 83 characters (max 60)
drafts/no-front-matter.md: no front matter block

Each line starts with the file path, so in most editors' terminals you can click straight through to the file. When everything passes, it prints nothing and exits with 0.

Making it hard to forget

#!/bin/sh
python3 check_front_matter.py drafts

If the script finds a problem, git stops the commit and shows the list. When I really do want to commit a half-finished draft, git commit --no-verify skips the hook for that one commit.

I don't always want that level of strictness. On some projects I just run the script by hand before I move a file into the "ready" pile, and that's enough.

What it doesn't do

This is not a real YAML parser. It reads simple key: value lines, one per field. If you write tags as a block list:

tags:
  - writing
  - workflow

That's the part I like about small checks like this. They take the boring, forgettable items off my mind, so the attention I have left goes to the writing itself.

Nobody clicks "click here": a small Python check for vague link text

Emma Jansen — Fri, 23 Oct 2026 09:07:39 +0000

Link text is one of those things I never thought about until I started paying attention to how people actually move through a page. Most readers don't read every word. They scan, and links stand out because they look different from everything around them. If the highlighted words are "click here" or "read more", the scan tells them nothing.

It matters even more for people using a screen reader. Many screen readers can list all the links on a page so you can jump straight to the one you want. A list that says "here, here, read more, this, here" is useless. A list that says "keyboard shortcut cheat sheet, style guide, accessibility checklist" works without any surrounding text at all.

So I made a rule for myself: every link should make sense if you read only the linked words. Then I wrote a tiny script, because I knew I would forget the rule by Thursday.

What a good link looks like

The fix is almost always to move the link onto the words that describe the destination. A few before-and-after pairs from my own drafts:

<!-- Before -->
For the full list of shortcuts, [click here](https://example.com/shortcuts).

<!-- After -->
Here is the [full list of keyboard shortcuts](https://example.com/shortcuts).

<!-- Before -->
The style guide is at [https://example.com/style](https://example.com/style).

<!-- After -->
Everything about tone and spelling is in our [house style guide](https://example.com/style).

The second one is sneaky. A bare URL as link text feels precise, but a screen reader may read it out character by character, and on a phone a long URL can wrap in strange places. A URL only belongs on screen when the reader genuinely needs to see or copy the address, like in printed material.

A couple of extra habits I picked up along the way:

If two links on the same page go to different places, give them different text.
Put the important words at the start of the link. "Pricing for teams" scans better than "Find out more about our pricing for teams".
Don't add "link to" in the text. It's already a link.

The script

My drafts live as Markdown files in one folder, so the check only needs to read .md files and look for inline links. Here it is:

#!/usr/bin/env python3
"""Flag vague link text in Markdown files."""
import re
import sys
from pathlib import Path

VAGUE = {
    "click here", "here", "this", "this link", "link",
    "read more", "more", "learn more", "this page", "this article",
}

# [text](url) but not images ![alt](src)
LINK = re.compile(r"(?<!!)\[([^\]]+)\]\(([^)\s]+)[^)]*\)")


def check(path):
    problems = 0
    lines = path.read_text(encoding="utf-8").splitlines()
    for number, line in enumerate(lines, start=1):
        for match in LINK.finditer(line):
            text = match.group(1).strip()
            cleaned = text.lower().strip(".,:;!?")
            if cleaned in VAGUE:
                reason = "vague link text"
            elif cleaned.startswith(("http://", "https://", "www.")):
                reason = "bare URL as link text"
            else:
                continue
            print(f"{path}:{number}: {reason}: [{text}]")
            problems += 1
    return problems


def main():
    folder = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
    total = sum(check(p) for p in sorted(folder.rglob("*.md")))
    print(f"{total} link(s) to look at")
    return 1 if total else 0


if __name__ == "__main__":
    sys.exit(main())

The regular expression matches [text](url) and skips images, which start with !. The [^)]* at the end allows for an optional title like [text](url "title"). Punctuation is stripped before comparing, so [read more.] is still caught.

Save it as check_links.py and point it at a folder:

python3 check_links.py drafts

On a test file the output looks like this:

drafts/newsletter.md:3: vague link text: [click here]
drafts/newsletter.md:4: bare URL as link text: [https://example.com/style]
drafts/newsletter.md:6: vague link text: [read more.]
3 link(s) to look at

The file:line format is handy because most editors, including VS Code's terminal, turn it into something you can click to jump straight to the line.

Running it before I publish

The script exits with code 1 when it finds something, so it plays nicely with anything that cares about exit codes. I run it as part of my usual pre-publish routine, but you could just as easily drop it into a Git pre-commit hook or a CI step next to other checks.

What it won't catch

It's deliberately simple. It ignores reference-style links ([text][ref]) and HTML <a> tags, and the list of vague phrases is short. That's fine for me, because the point isn't a perfect audit. The point is a nudge at the moment I'm most likely to get lazy, which is right at the end of a draft.

Feel free to grow the VAGUE set with your own bad habits. Mine now includes "this", which I apparently type far more often than I'd like to admit.

A tiny script to track how many words I write per day

Emma Jansen — Wed, 21 Oct 2026 16:18:11 +0000

Word count goals get a lot of criticism, and some of it is fair. A thousand bad words aren't better than two hundred good ones. But on days when I'm drafting, a simple number tells me something useful: did I actually write today, or did I just rearrange commas?

Most editors show the word count of the current file. That's not what I want. I want to know how many words I added today across everything I work on. So I wrote a small script for it. It takes a snapshot of my writing folder once a day and compares it with yesterday.

The idea

Count the words in every Markdown file in a folder.
Save the total, with today's date, to a small CSV file.
Show the difference from the previous entry.

That's all. No database, no app, no account.

The script

I wrote it in Python because it ships with most systems and handles text well. Save this as wordlog.py:

#!/usr/bin/env python3
"""Log the total word count of a writing folder once per day."""

import csv
import re
import sys
from datetime import date
from pathlib import Path

FOLDER = Path(sys.argv[1] if len(sys.argv) > 1 else "~/writing").expanduser()
LOG = FOLDER / ".wordlog.csv"
FRONTMATTER = re.compile(r"\A---\n.*?\n---\n", re.DOTALL)
CODE_BLOCK = re.compile(r"```

.*?

```", re.DOTALL)


def count_words(text: str) -> int:
    text = FRONTMATTER.sub("", text)
    text = CODE_BLOCK.sub("", text)
    return len(re.findall(r"\b[\w'-]+\b", text))


def total_words() -> int:
    return sum(
        count_words(p.read_text(encoding="utf-8", errors="ignore"))
        for p in FOLDER.rglob("*.md")
    )


def read_log() -> list[list[str]]:
    if not LOG.exists():
        return []
    with LOG.open(newline="") as f:
        return list(csv.reader(f))


def main() -> None:
    today = date.today().isoformat()
    total = total_words()
    rows = [r for r in read_log() if r and r[0] != today]
    previous = int(rows[-1][1]) if rows else total
    rows.append([today, str(total)])
    with LOG.open("w", newline="") as f:
        csv.writer(f).writerows(rows)
    print(f"{today}: {total} words total, {total - previous:+d} since last entry")


if __name__ == "__main__":
    main()

A few choices worth explaining:

Frontmatter and code blocks are skipped. I don't want a YAML header or a pasted config file to count as writing.
Running it twice on the same day is safe. The script replaces today's row instead of adding a second one.
The log lives inside the folder as a hidden file, so it travels with the writing.

Running it

chmod +x wordlog.py
./wordlog.py ~/writing

Output looks like this:

2026-10-21: 48210 words total, +734 since last entry

Making it automatic

I don't want to remember to run it. On Linux or macOS, a cron job at the end of the day takes care of that. Open your crontab with crontab -e and add:

55 23 * * * /usr/bin/python3 /home/you/bin/wordlog.py /home/you/writing

Adjust the paths for your system. If your machine is usually off at midnight, pick a time when it's on, or just run the script by hand when you finish for the day.

Reading the log

Because it's a plain CSV, you can open it in any spreadsheet and make a chart. For a quick look in the terminal, this prints the daily difference:

awk -F, 'NR>1 {print $1, $2-prev} {prev=$2}' ~/writing/.wordlog.csv

The catch

This counts net words. On an editing day, when I cut a weak section, the number goes negative. At first that bothered me. Now I like it. A negative day usually means the piece got better, and seeing it written down reminds me that deleting is part of the work too.

If you want gross words written instead, you'd need to track changes per file, for example with git diff --word-diff and counting the added words. That's a nice next step, but the simple version has been enough for me.

Do you track your writing output at all, or does a number like this just add pressure?

Checking your writing in your editor with LanguageTool and Vale

Emma Jansen — Wed, 21 Oct 2026 15:05:15 +0000

For code we have linters that catch every missing semicolon. For prose, most people still rely on "I'll give it a quick read later." I use two tools side by side to check my writing, and each one does something different.

LanguageTool: spelling and grammar

LanguageTool is an open-source grammar and style checker that supports English and many other languages. You can use the browser extension, but if you write in your editor it's nicer to have it right there.

In VS Code you can do that with the LTeX+ extension, which uses LanguageTool for Markdown, LaTeX and other formats. Set the language in your settings:

{
  "ltex.language": "en-US"
}

If you'd rather use LanguageTool from a script, there's an HTTP API:

curl -s https://api.languagetool.org/v2/check \
  -d language=en-US \
  --data-urlencode "text=This sentence contain a mistake that get caught."

You get JSON back with the issues it found and suggested fixes. Keep in mind that the free public API has limits. For large amounts of text, or anything confidential, you can also run LanguageTool locally; the standalone version includes its own HTTP server.

Vale: your own style rules

LanguageTool checks whether something is correct. Vale checks whether it fits your style. Vale is an open-source command-line prose linter. You write rules in YAML and Vale runs them over your Markdown files.

You can install existing style packages, but writing your own rules is easy. A minimal .vale.ini:

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale, MyStyle

And a rule in styles/MyStyle/Wordy.yml to catch stiff, wordy phrases:

extends: substitution
message: "Consider using '%s' instead of '%s'."
level: warning
ignorecase: true
swap:
  utilize: use
  in order to: to
  prior to: before
  in the event that: if

Run it:

vale article.md

Vale points out, line by line, where your text breaks your own rules. It's also easy to add to a CI pipeline, so the documentation in a repo keeps a consistent style.

Why use both

LanguageTool catches the "contain/contains" slips. Vale enforces the choices you made yourself: no corporate filler words, consistent spelling of product names, no "click here." Together they save a whole round of proofreading.

What's in your prose-linting setup? I'd love to hear which Vale rules other people swear by.

DEV Community: Emma Jansen

I draw a bar for every sentence to find the ones that run too long

What the script shows

The script

Running it

What I look for in the bars

What it won't tell you

I keep my article drafts in Git: the five commands I actually use

1. git init: once per project

2. git add and git commit: save a version with a note

3. git diff --word-diff: see what I actually changed

4. git log: find the version I'm looking for

5. git show: get an old paragraph back

What I skip

My personal style sheet is a text file and a short Python script

What goes in the file

Why a plain file

A short script that reads it

A few things I learned using it

Keeping it alive

Write twenty headlines, keep one: my plain-text headline routine

Finish the draft first

Twenty lines in one file

Sort them by length

Cut the ones that hide the topic

Test the survivors against the first paragraph

Keep the file

Let your computer read your draft back to you

Turn the Markdown into plain text first

Let the voice read it

Put it in one small script

What to listen for

Where it fits in my routine

One article, four formats: how I repurpose long pieces without copy-paste

Start from the outline, not the text

Write one sentence per format first

Rewrite the opening for each audience

Keep one detail, drop the rest

Link back only when it helps

Keep all versions together

What changed for me

A small Python check for front matter in a folder of Markdown drafts

What it checks

The script

Running it

Making it hard to forget

What it doesn't do

A small Python check for front matter in a folder of Markdown drafts

What it checks

The script

Running it

Making it hard to forget

What it doesn't do

Nobody clicks "click here": a small Python check for vague link text

What a good link looks like

The script

Running it before I publish

What it won't catch

A tiny script to track how many words I write per day

The idea

The script

Running it

Making it automatic

Reading the log

The catch

Checking your writing in your editor with LanguageTool and Vale

LanguageTool: spelling and grammar

Vale: your own style rules

Why use both

1. `git init`: once per project

2. `git add` and `git commit`: save a version with a note

3. `git diff --word-diff`: see what I actually changed

4. `git log`: find the version I'm looking for

5. `git show`: get an old paragraph back