# TrunkBasedDevelopment.com: the Hugo source behind a book on trunk based development > paul-hammant/tbd holds the source for the website and the book that carries Paul Hammant's trunk based development writing, built with Hugo and published to Netlify. It is a writing pipeline rather than a software product, and the contribution rules are as much a part of the project as the code. **paul-hammant/tbd** — Source for TrunkBasedDevelopment.com - Repository: https://github.com/paul-hammant/tbd - Website: https://trunkbaseddevelopment.com - Stars: 548 · Forks: 154 - Language: CSS - License: NOASSERTION - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/paul-hammant-tbd ## A book that ships as a website, with the book as a subset The repository description is one line: source for TrunkBasedDevelopment.com. That undersells the scope a little. The project is Paul Hammant's writing on trunk based development, and it exists in two forms at once. The site is the long form, free to read and organized by topic, while a book is a bounded edition of the same writing, and the repository carries the artefacts for both. There is a book_cover.jpg and a book_page_start.html at the top level, alongside a Logo.graffle and TbdArt.graffle source files for artwork, which tells you the cover and interior design are edited in the same place as the prose. The primary language listed for the repository is CSS, not Markdown or Python, which is a small signal with a real explanation. The markup is generated by a theme, and the repository carries a themes directory, so a substantial part of the tracked code is presentation rather than content. The content itself lives in a content directory, and a static directory holds assets. The site is built by Hugo and deployed with a netlify.toml in the root, so the publishing path is a static build pushed to a hosting platform rather than a runtime application. For an engineer assessing adoption, the honest framing is that this is a publishing project with a code toolchain. There is no library to depend on, no API to integrate, and no plugin contract to program against. What there is: a working setup you can run, a set of editorial rules you must follow, and a deployment that already works. ## Translations live on sibling branches, not in a folder The contribution instructions define three branches with distinct jobs. English contributions go to master. Chinese translations go to the cn branch or the tw branch, which serves a separate site at tw.trunkbaseddevelopment.com. The stated reason for that split is keeping the two languages in step. The instruction says the translations should always reflect the English content, and that merge tracking is used for that purpose. This is a workable but manual arrangement. A translator adds a file on a branch, and the person who merges English content into the translation branches has to resolve whatever moved underneath. A directory based translation setup, where each language is a subfolder of the same content tree and the build renders several languages from one checkout, avoids that merge work entirely, since the tooling then handles which files belong to which language. The trade-off sits in how much the two approaches share. With branches, a translator gets the exact English text to work from in a familiar git workflow, and the English site is never at risk from a translation edit. With folders, a single pull request can change two languages at once, which is easier to review and harder to break. For a contributor this matters before you write a line. If you submit a Chinese translation, you are expected to target cn or tw, not master, and you are expected to work from current English content. The rules make no mention of a separate repository for translations, so a fork with its own translation workflow would be an unusual thing to propose here. ## Running the site locally takes one Hugo command The local run instructions are short because Hugo does most of the work. The guide asks you to install Hugo for yourself, clone the repository, and enter the tbd directory, then launch the Hugo server. ```bash hugo server ``` The next step tells you where to look, which is the local address on port 1313. Once the server is running, editing the Markdown sources hot reloads the pages, so a change appears in the browser without a manual rebuild. That is the whole development loop, and it is a good illustration of why a static site generator suits a writing project: the feedback cycle is a browser refresh. Two things to know before you start. The instructions say to install Hugo yourself rather than providing a pinned version, a lock file for the toolchain, or a container, so the behaviour of your local build depends on which Hugo you have. The repository does carry a flake-style or lock style project with a .gitignore, but nothing in the top level listing pins the Hugo version, and a theme upgrade on your machine can therefore change the output without any change to the repository. The second is that the theme is assumed. The contribution rules warn against H1 tags because the Hugo theme does not do the right thing with them. That is a small sign of how much the markup contract is owned by the theme rather than by the content, and it is the kind of detail that only shows up once you render the site. ## Front matter dates are fake on purpose, and they drive navigation Contribution rule nine is the most surprising line in the whole guide. It says to be careful with the dates in the front matter of the Markdown sources, and explains that they are being contrived, because they guide the prev/next article navigation. So the dates on these articles are not publication timestamps. They are an ordering key. The site presents articles in a sequence, and that sequence is derived from the date field, which means the dates have to be assigned with care and changed when the intended order changes. Any contributor who assumes a date records when something was written, or who tidies up a date that looks wrong, can silently reorder the site. This is also a good example of documentation being an instruction rather than a description. A normal project documents what a field is for. This one documents what a field is not for, and warns about the specific mistake a well meaning contributor would make. Rule six adds a related constraint. Links to blog entries and tweets should go in a collapsed refs section, without forward links inline, and the references should stay in chronological order per section. In other words, a citation is not an inline footnote at the point of the claim, it is a list at the end of the section, in time order, hidden behind a disclosure. The two Python scripts in the repository root, one named footer_refs.py and one named fix_html.py, are consistent with that: they exist to manipulate the rendered reference and HTML structure rather than to serve the site. ## Eleven editorial rules that read like a style guide The contribution rules are the substance of the project, and they are more prescriptive than a code review would be. The first requirement is simple: contribute if you have something to add to the site. Then come the constraints. Keep the message multi-level, meaning beginner, intermediate and advanced, so a single article has to serve readers at different points of experience. Understand that some people are diametrically opposed to the approach, and that any attempt to convince them has to be very careful. Use no inflamed language. Abide by the golden rule and write according to the High Esteem value. Those are not stylistic preferences, they are the reason the book reads the way it does, and the rules exist to keep the tone of contributed writing consistent with the existing text. Then come the mechanical ones. Links to mainstream books and Gartner-style reports go inline, with affiliate codes that contribute to the original authors where applicable, which means the project treats citation as a revenue share as well as a reference. Avoid H1 tags, for the theme reason described earlier. Do not shorten to TBD beyond the single use that already exists, so the abbreviation carries exactly one appearance in the whole body of the work. Repo and Deps should be expanded to their long form. That last rule is a small example of a larger principle. The site is written for readers who are not software engineers, and the rules enforce that audience. It is also a rule that a repository full of engineering writing often breaks, which is presumably why it is written down. ## Python helpers and a numbered table of contents Four Python files sit in the repository root, and their names describe a build pipeline that the site itself does not mention. There is fix_html.py, footer_refs.py, toc_numberer.py and toc_number_applier.py. The last two read as a two stage process. A numberer produces numbers, and an applier puts them somewhere, which suggests the table of contents is generated in a separate step from the numbering being written into the page. A single pass that numbered and applied in one go would need only one script, so the split implies an intermediate representation, probably a JSON file that the numbering tool writes and the applier consumes, and probably a place where a human can correct the numbers before they are stamped into the Markdown. The top level listing also contains book_page_start.html, a hand maintained HTML fragment that presumably starts the book rendering, and a .gitignore that keeps build output out of the tree. The comparison with a plain Hugo site is instructive. A typical Hugo project has content, a config file, a theme, and nothing else. This one adds Python at the root, and the addition is not for the server but for the editing. The site build and the content preparation are separate concerns, and the latter is where the scripting lives. For a contributor this is the part to read first, because if your change touches numbering or references, one of these scripts is what will rewrite your file, and the guide does not say which script to run or in what order. ## Netlify hosting, a custom licence and no tagged releases The repository has no GitHub releases, and the project versioning is not tied to the book editions in a way the repository exposes. The branches do the versioning work instead, with master carrying English and cn and tw carrying the Chinese editions. The last push was on 2026-10-20, so the site is being edited regularly, but there is no release artefact to download, no changelog and no semantic version for the site content. Deployment runs through a netlify.toml in the repository root. That file is the only deployment configuration in the project, and the guide does not describe the build command, the publish directory or any environment settings for it. Netlify also supports deploy previews and branch based staging in general, but nothing in the project states whether the cn and tw branches get their own previews, so that behaviour is a question for the maintainer rather than something the configuration answers. The licence deserves attention because it is unusual. The repository is marked as carrying a licence that GitHub cannot classify, and the pointer to a LICENSE.md file in the root is the only way to read it. This is not a standard permissive licence and it is not one of the common open source licences. If you plan to reuse the prose, the images or the code, read LICENSE.md yourself and take advice on what it permits. Nothing in this review interprets its terms. One more operational note for contributors. The guide asks for pull requests if you are not a committer, and for larger changes to open an issue first, in the same spirit as the merge tracking used for translations. The project is a single maintainer's editorial work with a defined voice, and the process reflects that. ## Conclusion This repository suits an editor or translator who wants to extend a book that already has a defined voice, a working Hugo toolchain and a deployment path, and it does not suit someone looking for a reusable static site template or a software library. Before you open a pull request, read the eleven contribution rules, because the front matter dates and the collapsed references structure are load bearing, and check the LICENSE.md file since the licence is a custom one rather than a standard open source licence. ## FAQ ### How do I run the TrunkBasedDevelopment.com site locally? Install Hugo, clone the repository, enter the tbd directory and run hugo server. The site is then served on localhost:1313 and pages hot reload as you edit the Markdown sources. ### Where should I send a Chinese translation of the content? Translations go to the cn or tw branch rather than master, with tw serving a separate site at tw.trunkbaseddevelopment.com. The translations should always reflect the current English content, and merge tracking is used to keep the two in step. ### What are the contribution rules for the tbd repository? The rules ask contributors to keep the message multi-level, avoid inflated language, put blog and tweet links in a collapsed references section rather than inline, avoid H1 tags, expand Repo and Deps to their long form, and not shorten to TBD beyond its single existing use. ### Why are the article dates in the front matter inaccurate? The dates are contrived on purpose because they drive the prev/next article navigation on the site, so they act as an ordering key rather than a publication timestamp. Contribution rule nine warns contributors to be careful with them. ### What licence is the tbd repository under? It carries a custom licence that GitHub cannot classify, and the terms are in the LICENSE.md file in the repository root. The repository is not under one of the standard open source licences. ## Sources - [Issues](https://github.com/paul-hammant/tbd/issues) - [paul-hammant/tbd on GitHub](https://github.com/paul-hammant/tbd) - [Project website](https://trunkbaseddevelopment.com) - [README](https://github.com/paul-hammant/tbd/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/paul-hammant-tbd