fix: preserve additional README.md content in transition (#2090)

## PR Checklist

- [x] Addresses an existing open issue: fixes #2088
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

Switches from two string docs options -`documentation` and `usage` to an
object with:

* `development`
* `readme`:
  * `additional`
  * `usage`

`readme.additional` is a new field that takes in content from
`README.md` after a contributors table, if it exists.

🎁

Author: JoshuaKGoldberg

docs/Configuration Files.md

@@ -22,15 +22,14 @@ These options are generally only programmatically used internally, but can still
 | Option              | Description                                                              | Default (If Available)                                    |
 | ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
 | `contributors`      | AllContributors contributors to store in `.all-contributorsrc`           | Existing contributors in the file, or just your username  |
-| `documentation`     | any additional docs to add to `.github/DEVELOPMENT.md`                   | Extra content in `.github/DEVELOPMENT.md`                 |
+| `documentation`     | additional docs to add to `.github/DEVELOPMENT.md` and/or `README.md`    | Extra content in those two files                          |
 | `existingLabels`    | existing labels to switch to the standard template labels                | Existing labels on the repository from the GitHub API     |
 | `explainer`         | additional `README.md` sentence(s) describing the package                | Extra content in `README.md` after badges and description |
 | `guide`             | link to a contribution guide to place at the top of development docs     | Block quote on top of `.github/DEVELOPMENT.md`            |
 | `logo`              | local image file and alt text to display near the top of the `README.md` | First non-badge image's `alt` and `src` in `README.md`    |
 | `node`              | Node.js engine version(s) to pin and require a minimum of                | Values from `.nvmrc` and `package.json`'s `"engines"`     |
 | `packageData`       | additional properties to include in `package.json`                       | Existing values in `package.json`                         |
 | `rulesetId`         | GitHub branch ruleset ID for main branch protections                     | Existing ruleset on the `main` branch from the GitHub API |
-| `usage`             | Markdown docs to put in `README.md` under the `## Usage` heading         | Existing usage lines in `README.md`                       |
 | `workflowsVersions` | existing versions of GitHub Actions workflows used                       | Existing action versions in `.github/workflows/*.yml`     |
 
 For example, changing `node` versions to values different from what would be inferred:

src/base.test.ts

@@ -20,7 +20,13 @@ describe("base", () => {
 			).contributors,
 			description:
 				"Quickstart-friendly TypeScript template with comprehensive, configurable, opinionated tooling. 🎁",
-			documentation: "",
+			documentation: {
+				development: expect.any(String),
+				readme: {
+					additional: expect.any(String),
+					usage: expect.any(String),
+				},
+			},
 			email: {
 				github: "[email protected]",
 				npm: "[email protected]",
@@ -51,7 +57,6 @@ describe("base", () => {
 			pnpm: expect.any(String),
 			repository: "create-typescript-app",
 			title: "Create TypeScript App",
-			usage: expect.any(String),
 			version: expect.any(String),
 			// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-require-imports
 			words: require("../cspell.json").words,

src/base.ts

@@ -9,6 +9,7 @@ import { readAllContributors } from "./options/readAllContributors.js";
 import { readAuthor } from "./options/readAuthor.js";
 import { readBin } from "./options/readBin.js";
 import { readDescription } from "./options/readDescription.js";
+import { readDevelopmentDocumentation } from "./options/readDevelopmentDocumentation.js";
 import { readDocumentation } from "./options/readDocumentation.js";
 import { readEmailFromCodeOfConduct } from "./options/readEmailFromCodeOfConduct.js";
 import { readEmailFromGit } from "./options/readEmailFromGit.js";
@@ -28,13 +29,14 @@ import { readOwner } from "./options/readOwner.js";
 import { readPackageAuthor } from "./options/readPackageAuthor.js";
 import { readPackageData } from "./options/readPackageData.js";
 import { readPnpm } from "./options/readPnpm.js";
+import { readReadmeAdditional } from "./options/readReadmeAdditional.js";
+import { readReadmeUsage } from "./options/readReadmeUsage.js";
 import { readRepository } from "./options/readRepository.js";
 import { readRulesetId } from "./options/readRulesetId.js";
 import { readTitle } from "./options/readTitle.js";
-import { readUsage } from "./options/readUsage.js";
 import { readWords } from "./options/readWords.js";
 import { readWorkflowsVersions } from "./options/readWorkflowsVersions.js";
-import { zContributor, zWorkflowsVersions } from "./schemas.js";
+import { zContributor, zDocumentation, zWorkflowsVersions } from "./schemas.js";
 
 export const base = createBase({
 	options: {
@@ -58,10 +60,9 @@ export const base = createBase({
 			.default("A very lovely package. Hooray!")
 			.describe("'Sentence case.' description of the repository"),
 		directory: z.string().describe("Directory to create the repository in"),
-		documentation: z
-			.string()
-			.optional()
-			.describe("any additional docs to add to .github/DEVELOPMENT.md"),
+		documentation: zDocumentation.describe(
+			"additional docs to add to .md files",
+		),
 		email: z
 			.union([
 				z.string(),
@@ -154,10 +155,6 @@ export const base = createBase({
 			.optional()
 			.describe("GitHub branch ruleset ID for main branch protections"),
 		title: z.string().describe("'Title Case' title for the repository"),
-		usage: z
-			.string()
-			.optional()
-			.describe("Markdown docs to put in README.md under the ## Usage heading"),
 		version: z
 			.string()
 			.optional()
@@ -190,8 +187,17 @@ export const base = createBase({
 			async () => await readDescription(getPackageData, getReadme),
 		);
 
+		const getDevelopmentDocumentation = lazyValue(
+			async () => await readDevelopmentDocumentation(take),
+		);
+
 		const getDocumentation = lazyValue(
-			async () => await readDocumentation(take),
+			async () =>
+				await readDocumentation(
+					getDevelopmentDocumentation,
+					getReadmeAdditional,
+					getReadmeUsage,
+				),
 		);
 
 		const getEmail = lazyValue(
@@ -263,6 +269,14 @@ export const base = createBase({
 			async () => await readFileSafe("README.md", ""),
 		);
 
+		const getReadmeAdditional = lazyValue(
+			async () => await readReadmeAdditional(getReadme),
+		);
+
+		const getReadmeUsage = lazyValue(
+			async () => await readReadmeUsage(getEmoji, getReadme, getRepository),
+		);
+
 		const getRepository = lazyValue(
 			async () => await readRepository(getGitDefaults, getPackageData, options),
 		);
@@ -275,10 +289,6 @@ export const base = createBase({
 			async () => await readTitle(getReadme, getRepository),
 		);
 
-		const getUsage = lazyValue(
-			async () => await readUsage(getEmoji, getReadme, getRepository),
-		);
-
 		const getVersion = lazyValue(async () => (await getPackageData()).version);
 
 		const getWords = lazyValue(async () => await readWords(take));
@@ -308,7 +318,6 @@ export const base = createBase({
 			repository: getRepository,
 			rulesetId: getRulesetId,
 			title: getTitle,
-			usage: getUsage,
 			version: getVersion,
 			words: getWords,
 			workflowsVersions: getWorkflowData,

src/blocks/blockCSpell.test.ts

@@ -280,7 +280,7 @@ describe("blockCSpell", () => {
 			  "scripts": [
 			    {
 			      "commands": [
-			        "node path/to/cspell-populate-words/bin/index.mjs --words "access" --words "public" --words "description" --words "Test description" --words "directory" --words "." --words "email" --words "github" --words "[email protected]" --words "npm" --words "[email protected]" --words "emoji" --words "💖" --words "owner" --words "test-owner" --words "preset" --words "minimal" --words "repository" --words "test-repository" --words "title" --words "Test Title"",
+			        "node path/to/cspell-populate-words/bin/index.mjs --words "access" --words "public" --words "description" --words "Test description" --words "directory" --words "." --words "documentation" --words "readme" --words "usage" --words "Test usage." --words "email" --words "github" --words "[email protected]" --words "npm" --words "[email protected]" --words "emoji" --words "💖" --words "owner" --words "test-owner" --words "preset" --words "minimal" --words "repository" --words "test-repository" --words "title" --words "Test Title"",
 			      ],
 			      "phase": 3,
 			    },

src/blocks/blockDevelopmentDocs.test.ts

@@ -149,7 +149,10 @@ describe("blockDevelopmentDocs", () => {
 		const creation = testBlock(blockDevelopmentDocs, {
 			options: {
 				...optionsBase,
-				documentation: "More documentation.",
+				documentation: {
+					...optionsBase.documentation,
+					development: "More documentation.",
+				},
 			},
 		});
 

src/blocks/blockDevelopmentDocs.ts

@@ -87,7 +87,9 @@ export const blockDevelopmentDocs = base.createBlock({
 			...Object.entries(addons.sections)
 				.sort(([a], [b]) => a.localeCompare(b))
 				.flatMap(([heading, section]) => printSection(heading, section)),
-			...(options.documentation ? [options.documentation] : []),
+			...(options.documentation.development
+				? [options.documentation.development]
+				: []),
 		];
 
 		return {

src/blocks/blockREADME.test.ts

@@ -4,16 +4,11 @@ import { describe, expect, test } from "vitest";
 import { blockREADME } from "./blockREADME.js";
 import { optionsBase } from "./options.fakes.js";
 
-const options = {
-	...optionsBase,
-	usage: "Use it.",
-};
-
 describe("blockREADME", () => {
 	test("description with one sentence", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
-				...options,
+				...optionsBase,
 				description: "One sentence.",
 			},
 		});
@@ -31,7 +26,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 
@@ -47,7 +42,7 @@ describe("blockREADME", () => {
 	test("description with two sentences", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
-				...options,
+				...optionsBase,
 				description: "First sentence. Second sentence.",
 			},
 		});
@@ -68,13 +63,54 @@ describe("blockREADME", () => {
 
 			## Usage
 
+			Test usage.
+
+			## Development
+
+			See [\`.github/CONTRIBUTING.md\`](./.github/CONTRIBUTING.md), then [\`.github/DEVELOPMENT.md\`](./.github/DEVELOPMENT.md).
+			Thanks! 💖
+
+			",
+			  },
+			}
+		`);
+	});
+
+	test("options.documentation", () => {
+		const creation = testBlock(blockREADME, {
+			options: {
+				...optionsBase,
+				documentation: {
+					development: "Development docs.",
+					readme: {
+						additional: "Additional docs.",
+						usage: "Use it.",
+					},
+				},
+			},
+		});
+
+		expect(creation).toMatchInlineSnapshot(`
+			{
+			  "files": {
+			    "README.md": "<h1 align="center">Test Title</h1>
+
+			<p align="center">Test description</p>
+
+			<p align="center">
+				<img alt="💪 TypeScript: Strict" src="https://img.shields.io/badge/%F0%9F%92%AA_typescript-strict-21bb42.svg" />
+			</p>
+
+			## Usage
+
 			Use it.
 
 			## Development
 
 			See [\`.github/CONTRIBUTING.md\`](./.github/CONTRIBUTING.md), then [\`.github/DEVELOPMENT.md\`](./.github/DEVELOPMENT.md).
 			Thanks! 💖
 
+			Additional docs.
 			",
 			  },
 			}
@@ -84,7 +120,7 @@ describe("blockREADME", () => {
 	test("options.explainer", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
-				...options,
+				...optionsBase,
 				explainer: ["And a one.", "And a two."],
 			},
 		});
@@ -105,7 +141,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 
@@ -121,7 +157,7 @@ describe("blockREADME", () => {
 	test("options.logo without sizing", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
-				...options,
+				...optionsBase,
 				logo: {
 					alt: "My logo",
 					src: "img.jpg",
@@ -144,7 +180,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 
@@ -160,7 +196,7 @@ describe("blockREADME", () => {
 	test("options.logo with sizing", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
-				...options,
+				...optionsBase,
 				logo: {
 					alt: "My logo",
 					height: 100,
@@ -185,7 +221,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 
@@ -201,7 +237,7 @@ describe("blockREADME", () => {
 	test("options.explainer and options.logo", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
-				...options,
+				...optionsBase,
 				explainer: ["And a one.", "And a two."],
 				logo: {
 					alt: "My logo",
@@ -230,7 +266,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 
@@ -244,9 +280,7 @@ describe("blockREADME", () => {
 	});
 
 	test("without addons", () => {
-		const creation = testBlock(blockREADME, {
-			options,
-		});
+		const creation = testBlock(blockREADME, { options: optionsBase });
 
 		expect(creation).toMatchInlineSnapshot(`
 			{
@@ -261,7 +295,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 
@@ -295,7 +329,7 @@ describe("blockREADME", () => {
 				notices: ["> Hello, world! 💖"],
 				sections: [`## Other\n\nHello!`],
 			},
-			options,
+			options: optionsBase,
 		});
 
 		expect(creation).toMatchInlineSnapshot(`
@@ -314,7 +348,7 @@ describe("blockREADME", () => {
 
 			## Usage
 
-			Use it.
+			Test usage.
 
 			## Development
 

src/blocks/blockREADME.ts

@@ -54,13 +54,16 @@ ${formatBadges(badges)}
 ${[logo, explainer].filter(Boolean).join("")}
 ## Usage
 
-${options.usage}
+${options.documentation.readme.usage}
 
 ## Development
 
 See [\`.github/CONTRIBUTING.md\`](./.github/CONTRIBUTING.md), then [\`.github/DEVELOPMENT.md\`](./.github/DEVELOPMENT.md).
 Thanks! ${options.emoji}
-${sections.map((section) => `\n${section}`).join("")}
+${[...sections, options.documentation.readme.additional]
+	.filter(Boolean)
+	.map((section) => `\n${section}`)
+	.join("")}
 ${notices.length ? `\n${notices.map((notice) => notice.trim()).join("\n\n")}` : ""}`,
 			},
 		};