Label AI-written blog posts, add authorship page, and add a blog style guide (#10)

* Label AI-written blog posts and add authorship policy page

Co-authored-by: Scott Chacon <schacon@gmail.com>

* Add blog style guide derived from the book's voice; rewrite posts to match

Co-authored-by: Scott Chacon <schacon@gmail.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: schacon

AGENTS.md

@@ -38,6 +38,19 @@ researching, or planning around prose that a human wrote, that's fair game.
 
 When in doubt, treat it as prose and hand it to a human.
 
+## Blog posts are the exception — but read the style guide first
+
+The site's blog (`site/src/content/blog/`) is not the book. Agents may write and edit
+blog posts when asked — automated posts exist precisely to communicate project updates.
+Two hard requirements:
+
+1. **Before writing or editing any blog post, read `site/BLOG_STYLE.md` and follow
+ it.** The blog is written in the book's voice, and that guide defines it. Do not
+ write a post without loading it first.
+2. **Set `automated: true` in the frontmatter of every agent-written post.** That
+ renders the "written by AI" disclosure banner; unlabeled machine writing is never
+ published.
+
 ## Cursor Cloud specific instructions
 
 This repo is the **Pro Git** book (source in AsciiDoc). "Building" means converting

site/BLOG_STYLE.md

@@ -0,0 +1,128 @@
+# Blog writing style guide
+
+Blog posts on the Pro Git site are written in the same voice as the book.
+This guide describes that voice, derived from the book's own text, so that posts read
+like they were written by the book's authors — because stylistically, they are.
+
+**Anyone (human or agent) writing or editing a post in `src/content/blog/` must read
+this guide first and follow it.**
+
+Every trait below is illustrated with a real sentence from the book.
+
+## Voice and person
+
+**Address the reader as "you"; the authors are "we".**
+The book talks directly to one reader and speaks as its authors, never in an
+impersonal third person.
+
+> You're about to spend several hours of your life reading about Git.
+> Let's take a minute to explain what we have in store for you.
+> — *Introduction*
+
+**Use "Let's" to start a walkthrough or a worked example.**
+
+> To visualize this, let's assume that you have a directory containing three files,
+> and you stage them all and commit.
+> — *Branches in a Nutshell*
+
+**Use contractions.**
+"You'll", "it's", "don't", "can't", "we're". The book is conversational, not formal.
+
+## Openers
+
+**Get to the point in the first sentence.**
+Posts open with the fact, then explain. No throat-clearing, no scene-setting.
+
+> So, what is Git in a nutshell?
+> — *What is Git?*
+
+**Rhetorical questions are welcome — but answer them immediately.**
+
+> What happens when you create a new branch?
+> Well, doing so creates a new pointer for you to move around.
+> — *Creating a New Branch*
+
+## Tone
+
+**Plain, concrete, and direct.** Explain *why* before *how*.
+
+> This is an important section to absorb, because if you understand what Git is and
+> the fundamentals of how it works, then using Git effectively will probably be much
+> easier for you.
+> — *What is Git?*
+
+**No hype and no marketing language.**
+Never "excited to announce", "seamless", "robust", "leverage", "delve", "game-changing".
+When the book praises something, it says specifically what is good about it.
+
+**Dry, understated humor — sparingly.** At most one flourish per post, and only when
+it lands naturally.
+
+> If the book spontaneously combusts at this point, you should already be pretty
+> useful wielding Git in the time it takes you to go pick up another copy.
+> — *Introduction*
+
+**Tell the reader when something matters.**
+
+> Pay attention now — here is the main thing to remember about Git if you want the
+> rest of your learning process to go smoothly.
+> — *The Three States*
+
+## Structure
+
+**Short paragraphs, one point each.** One to four sentences is typical.
+
+**Signpost what's coming, and end with a bridge.**
+The book constantly tells you where you are going next and closes sections by pointing
+forward. Posts should end the same way: where to follow along, what happens next, or
+where to pitch in.
+
+> Let's get started.
+> — *Introduction*
+
+**Lists are for enumerable facts; numbered lists are for step sequences.**
+The book uses bullets for parallel facts (the three states) and numbers for workflows
+(the basic Git workflow). Everything else is prose.
+
+## Sentences and punctuation
+
+**Mostly short and medium declarative sentences.** Vary the rhythm; don't stack three
+long sentences in a row.
+
+**Em dashes for asides**, surrounded by spaces (the book's ` -- ` renders as an
+em dash; in MDX write ` — ` directly).
+
+> Most operations in Git need only local files and resources to operate — generally
+> no information is needed from another computer on your network.
+> — *Nearly Every Operation Is Local*
+
+**Parentheses for quick side remarks.**
+
+> …you can commit happily (to your _local_ copy, remember?) until you get to a
+> network connection to upload.
+> — *Nearly Every Operation Is Local*
+
+**No exclamation points. No emoji.**
+
+## Formatting conventions
+
+- `monospace` for commands, branch names, file names, config keys: `git branch`,
+  `main`, `AGENTS.md`.
+- _Italics_ for a new term at first use, the way the book introduces _snapshots_
+  and _blobs_. Also for book titles: _Pro Git_.
+- **Bold** sparingly, for the one key phrase in a paragraph — the book bolds
+  *stream of snapshots*, not whole sentences.
+- Headings only when a post is long enough to need them; short posts are just prose.
+
+## Source formatting
+
+**One sentence per line.**
+The book's AsciiDoc sources put each sentence on its own line (semantic line breaks),
+which keeps diffs reviewable. Do the same in post MDX; Markdown joins the lines when
+rendering.
+
+## Frontmatter
+
+- `description` is one plain sentence, in the same voice.
+- Agent-written posts must set `automated: true` (see `README.md`); this renders the
+  "written by AI" banner and is non-negotiable.

site/README.md

@@ -41,6 +41,9 @@ because Pagefind indexes the generated HTML.
 
 ## Writing a blog post
 
+**Read [`BLOG_STYLE.md`](./BLOG_STYLE.md) first** — posts are written in the book's
+voice, and that guide defines it.
+
 Add an `.mdx` file to `src/content/blog/` with this frontmatter:
 
 ```mdx
@@ -49,13 +52,20 @@ title: 'Post title'
 description: 'One-sentence summary shown in lists and search results.'
 date: 2026-08-02
 author: 'Your Name'   # optional
+automated: true       # optional; set when the post is generated by an AI agent
 ---
 
 Post body in MDX…
 ```
 
 The file name (without `.mdx`) becomes the URL: `/blog/<file-name>/`.
 
+Posts with `automated: true` get a "This post was written by AI" banner at the top
+(and a "Written by AI" tag in the post list) linking to `/authorship/`, the page
+that explains the project's authorship policy. Human-written posts get a
+"Written by a human" banner instead. **Always set `automated: true` on
+agent-generated posts.**
+
 ## Deployment
 
 `.github/workflows/deploy-site.yml` builds the site on every push to `main` and

site/package-lock.json

@@ -8,6 +8,8 @@ const blog = defineCollection({
     description: z.string(),
     date: z.coerce.date(),
     author: z.string().default('The Pro Git project'),
+    /** True when the post was generated by an AI agent rather than written by a human. */
+    automated: z.boolean().default(false),
   }),
 });
 

site/src/content.config.ts

@@ -2,25 +2,22 @@
 title: 'A new home on the web for Pro Git'
 description: 'The Pro Git project now has its own site: read the book online, search it, and follow progress on the third edition.'
 date: 2026-08-02
+automated: true
 ---
 
-The _Pro Git_ project now has a website of its own, and you are looking at it.
+The _Pro Git_ project now has a website of its own, and you're looking at it.
+Let's take a minute to walk through what's here.
 
-Here is what you will find:
+First, [the book itself](../../book/), readable online.
+Every section is rendered straight from the AsciiDoc sources in the repository, one page per section, with a sidebar table of contents and previous/next links — so you can read it front to back or jump around as you please.
 
-- **[The book, readable online](../../book/)** — the full text of _Pro Git_, rendered
-  straight from the AsciiDoc sources in the repository, one page per section with
-  a sidebar table of contents and previous/next navigation.
-- **[Full-text search](../../search/)** — every section of the book (and every post
-  on this blog) is indexed, so you can jump straight to the material you need.
-- **[This blog](../../blog/)** — updates and progress reports as work on the third
-  edition moves along.
-- **[A history of the book](../../history/)** — how _Pro Git_ went from a 2009
-  Apress title to one of the most widely read open source books in the world.
+Second, [full-text search](../../search/) over the whole book and this blog.
+If you want to know where we cover `git rebase` or the reflog, you can jump straight there instead of scanning the table of contents and hoping.
 
-The site is rebuilt automatically from the [`progit3` repository](https://github.com/progit/progit3)
-every time a change lands on `main`, so what you read here always matches the
-latest state of the manuscript.
+Third, [this blog](../../blog/), where we'll post updates and progress reports as work on the third edition moves along.
 
-If you spot a problem — in the book or on the site — [issues and pull requests
-are welcome](https://github.com/progit/progit3/blob/main/CONTRIBUTING.md).
+And finally, [a history of the book](../../history/) — how _Pro Git_ went from a 2009 Apress title to one of the most widely read (and most widely translated) open source books in the world.
+
+How does the site stay current?
+It's rebuilt automatically from the [`progit3` repository](https://github.com/progit/progit3) every time a change lands on `main`, so what you read here always matches the latest state of the manuscript.
+If you spot a problem — in the book or on the site — [issues and pull requests are welcome](https://github.com/progit/progit3/blob/main/CONTRIBUTING.md).

site/src/content/blog/a-new-home-for-pro-git.mdx

@@ -1,40 +1,27 @@
 ---
 title: 'Planning the third edition'
-description: 'Git 3.0 is coming, and Pro Git is getting its first full revision since 2014. Here is what is changing and why.'
+description: "Git 3.0 is coming, and Pro Git is getting its first full revision since 2014. Here's what's changing and why."
 date: 2026-08-02
+automated: true
 ---
 
-Work has started on the third edition of _Pro Git_ — the first full revision of
-the book since the second edition shipped in 2014.
+Work has started on the third edition of _Pro Git_ — the first full revision of the book since the second edition shipped in 2014.
+Let's take a minute to explain why now, and what's going to change.
 
-The trigger is **Git 3.0**. After more than a decade of careful backward
-compatibility, Git's maintainers have queued up a set of genuine breaking
-changes, and several of them cut straight through material the book teaches
-today:
+So, why a third edition?
+The short answer is **Git 3.0**.
+After more than a decade of careful backward compatibility, Git's maintainers have queued up a set of genuine breaking changes, and several of them cut straight through material the book teaches today:
 
-- **`main` becomes the real default branch name.** The book currently teaches
-  `master` first and treats `main` as an opt-in override. That flips: the
-  inventory counts roughly **600 renames** across the text, plus the diagrams
-  and screenshots that show branch names.
-- **SHA-256 becomes the default object hash** for new repositories. The famous
-  "40-character SHA-1 string" passage — and every example hash in the book —
-  needs a rethink.
-- **`reftable` replaces the `files` backend** as the default ref storage, which
-  reshapes parts of the Git Internals chapter.
-- **Rust becomes a mandatory build dependency**, so "installing from source"
-  gets a new prerequisite.
-- **New security defaults** like `safe.bareRepository` and `safe.directory`
-  aren't covered by the current text at all.
+- **`main` becomes the real default branch name.** The book currently teaches `master` first and treats `main` as an opt-in override. That flips — and the inventory counts roughly 600 renames across the text, plus the diagrams and screenshots that show branch names.
+- **SHA-256 becomes the default object hash** for new repositories. You may remember the "40-character SHA-1 string" from the book; that passage — and every example hash in the book — needs a rethink.
+- **`reftable` replaces the `files` backend** as the default ref storage, which reshapes parts of the Git Internals chapter.
+- **Rust becomes a mandatory build dependency**, so "installing from source" gets a new prerequisite.
+- **New security defaults** like `safe.bareRepository` and `safe.directory` aren't covered by the current text at all.
 
-Beyond the 3.0-specific work there is a decade of general staleness to clear
-out: version framing ("this book was written using Git version 2"), long-stable
-features still described as new, and forge screenshots from another era.
+Beyond the 3.0 work, there's a decade of general staleness to clear out: the book still tells you it was written using Git version 2, describes long-stable features as new, and shows forge screenshots from another era.
 
-The full chapter-by-chapter inventory lives in
-[`REVISION_PLAN.md`](https://github.com/progit/progit3/blob/main/REVISION_PLAN.md)
-in the repository, with the `master` → `main` breakdown in
-[`book_master_to_main_inventory.md`](https://github.com/progit/progit3/blob/main/book_master_to_main_inventory.md).
+If you want the details, the full chapter-by-chapter inventory lives in [`REVISION_PLAN.md`](https://github.com/progit/progit3/blob/main/REVISION_PLAN.md) in the repository, with the `master` → `main` breakdown in [`book_master_to_main_inventory.md`](https://github.com/progit/progit3/blob/main/book_master_to_main_inventory.md).
 
-Progress will be posted here as chapters get revised. As always, the book is
-being written in the open — follow along or pitch in at
-[github.com/progit/progit3](https://github.com/progit/progit3).
+We'll post progress here as chapters get revised.
+As always, the book is being written in the open — follow along or pitch in at [github.com/progit/progit3](https://github.com/progit/progit3).
+Let's get started.

site/src/content/blog/planning-the-third-edition.mdx

@@ -0,0 +1,58 @@
+---
+import Base from '../layouts/Base.astro';
+import { url } from '../lib/url';
+---
+
+<Base
+  title="Humans, AI, and this project · Pro Git"
+  description="The Pro Git book is written entirely by humans. Some blog posts are automated to communicate project updates — and they are always labeled."
+>
+  <main class="container narrow" data-pagefind-body data-pagefind-meta="title:Humans, AI, and this project">
+    <h1 class="page-title">Humans, AI, and this project</h1>
+    <p class="page-lede">Who writes what around here — and how you can always tell.</p>
+
+    <div class="prose">
+      <h2>The book is written entirely by humans</h2>
+      <p>
+        Every sentence of <em>Pro Git</em> — the chapters, sections, sidebars, and captions —
+        is written by its human authors. That is a firm rule of this project, not a
+        preference: the book has named authors and a voice, and the writing is the work.
+        AI agents never compose, rewrite, paraphrase, or "polish" the book's prose.
+      </p>
+      <p>
+        Agents do help with the mechanical work around the book: search-and-replace fixes
+        (like renaming <code>master</code> to <code>main</code> in examples), generating and
+        wiring up figures, building tooling, research, and planning. The full policy lives in
+        <a href="https://github.com/progit/progit3/blob/main/AGENTS.md" rel="noopener"><code>AGENTS.md</code></a>
+        in the repository.
+      </p>
+
+      <h2>Some blog posts are automated</h2>
+      <p>
+        The blog is different. Some posts there exist to communicate project updates —
+        progress reports, site changes, revision milestones — and those are generated by
+        automated agents working on the project.
+      </p>
+      <p>
+        When a post was written by AI, we make that clear: it carries a
+        <strong>"This post was written by AI"</strong> banner at the top of the post and a
+        <strong>"Written by AI"</strong> tag in the post list. Posts written by a human say so
+        too. There is no ambiguity, and no unlabeled machine writing anywhere on this site.
+      </p>
+
+      <h2>In short</h2>
+      <ul>
+        <li><strong>The book:</strong> humans, always.</li>
+        <li><strong>The blog:</strong> humans or AI — always labeled at the top of the post.</li>
+      </ul>
+    </div>
+
+    <p class="back"><a href={url('/blog/')}>← Back to the blog</a></p>
+  </main>
+</Base>
+
+<style>
+  .back {
+    margin: 3rem 0;
+  }
+</style>