Adding an automated prose checker for my posts

If you write blog posts by hand (I hope you do), but are looking for some automated checks to improve the quality and clarity of your posts, here’s the setup I use.

I like to write blog posts, but as a human writer I make plenty of mistakes. Including duplicating words words randomly. My eyes just filter them out. I wanted to improve my writing, but still keep all my posts written by hand, so I put together a few processes to help improve.

Static analysis with Vale

Vale is a tool that acts like a static analyzer for your text. This includes things like spelling and word-choice. It’s popular in online technical documentation in use by Microsoft, Google, and others to ensure technical documentation is consistent.

The configuration started with just identifying duplicates:

1
2
3
4
5
6
7
8
# .vale.ini
StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale
Vale.Spelling = NO
Vale.Repetition = YES

And integrating with my CI workflow looked like:

1
2
3
4
5
6
7
8
9
# .forgejo/workflows/build.yaml
jobs:
    build:
	    steps:
 	      - name: Analyze post text contents
	        uses: https://github.com/vale-cli/vale-action@518a9136acc6e6668ce7c00d367051e0941e87ff
	        with:
	          fail_on_error: true
	          files: '["content/", "README.md"]'

Running it manually with vale content/ gave me some immediate feedback of posts to fix:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[...]

content/posts/2026/02/replatform-rke1-k8s-to-nix-part-1/index.md  
15:32   error  'a' is repeated!     Vale.Repetition    
354:36  error  'auto' is repeated!  Vale.Repetition    
  
  
content/posts/2026/03/ads-and-data-brokers-are-out-of-control/index.md  
44:54  error  'Android' is repeated!  Vale.Repetition    
  
  
content/posts/2026/05/create-kyverno-policies-with-openwebui/index.md  
143:14  error  'what' is repeated!  Vale.Repetition    
  
✖ 15 errors, 0 warnings and 0 suggestions in 92 files.

Perfect. I fixed all those repeated words and now I’ll never make the same mistake.

Struggling with spell check

Enabling the spell check is a bit harder since my posts use a lot of technical terms, so I get 800+ errors with words referring to technical concepts.

1
2
3
4
5
6
7
content/posts/2026/06/failure-to-launch/index.md
Vale.Spelling 
 375:34   error  Did you really mean 'Kimi'?                               Vale.Spelling 
 381:122  error  Did you really mean 'md'?                                 Vale.Spelling 
 382:15   error  'logical_block_size' looks like code; format it as code.  Vale.Spelling 
 385:122  error  Did you really mean 'md'?                                 Vale.Spelling
✖ 838 errors, 0 warnings and 0 suggestions in 92 files.

For this, I need to use Vale’s vocabulary feature. Update .vale.ini:

1
2
3
4
5
6
7
8
9
StylesPath = styles
MinAlertLevel = suggestion

Vocab = terms

[*.md]
BasedOnStyles = Vale
Vale.Spelling = YES
Vale.Repetition = YES

Then create a file called styles/config/vocabularies/terms/accept.txt and add each word as a new line:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Clickhouse
containerd
Forgejo
GOModel
Helicone
Kubernetes
Langfuse
NuGet
Postgres
Syft
[...]

Make sure to format words in proper casing, as the Vale.Terms rule will enforce it. That’s why I use Clickhouse and containerd since those are the generally accepted formatting.

54:9     error  Use 'Syft' instead of 'syft'.    Vale.Terms

Vale also tries to enforce spelling on the front matter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
---
title: "Signal Lost: An upgrade to Linux broke Postgres"
slug: upgrading-linux-broke-postgres
date: 2026-08-24T23:42:00-07:00
tags:
- kubernetes
- linux
- bug
---

content/posts/2026/08/upgrading-linux-broke-postgres/index.md  
4:29  error  Use 'Postgres' instead of 'postgres'.  Vale.Terms

An easy fix is to exclude applying to the slug and tags, by adding the following to .vale.ini

1
2
3
4
5
IgnoredScopes = text.frontmatter.slug, text.frontmatter.tags, code, tt, kbd, samp
Vocab = terms

[*.md]
# ...

With 800+ errors across 360 files going back over ten years, I did not want to retroactively fix everything, so I excluded the old posts by adding this to .vale.ini:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
StylesPath = styles
MinAlertLevel = suggestion
IgnoredScopes = text.frontmatter.slug, text.frontmatter.tags, code, tt, kbd, samp
Vocab = terms

# all posts going forward
[*.md]
BasedOnStyles = Vale
Vale.Repetition = YES
Vale.Spelling = YES

# Older posts: Ignore spelling so I don't have to fix everything
[content/posts/201*/*]
Vale.Spelling = NO
[content/posts/2020/*]
Vale.Spelling = NO
[content/posts/2021/*]
Vale.Spelling = NO
Vale.Terms = NO
[content/posts/2022/*]
Vale.Spelling = NO
[content/posts/2023/*]
Vale.Spelling = NO
[content/posts/2024/*]
Vale.Spelling = NO
[content/posts/2025/*]
Vale.Spelling = NO
[content/posts/2026/0*]
Vale.Spelling = NO

All posts moving forward will have to pass the spell checker. If I need to exclude a word, such as the Easter egg at the top of this post, I can:

1
Including duplicating <!--vale off-->words words<!-- vale on--> randomly

More with Vale

Vale has a ton of rules to add. For example, adding BasedOnStyles = Vale, proselint means that Vale is going to flag words like Hopefully or cliches like Slow as molasses (actual quotes from posts.) I excluded those rules because these posts aren’t supposed to be legal docs, they are written by a human.

Content review with LLMs

I feel strongly that my blog posts should be human written because I write for other humans. I want my passion and interest to be shared widely. That’s why I don’t use LLMs to write posts. However, I appreciate an LLM’s ability to read a post and give feedback to me on clarity, accuracy, and structure. Sure, only a human can tell me that a post is absolute nonsensical, but an LLM can at least tell me if it’s unreadable to an AI.

That’s why I use it as a first-pass before publishing. Mine will even do basic correct checking on claims I make in posts.

Sometimes, I phone a friend to give feedback.

I started with an AGENTS.md like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# Post Review

When reviewing posts, ensure that:

* **Proper spelling and grammar**: Check for typos, double negatives (e.g., "didn't not understand"), singular/plural consistency, and empty section gaps when elaborating on edges (e.g., advantages/disadvantages without details)
* **Accessibility**: All images must have descriptive alt tags (not just `![](filename.png)`)
* **Meaningful conclusion**: Every post must have a substantive conclusion that touches on key takeaways based on the post's scope and intended learning; consider adding an explicit "Key Takeaways" section before the conclusion
* **Headings hierarchy**: Verify headings are properly numbered and nested (H1 → H2 → H3), semantically useful, and aligned with content focus
* **Pros/cons presentation**: Posts discussing trade-offs should clearly present both sides with rationale
* **Workflow clarity**: Technical walkthroughs should explain the progression (when decisions were discovered vs when solutions were implemented)
* **Formatting consistency**: Code blocks should include a language tag
* **Abbreviation clarity**: Expand abbreviations upon first use (e.g., API, RBAC)
* **YAML front-matter**: All posts should contain a date with timezone, author, title.

* **Content consistency**: Check for inline updates or missing info that stray from the main theme
* **Format/Output links**: User instructions must match tested and verified approach
* **Consistency with content progression**: Avoid tags that feel out of place or misaligned with actual content flow
* **Summary alignment**: Tags descriptions should match actual content topics, not fillers
* **Readability**: Avoid text walls above 54 chars
* **Structure clarity**: For multi-section posts, explicitly state the progression (e.g., discovering the problem vs. choosing an alternative)
* **Title consistency**: Check for overlapping title references within headings that cause confusion
* **Search indexing**: Identify extraneous images that don't contribute to understanding
* **Visual clarity**: The interactions, emphasis on function vs appearance, and functional utility of custom visuals
* **Visual warning status**: Include disclaimers describing boundaries, limitations, or caveats of any outcome
* **Visual template**: Each self-contained post should include at least one visual (code diff, terminal session, dashboard screenshot)
* **Visual type appropriateness**: Choose styles appropriate for technical audience (code diffs, CLI output, dashboard mocks)
* **User command markup**: Mark challenges or tool steps with appropriate markup for clarity
* **User-friendly output**: Provide examples of user-facing output (terminal prompts, CLI output)
* **Structure & progression**: Ensure all sections connect logically; avoid disjointed or segmented flow

## Content & Structure

1. **No meandering intro.** The title plus first three sentences must tell the reader:
   - Who the article is for (e.g., "programmers who use Go"), and
   - What benefit they get from reading it (learn a skill, understand a concept, a new perspective, or entertainment).
   - Flag any preamble — backstory, historical context, biography, subtitle, decorative image, or famous quote — that appears before the value proposition. Preamble counts as meandering.

2. **Minimize assumptions about reader knowledge.** Don't assume the reader shares the author's exact background ("the reader knows everything I know except this one thing").
   - Flag unexplained jargon, especially in introductory articles (e.g., explaining Docker in terms of cgroups or BSD jails).
   - Every technical term should either be common for the target audience or briefly defined in plain language.

3. **Don't use links as a substitute for explanation.**
   - Any link pointing to an external page as the *only* explanation of a term or concept is a violation — links should be optional bonuses, not prerequisites.
   - Inline the minimum explanation needed to keep the reader of the article. The reader should be able to understand the post from start to finish without clicking any links.

4. **No sequel injection.** The article must not open with a reference to a previous post or rely on prior knowledge of the author's earlier articles ("In part one, we learned...").
   - Linking to related posts is fine, but only alongside a summary of the relevant context, and never in the introduction.

## Tone

5. **No excessive formality.** Flag prose that sounds like a legal document or corporate memo (passive voice, pompous phrasing like "were utilized throughout the duration of the project's lifetime"). Prose should read like a knowledgeable colleague speaking casually — personable and unpretentious, with room for personality and humor.

Then as I iterate on revisions, I ask for feedback.

For example, it gave me:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# The good stuff
- Your thesis lands immediately. The fake duplication in the first paragraph is a genuinely funny hook, and the post is about something concrete: the "I'll never do it again" line is the best joke in the post.
- The structure is sound. Problem → fix → new problem → fix, twice, then the LLM pass. Each config is shown in full context rather than as fragments.
- The evidence is great. Real vale content/ output, real file paths, real error counts. That's the part readers trust most.
- The "human written, LLM reviewed" stance is the strongest idea in the post and gets a direct, quotable sentence ("only a human can tell me that a post is absolute nonsensical").
  
# Must fix (factual errors)
1. Line 31 — fail_on_error doesn't exist. I checked vale-cli/vale-action@518a913's action.yml. Its inputs are styles, config, files, onlyAnnotateModifiedLines, and debug. It fails a PR by default when there are errors; there's no fail_on_error input. Drop that line so you don't send readers chasing a parameter that silently does nothing.
2. Line 34 — files expects "all" or a folder, not a JSON array. The description is literally '"all" or "<some_folder>"'. Your array ('["content/", "README.md"]') probably won't be parsed the way you expect. Use files: content and run Vale twice if you need README.md.
3. Line 148 — the stray Vale.Terms = NO under [2021/*] looks like a copy/paste slip; every other section has only Vale.Spelling = NO. Either remove it or explain why 2021 is special.
4. Line 116 — the front-matter example doesn't show a problem. The Vale.Terms error on line 4 is about the title: field ("Signal Lost: An upgrade to Linux broke Postgres"), not the slug or tags. But the fix you show targets only slug and tags. As written, the example and the fix don't connect. Either use an error that really is in slug/tags, or say "the fix also skips the slug and tags."
5. Line 120 — IgnoredScopes silently re-enables code spans? According to the docs, setting IgnoredScopes replaces the default list (tt, code, kbd, samp). You include the defaults, so you're fine — but you also add text.frontmatter.slug and text.frontmatter.tags. The docs say non-string front-matter fields are already left alone, and lists (your tags:) are "left alone" too. Worth a quick vale run to confirm the scope names actually match, because a wrong scope name in IgnoredScopes fails silently.
Should fix (reader-facing accuracy)
 6. Line 9 — "static analysis like tool" reads like a typo of "static-analysis-like". Try: "Vale is a linter for prose — it checks spelling, word choice, and phrasing."
 7. Line 9 — "in-use by Microsoft, Google" should be "in use by".
 8. Line 58 — "800+ errors" vs the output showing 838 and "across 360 files" on line 127 vs "92 files" in the paste. Are those different runs? If so, say so, otherwise the numbers look made up.
 9. Line 98 — "Make sure to format words in proper casing" is the single most useful insight in the Vale section, and it's one sentence. Add why: accept.txt is case-sensitive and Vale.Terms turns your vocabulary into a casing-enforcement rule, so Postgres in accept.txt rejects postgres. That's the "aha" moment readers will copy.
10. Line 118 — "exclude applying to the slug and tags, but adding the following": "but" should be "by".
Craft (against your own AGENTS.md)
Your AGENTS.md asks for "No meandering intro" and "who the article is for." Your intro is about you, not the reader. Run this post through your own checker and it will flag itself — which is actually a great bit you could lean into.
- Add the reader to sentence one. Something like: "If you write technical posts by hand and want a machine to catch the dumb mistakes before your readers do, here's the setup I use." One clause, keeps the joke.
- The demo run is the punchline but arrives late. The actual output block for vale content/ could show the very words words repetition if you can reproduce it in a sample file — right now the joke is orphaned from the evidence.
- "Error" vs "alert". Vale's own output says error, but MinAlertLevel = suggestion means these aren't all fatal. A sentence on which rules you've made blocking in CI would answer the obvious reader question: "does this fail my build?"
- No conclusion. The post ends on a link list. Add a short closing paragraph tying it together — human-written, machine-reviewed, and what you'd change next (e.g. a custom rule for heartbleed-style phrasing, or a Vale rule that flags "text walls above 54 chars" from the AGENTS.md).
The AGENTS.md section
- Line 163: "an LLMs ability" → "an LLM's ability".
- Line 163: "is absolute nonsensical" → "is absolute nonsense".
- Line 177 — the inline triple-backtick in a Markdown block ( `lang  ) inside a fenced markdown block is fragile. It renders, but breaks on some syntax highlighters and mangles copy-paste. Rephrase: "Code blocks should include a language tag (like go or bash)."
- Line 185 — "Avoid text walls above 54 chars" should be "above ~54 words per paragraph" (I assume you mean characters per line, but as written it's ambiguous).
- The list has two groups separated by a blank line and * YAML front-matter ending with a period while the rest don't. Minor, but your own linter would flag it.

Now, some of the feedback was incorrect. It tried, but incorrectly analyzed the implementation of vale-cli/vale-action and assumed it didn’t have the inputs I gave, but it’s still impressive that it checked. For the other feedback, I incorporated changes.

Conclusion

None of this is intended to write my posts for me. Vale helps prevent me from making dumb grammatical errors and uses proper capitalization. LLMs give me a second perspective looking at what I actually wrote. It ensures that my posts are factually correct and substantiated.

While I didn’t fix all the issues in my older posts, what I did fix makes those posts more useful for readers like you.

None of these checks verify that my posts are actually meaningful and useful to readers, but with as cheap as they are, I think it’s valuable

References

Copyright - All Rights Reserved

Comments

To give feedback, send an email to adam [at] this website url.

Donate

If you've found these posts helpful and would like to support this work directly, your contribution would be appreciated and enable me to dedicate more time to creating future posts. Thank you for joining me!

Donate to my blog