DEV Community: Emma Jansen

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.