A cleaner Markdown pitch, with a Go toolchain attached
Shrimple is a small, opinionated markup format for people who want documents that stay easy to read in plain text and still come out looking tidy when rendered to HTML. It trims away some of the messier habits that pile up in ordinary Markdown workflows, then asks writers to follow a narrower set of rules. That’s a friendly sell if you’ve ever stared at a README and thought, “This could be less fussy,” and a slightly annoying one if you’ve already memorized your own preferred Markdown quirks.
In a week when tech news keeps bouncing between AI policy fights, platform changes, and the usual digital culture skirmishes, Shrimple feels refreshingly low-drama. It is not trying to be the future of writing. It is trying to be less irritating than what many people use now. That’s a much smaller claim, which may be why it sounds more believable.
The workflow matches that attitude. Shrimple is built around the Go toolchain, so the first step is a straightforward build. After that, you run the command-line tool against a README-style source file and let it produce HTML from there. No web app. No notebook-style interface. No pop-up wizard asking how you feel about your content structure. Just compile, run, render.
The appeal is plain enough: keep the source file clean, then let the output look like it was meant to be read by another human.
Two output switches do a lot of the heavy lifting for everyday use. One adds default styling, which matters if you want the rendered page to look presentable without writing your own CSS right away. The other wraps the result as a full HTML page, so you get a complete document rather than a fragment meant to be dropped somewhere else. Between those two options, Shrimple covers the common “I just want this to look decent” and “I need an actual page” cases without making you hunt through a maze of settings.
That setup gives the project its hook. Instead of treating Markdown as a loose convention that everyone bends in their own direction, Shrimple makes a cleaner, more controlled offer: learn its rules, and the output stays predictable. For some writers, that kind of opinionated formatting will feel like relief. For others, it will feel like swapping one set of annoyances for another. Both reactions make sense. The real question is whether a markup tool can be strict in a way that still feels pleasant, especially for the everyday stuff people write most often, the README files, notes, and documentation pages that live at the boring center of the web.
However it lands, that’s a sharper proposition than yet another “Markdown, but different” pitch. Shrimple is betting that clarity in the source and cleanliness in the output can make the whole experience less grumpy. If it works, the format may win people over for reasons that are almost embarrassingly practical: fewer visual distractions, a simpler build path, and HTML that doesn’t look as if it was assembled in a hurry.
What Shrimple changes in everyday writing
Once the Go CLI has rendered a file, the next question is what you actually have to type in the source. That’s where Shrimple makes its opinion known. It keeps the document readable as plain text, but it doesn’t ask you to preserve standard Markdown habits just because they’re familiar. If you’re used to GitHub’s Markdown syntax guide, the biggest surprise is not that Shrimple can make HTML. It’s that it shifts where a few common pieces live, so the source file looks calmer while the rendered page still comes out clean.
Shrimple’s trick is restraint: it keeps the source file sparse by giving each piece of content one place to live.
Links are the first obvious example. In standard Markdown, the URL often sits right there in the sentence, surrounded by brackets and parentheses, which is fine until a document fills up with them. Shrimple pulls that address out of the line and parks it in a matching footnote instead. The sentence keeps the link text, the footnote carries the destination, and the source stops looking like it was fed through a punctuation machine. The result is easy to scan. You can read the paragraph without tripping over a long URL, then check the note when you actually need the destination. Writers who spend time in browser-based editors like StackEdit or Glyphmd will recognize the appeal immediately, even if Shrimple is stricter about how that tidiness gets achieved.
Code gets its own treatment too. Rather than sitting close to the surrounding text, code blocks are indented more deeply, so they stand apart without needing extra decoration. That extra indent sounds minor on paper, but on the page it changes the rhythm. Ordinary prose stays in one visual lane, and code clearly moves into another. Shrimple also lets you add an optional language label at the top of the block, which gives syntax-highlighting tools a hint about what they’re looking at. A Go snippet can be marked as Go, a shell command can be marked as shell, and a highlighter can stop guessing. For technical documents, that keeps the markup lean without making the code feel hidden.
Lists follow a similar logic, just with more rules than most Markdown users are probably used to. Bullet lists and numbered lists use a two-space indent, so the structure is compact but still visible at a glance. When an item runs long, the continuation lines drop into a deeper hanging indent rather than drifting into the left margin and making the list hard to parse. That matters more than it sounds, especially in documentation where one item can stretch into a small paragraph. Shrimple also normalizes numbering automatically, so you don’t have to fuss over whether an item is 1. or 7. while drafting. If you’ve ever renumbered a list by hand after moving a paragraph, the relief should be obvious. The format looks tidy in the source, and it can stay tidy even when the ordering changes.
Headers are handled with underline-style syntax instead of the hash-mark approach most people associate with Markdown. So instead of typing a row of # symbols in front of a heading, you write the heading text and let an underline define its level. That makes the structure feel a bit more document-like and a bit less like you’re entering a forum post from 2009. It also makes larger blocks of text easier to skim in plain form, because the heading is still just a line of words, not a line of symbols. Shrimple’s note blocks work in a similarly restrained way. They begin with an all-caps label, then sit in an indented block class that separates them from the main flow. In practice, that gives you a clean way to mark side comments, warnings, or asides without piling more inline markup into the paragraph itself.
If that sounds picky, it is. That seems to be the point. Shrimple is not trying to look permissive; it’s trying to keep writers from improvising ten different ways to express the same structure. On a short README, the difference may be subtle. On a longer document, the lack of visual clutter adds up fast. You spend less time decoding your own source and more time checking whether the content actually says what you meant. For the kind of writing that lives in docs, project notes, and other text-heavy files, that trade can feel oddly refreshing. It’s still markup, but with fewer loose ends hanging off the page.
The extra tricks: dictionaries and static-site output
By the time Shrimple gets past the basics, it starts behaving less like a text format and more like a small publishing system with opinions. The dictionary feature is the cleanest example. Instead of forcing writers to wrap every repeated term, note, or special phrase in extra markup, Shrimple can scan for words or phrases during parsing and then apply styling at render time. That means the source stays readable, but the final HTML can still carry consistent classes, emphasis, or other presentation rules where they belong.
The setup is split on purpose. Shrimple can use separate parse and render dictionaries, and the command-line flags let you point each stage at its own file. That sounds fussy at first, but it gives the tool a useful split of labor. One dictionary tells Shrimple what to notice in the text. The other tells it how to present what it found. For document formatting work where the same term keeps showing up across a manual or reference page, that can save a lot of repetitive markup. It also keeps the author from babysitting every instance by hand, which is usually where plain-text systems start to feel less pleasant than they advertised.
The whole point is to keep the source file calm and let the renderer do the boring part.
The idea feels especially at home in a tool that already cares about clean text and tidy output. If you’ve used Typora, you probably know the appeal of writing in a file that stays readable even while the software handles the visual polish. Shrimple takes a more formal path than an editor does, but the instinct is similar: reduce noise in the source, keep the result predictable, and don’t make writers fight the syntax just to mark one phrase differently from the next. It’s a small thing until you’re three dozen pages into a guide and you realize how many times you would have had to paste the same wrapper again and again.
The dictionaries also make Shrimple feel less rigid than a lot of Markdown variants. Standard Markdown, as defined in places like CommonMark, is built around a relatively narrow set of inline and block rules. Shrimple keeps that plain-text discipline, then adds a second layer where the author can predefine how certain words should be treated. That’s a neat fit for recurring labels, product names, or house-style terms. It doesn’t replace footnotes or code blocks. It sits beside them, quietly handling the repeated bits that usually clutter the page.
That same attitude shows up in the static site generator, which is where Shrimple stops being just a formatter and starts acting like a documentation pipeline. Point it at a directory tree full of Shrimple files and it will turn that structure into HTML pages. The folders become the outline. The files become the pages. A nested menu can be generated automatically, and optional previous and next links can be added so readers can move through a sequence without hunting around for the next page in the set. For internal docs, product manuals, or a compact knowledge base, that removes a chunk of manual linking work.
The ordering rules are practical rather than magical. Numbered folders and files keep their place, so a structure like 01, 02, 03 will stay in that order when the site is built. If a file and a folder share the same name, Shrimple treats that match as an index page, which is the kind of detail that saves a person from fiddly directory naming later. The generator also tries to avoid unnecessary work on reruns. If only one file changes, only that file gets rebuilt. The rest of the site can stay put, which matters a lot once a folder has grown past a handful of pages.
There’s a reason this part of Shrimple reads more like tooling for a docs team than a one-off markup experiment. It links source files, page structure, and output in one pass, while still leaving room for the kind of small formatting controls that plain Markdown usually makes awkward. In a larger writing setup, that means less glue code, fewer manual steps, and fewer excuses to leave the source messy because “the final page will fix it.” Sometimes the boring part is the point, and here the boring part is doing a fair amount of the heavy lifting.
Pleasant, maybe — but only for the right kind of writer
Shrimple’s pitch is easy to grasp once you’ve seen the pattern: keep the source file spare, make the output page tidy, and accept that the tool wants things done its way. That tradeoff is the whole story. A writer gets a cleaner-looking document and a more controlled HTML result, but the cost is real. Shrimple does not try to melt into the background the way plain Markdown often does. It asks you to learn its rules, remember its punctuation, and stop expecting every familiar Markdown habit to carry over untouched.
That will feel natural to some people and mildly annoying to others. If your work lives in docs, README files, notes for internal tools, or a personal site where you care just as much about how the text file reads as how the final page renders, Shrimple starts to make sense fast. Documentation writers tend to notice small irritations that regular prose can ignore. A link format that keeps the text uncluttered. Lists that behave the same way every time. Headings and notes that look consistent without a lot of visual fuss. Those are the sort of details that can save time when you’re updating a project page at 11 p.m. And don’t want to fight your markup.
It probably fits developer-facing content best, which is no surprise given the surrounding ecosystem. README pages, API notes, release docs, setup guides, even a static personal homepage with a few repeated content types all benefit when the source stays easy to scan. Shrimple’s rules make the file itself feel more orderly, and that matters when the file is what you edit most often. If the page is going to be revised repeatedly by the same person, a little structure goes a long way. A prettier output page is welcome, but the bigger win is often the text file you can open six months later without feeling like you’ve stepped on a rake.
The tradeoff is simple: Shrimple removes a lot of visual clutter, but it replaces guesswork with its own rules.
There’s also a practical side to the appeal that shouldn’t get dressed up as theory. Fewer inline distractions mean the document is easier to read before it’s rendered. Cleaner HTML means the output is easier to style, inspect, and ship. The path from source text to published page is built in, which saves writers from assembling their own little chain of scripts every time they want to turn notes into a site. For teams that already live around developer tools, that can be enough to make the format worth a look. You type in one place, run the build, and get something that looks like it was meant to be published instead of something that wandered out of a code comment.
Still, Shrimple is narrow by design, and that narrowness will be the dealbreaker for plenty of people. If you want maximum portability, broad editor support, and a format almost everyone recognizes immediately, plain Markdown keeps the upper hand. Shrimple is choosier. It works best when you’re willing to trade away some familiarity in exchange for a quieter source file and a more disciplined output. That’s a fair bargain for documentation-heavy work, personal publishing, and developer notes. It’s less appealing when you just want to jot something down and move on.
So the final read is pretty clear. Shrimple doesn’t look like a universal Markdown replacement, and it probably won’t become one. It looks more like a repair job for the people who always felt Markdown carried a bit too much visual clutter for everyday writing. For them, a tighter syntax and a cleaner page might be exactly the point.
