fix: allow README.md explainer to be a full section (#2128)

## PR Checklist

- [x] Addresses an existing open issue: fixes #2127
- [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

Moves the `explainer` option into `documentation.readme` so it sits
alongside `additional`.

🎁

Author: JoshuaKGoldberg

docs/Configuration Files.md

@@ -24,7 +24,6 @@ These options are generally only programmatically used internally, but can still
 | `contributors`      | AllContributors contributors to store in `.all-contributorsrc`           | Existing contributors in the file, or just your username  |
 | `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"`     |

src/base.test.ts

@@ -24,6 +24,10 @@ describe("base", () => {
 				development: expect.any(String),
 				readme: {
 					additional: expect.any(String),
+					explainer: [
+						`\`create-typescript-app\` is a one-stop-shop solution to set up a new or existing repository with the latest and greatest TypeScript tooling.`,
+						`It includes options not just for building and testing but also automated release management, contributor recognition, GitHub repository settings, and more.`,
+					].join("\n"),
 					usage: expect.any(String),
 				},
 			},
@@ -33,10 +37,6 @@ describe("base", () => {
 			},
 			emoji: "🎁",
 			existingLabels: expect.any(Array),
-			explainer: [
-				`\`create-typescript-app\` is a one-stop-shop solution to set up a new or existing repository with the latest and greatest TypeScript tooling.`,
-				`It includes options not just for building and testing but also automated release management, contributor recognition, GitHub repository settings, and more.`,
-			],
 			funding: "JoshuaKGoldberg",
 			guide: {
 				href: "https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository",

src/base.ts

@@ -17,7 +17,6 @@ import { readEmailFromNpm } from "./options/readEmailFromNpm.js";
 import { readEmails } from "./options/readEmails.js";
 import { readEmoji } from "./options/readEmoji.js";
 import { readExistingLabels } from "./options/readExistingLabels.js";
-import { readExplainer } from "./options/readExplainer.js";
 import { readFileSafe } from "./options/readFileSafe.js";
 import { readFunding } from "./options/readFunding.js";
 import { readGitDefaults } from "./options/readGitDefaults.js";
@@ -31,6 +30,7 @@ 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 { readReadmeExplainer } from "./options/readReadmeExplainer.js";
 import { readReadmeUsage } from "./options/readReadmeUsage.js";
 import { readRepository } from "./options/readRepository.js";
 import { readRulesetId } from "./options/readRulesetId.js";
@@ -94,10 +94,6 @@ export const base = createBase({
 			)
 			.optional()
 			.describe("existing labels from the GitHub repository"),
-		explainer: z
-			.array(z.string())
-			.optional()
-			.describe("additional README.md sentence(s) describing the package"),
 		funding: z
 			.string()
 			.optional()
@@ -200,6 +196,7 @@ export const base = createBase({
 				await readDocumentation(
 					getDevelopmentDocumentation,
 					getReadmeAdditional,
+					getReadmeExplainer,
 					getReadmeUsage,
 				),
 		);
@@ -232,8 +229,6 @@ export const base = createBase({
 			async () => await readExistingLabels(take, getOwner, getRepository),
 		);
 
-		const getExplainer = lazyValue(async () => await readExplainer(getReadme));
-
 		const getFunding = lazyValue(async () => await readFunding(take));
 
 		const getGitDefaults = lazyValue(async () => await readGitDefaults(take));
@@ -282,6 +277,10 @@ export const base = createBase({
 			async () => await readReadmeAdditional(getReadme),
 		);
 
+		const getReadmeExplainer = lazyValue(
+			async () => await readReadmeExplainer(getReadme),
+		);
+
 		const getReadmeUsage = lazyValue(
 			async () => await readReadmeUsage(getEmoji, getReadme, getRepository),
 		);
@@ -318,7 +317,6 @@ export const base = createBase({
 			email: getEmail,
 			emoji: getEmoji,
 			existingLabels: getExistingLabels,
-			explainer: getExplainer,
 			funding: getFunding,
 			guide: getGuide,
 			keywords: getKeywords,

src/blocks/blockREADME.test.ts

@@ -121,7 +121,13 @@ describe("blockREADME", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
 				...optionsBase,
-				explainer: ["And a one.", "And a two."],
+				documentation: {
+					...optionsBase.documentation,
+					readme: {
+						...optionsBase.documentation.readme,
+						explainer: "\nAnd a one.\nAnd a two.\n",
+					},
+				},
 			},
 		});
 
@@ -136,9 +142,11 @@ describe("blockREADME", () => {
 				<img alt="💪 TypeScript: Strict" src="https://img.shields.io/badge/%F0%9F%92%AA_typescript-strict-21bb42.svg" />
 			</p>
 
+
 			And a one.
 			And a two.
 
+
 			## Usage
 
 			Test usage.
@@ -238,7 +246,13 @@ describe("blockREADME", () => {
 		const creation = testBlock(blockREADME, {
 			options: {
 				...optionsBase,
-				explainer: ["And a one.", "And a two."],
+				documentation: {
+					...optionsBase.documentation,
+					readme: {
+						...optionsBase.documentation.readme,
+						explainer: "And a one.\nAnd a two.",
+					},
+				},
 				logo: {
 					alt: "My logo",
 					height: 100,

src/blocks/blockREADME.ts

@@ -36,7 +36,8 @@ export const blockREADME = base.createBlock({
 		const { badges, notices, sections } = addons;
 
 		const explainer =
-			options.explainer && `\n${options.explainer.join("\n")}\n`;
+			options.documentation.readme.explainer &&
+			`\n${options.documentation.readme.explainer}\n`;
 
 		const logo =
 			options.logo &&

src/options/readDocumentation.ts

@@ -3,10 +3,12 @@ import { Documentation } from "../schemas.js";
 export async function readDocumentation(
 	getDevelopmentDocumentation: () => Promise<string | undefined>,
 	getReadmeAdditional: () => Promise<string | undefined>,
+	getReadmeExplainer: () => Promise<string | undefined>,
 	getReadmeUsage: () => Promise<string>,
 ): Promise<Documentation> {
-	const [additional, development, usage] = await Promise.all([
+	const [additional, explainer, development, usage] = await Promise.all([
 		getReadmeAdditional(),
+		getReadmeExplainer(),
 		getDevelopmentDocumentation(),
 		getReadmeUsage(),
 	]);
@@ -15,6 +17,7 @@ export async function readDocumentation(
 		development,
 		readme: {
 			additional,
+			explainer,
 			usage,
 		},
 	};