Eight guides sit in the TipBop repository. On 17 November three of them were live on tipbop.com and listed in the sitemap. The other five were held as drafts. We asked for one of the five and got a 404, which is the point. The five were later checked and published, and all eight are live now.
TipBop’s plain-English guides to digital tipping are written for customers and workers. This post is about the machinery under them, and about why a guide can go wrong in ways a normal page cannot.
The build fails, so nobody has to remember
A guide is a text file with a header and a body. A small loader reads each file and checks it. The checks are plain functions with no server in them.
There are 17 rules by our count. They cover the title and description length, a short answer under the heading, and a body between 700 and 1,500 words. They also catch dashes, banned hype words and a wrong spelling of the brand name. The last section must be the questions, and every guide it links to as related must exist.
The build command exits with an error if any file breaks a rule. The same rules run again in the repository’s gate, so a bad guide turns the gate red before it can be pushed.
The part we trust most is how the rules are tested. Each rule has a test that takes a clean fixture guide and breaks one thing. Examples are a title that is too long, an en dash, a missing questions section and a picture with no alt text. The test asserts that this exact rule fires. A second test checks that the clean fixture passes with no errors and no warnings.
Without the second test, a checker that rejects everything looks like a strict one. Without the first, a checker that accepts everything looks like a clean bill of health.
Some advice only warns. Too few questions, or too many sections, prints a note and does not stop the build. We kept the fatal list short so that people do not learn to ignore it.
The server has no filesystem
TipBop runs on a Worker, which cannot read a folder of files at request time. So the build turns the guides into one generated module, and the Worker serves that.
A generated file is a second copy, and a second copy goes stale. A test regenerates the module from the real guides and compares it with the committed one. If a guide changed and nobody rebuilt, the test fails and says to run the build. It is the same habit we use for shared money test data: make a machine compare the copy with its source on every run.
The same test file checks that each live guide has its share-card image, built from the guide’s current title. The card generator is tested too, including that white text on TipBop’s pink clears the 3:1 contrast that WCAG asks of large text.
The markup cannot disagree with the page
Search engines read structured data that sits next to a page. If that data says one thing and the page says another, the markup is wrong.
So the questions markup is never written by hand. It is built from the visible questions section, word for word. A test parses the finished data as data, not as text, and compares every question and answer with what the page shows. If a guide has no questions section, the markup is left out.
The short answer under the heading is held to the same standard. A test checks that it sits directly under the H1, because it is the passage a reader, and a search tool, is most likely to take away.
A held guide leaves no trace
A draft is held, not hidden by a style rule. It is left out of the index, the sitemap, the machine-readable site summary and the navigation, and its own address answers 404. A related-guides link to a held guide appears as plain text, not as a link, so a draft cannot be found by following a sibling.
If no guide is live at all, the whole section disappears. The index answers 404, and no link to it appears on the site. A test runs that case on purpose, with nothing live and with only a draft.
The legal guides are a different kind of hold. A guide about a law has a reviewed date that the build insists on. But the build cannot know that a person has read it, and we do not pretend it can. The hold is a human step. A guide that deals with law stays a draft until someone has read it, and publishing is one small change with its own gate and deploy.
What went wrong
Our first version served the guides and their share cards from a file route that did not reach paths as deep as the cards and the guide pictures. We found it and fixed it in a follow-up. The fix came with a test that fetches a card three levels deep and a picture four levels deep. It also checks that a path trying to climb out of the folder is refused.
One more boundary mattered. The guides are public information pages, so they carry visit statistics under the same consent rules as the FAQ. The tip page, the receipt and the worker app stay clean, and their tests did not change. We only added the guide pages to the list of pages that may carry statistics.



