Skip to content

Commit 2c41380

Browse files
JoshuaKGoldbergJoshuaKGoldberg
authored
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. 🎁
1 parent 5bbf8be commit 2c41380

17 files changed

+283
-90
lines changed

‎docs/Configuration Files.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,14 @@ These options are generally only programmatically used internally, but can still
2222
| Option | Description | Default (If Available) |
2323
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
2424
| `contributors` | AllContributors contributors to store in `.all-contributorsrc` | Existing contributors in the file, or just your username |
25-
| `documentation` | any additional docs to add to `.github/DEVELOPMENT.md` | Extra content in `.github/DEVELOPMENT.md` |
25+
| `documentation` | additional docs to add to `.github/DEVELOPMENT.md` and/or `README.md` | Extra content in those two files |
2626
| `existingLabels` | existing labels to switch to the standard template labels | Existing labels on the repository from the GitHub API |
2727
| `explainer` | additional `README.md` sentence(s) describing the package | Extra content in `README.md` after badges and description |
2828
| `guide` | link to a contribution guide to place at the top of development docs | Block quote on top of `.github/DEVELOPMENT.md` |
2929
| `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` |
3030
| `node` | Node.js engine version(s) to pin and require a minimum of | Values from `.nvmrc` and `package.json`'s `"engines"` |
3131
| `packageData` | additional properties to include in `package.json` | Existing values in `package.json` |
3232
| `rulesetId` | GitHub branch ruleset ID for main branch protections | Existing ruleset on the `main` branch from the GitHub API |
33-
| `usage` | Markdown docs to put in `README.md` under the `## Usage` heading | Existing usage lines in `README.md` |
3433
| `workflowsVersions` | existing versions of GitHub Actions workflows used | Existing action versions in `.github/workflows/*.yml` |
3534

3635
For example, changing `node` versions to values different from what would be inferred:

‎src/base.test.ts

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,13 @@ describe("base", () => {
2020
).contributors,
2121
description:
2222
"Quickstart-friendly TypeScript template with comprehensive, configurable, opinionated tooling. 🎁",
23-
documentation: "",
23+
documentation: {
24+
development: expect.any(String),
25+
readme: {
26+
additional: expect.any(String),
27+
usage: expect.any(String),
28+
},
29+
},
2430
email: {
2531
github: "[email protected]",
2632
npm: "[email protected]",
@@ -51,7 +57,6 @@ describe("base", () => {
5157
pnpm: expect.any(String),
5258
repository: "create-typescript-app",
5359
title: "Create TypeScript App",
54-
usage: expect.any(String),
5560
version: expect.any(String),
5661
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-require-imports
5762
words: require("../cspell.json").words,

‎src/base.ts

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import { readAllContributors } from "./options/readAllContributors.js";
99
import { readAuthor } from "./options/readAuthor.js";
1010
import { readBin } from "./options/readBin.js";
1111
import { readDescription } from "./options/readDescription.js";
12+
import { readDevelopmentDocumentation } from "./options/readDevelopmentDocumentation.js";
1213
import { readDocumentation } from "./options/readDocumentation.js";
1314
import { readEmailFromCodeOfConduct } from "./options/readEmailFromCodeOfConduct.js";
1415
import { readEmailFromGit } from "./options/readEmailFromGit.js";
@@ -28,13 +29,14 @@ import { readOwner } from "./options/readOwner.js";
2829
import { readPackageAuthor } from "./options/readPackageAuthor.js";
2930
import { readPackageData } from "./options/readPackageData.js";
3031
import { readPnpm } from "./options/readPnpm.js";
32+
import { readReadmeAdditional } from "./options/readReadmeAdditional.js";
33+
import { readReadmeUsage } from "./options/readReadmeUsage.js";
3134
import { readRepository } from "./options/readRepository.js";
3235
import { readRulesetId } from "./options/readRulesetId.js";
3336
import { readTitle } from "./options/readTitle.js";
34-
import { readUsage } from "./options/readUsage.js";
3537
import { readWords } from "./options/readWords.js";
3638
import { readWorkflowsVersions } from "./options/readWorkflowsVersions.js";
37-
import { zContributor, zWorkflowsVersions } from "./schemas.js";
39+
import { zContributor, zDocumentation, zWorkflowsVersions } from "./schemas.js";
3840

3941
export const base = createBase({
4042
options: {
@@ -58,10 +60,9 @@ export const base = createBase({
5860
.default("A very lovely package. Hooray!")
5961
.describe("'Sentence case.' description of the repository"),
6062
directory: z.string().describe("Directory to create the repository in"),
61-
documentation: z
62-
.string()
63-
.optional()
64-
.describe("any additional docs to add to .github/DEVELOPMENT.md"),
63+
documentation: zDocumentation.describe(
64+
"additional docs to add to .md files",
65+
),
6566
email: z
6667
.union([
6768
z.string(),
@@ -154,10 +155,6 @@ export const base = createBase({
154155
.optional()
155156
.describe("GitHub branch ruleset ID for main branch protections"),
156157
title: z.string().describe("'Title Case' title for the repository"),
157-
usage: z
158-
.string()
159-
.optional()
160-
.describe("Markdown docs to put in README.md under the ## Usage heading"),
161158
version: z
162159
.string()
163160
.optional()
@@ -190,8 +187,17 @@ export const base = createBase({
190187
async () => await readDescription(getPackageData, getReadme),
191188
);
192189

190+
const getDevelopmentDocumentation = lazyValue(
191+
async () => await readDevelopmentDocumentation(take),
192+
);
193+
193194
const getDocumentation = lazyValue(
194-
async () => await readDocumentation(take),
195+
async () =>
196+
await readDocumentation(
197+
getDevelopmentDocumentation,
198+
getReadmeAdditional,
199+
getReadmeUsage,
200+
),
195201
);
196202

197203
const getEmail = lazyValue(
@@ -263,6 +269,14 @@ export const base = createBase({
263269
async () => await readFileSafe("README.md", ""),
264270
);
265271

272+
const getReadmeAdditional = lazyValue(
273+
async () => await readReadmeAdditional(getReadme),
274+
);
275+
276+
const getReadmeUsage = lazyValue(
277+
async () => await readReadmeUsage(getEmoji, getReadme, getRepository),
278+
);
279+
266280
const getRepository = lazyValue(
267281
async () => await readRepository(getGitDefaults, getPackageData, options),
268282
);
@@ -275,10 +289,6 @@ export const base = createBase({
275289
async () => await readTitle(getReadme, getRepository),
276290
);
277291

278-
const getUsage = lazyValue(
279-
async () => await readUsage(getEmoji, getReadme, getRepository),
280-
);
281-
282292
const getVersion = lazyValue(async () => (await getPackageData()).version);
283293

284294
const getWords = lazyValue(async () => await readWords(take));
@@ -308,7 +318,6 @@ export const base = createBase({
308318
repository: getRepository,
309319
rulesetId: getRulesetId,
310320
title: getTitle,
311-
usage: getUsage,
312321
version: getVersion,
313322
words: getWords,
314323
workflowsVersions: getWorkflowData,

‎src/blocks/blockCSpell.test.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,7 @@ describe("blockCSpell", () => {
280280
"scripts": [
281281
{
282282
"commands": [
283-
"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"",
283+
"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"",
284284
],
285285
"phase": 3,
286286
},

‎src/blocks/blockDevelopmentDocs.test.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,10 @@ describe("blockDevelopmentDocs", () => {
149149
const creation = testBlock(blockDevelopmentDocs, {
150150
options: {
151151
...optionsBase,
152-
documentation: "More documentation.",
152+
documentation: {
153+
...optionsBase.documentation,
154+
development: "More documentation.",
155+
},
153156
},
154157
});
155158

‎src/blocks/blockDevelopmentDocs.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,9 @@ export const blockDevelopmentDocs = base.createBlock({
8787
...Object.entries(addons.sections)
8888
.sort(([a], [b]) => a.localeCompare(b))
8989
.flatMap(([heading, section]) => printSection(heading, section)),
90-
...(options.documentation ? [options.documentation] : []),
90+
...(options.documentation.development
91+
? [options.documentation.development]
92+
: []),
9193
];
9294

9395
return {

‎src/blocks/blockREADME.test.ts

Lines changed: 56 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,11 @@ import { describe, expect, test } from "vitest";
44
import { blockREADME } from "./blockREADME.js";
55
import { optionsBase } from "./options.fakes.js";
66

7-
const options = {
8-
...optionsBase,
9-
usage: "Use it.",
10-
};
11-
127
describe("blockREADME", () => {
138
test("description with one sentence", () => {
149
const creation = testBlock(blockREADME, {
1510
options: {
16-
...options,
11+
...optionsBase,
1712
description: "One sentence.",
1813
},
1914
});
@@ -31,7 +26,7 @@ describe("blockREADME", () => {
3126
3227
## Usage
3328
34-
Use it.
29+
Test usage.
3530
3631
## Development
3732
@@ -47,7 +42,7 @@ describe("blockREADME", () => {
4742
test("description with two sentences", () => {
4843
const creation = testBlock(blockREADME, {
4944
options: {
50-
...options,
45+
...optionsBase,
5146
description: "First sentence. Second sentence.",
5247
},
5348
});
@@ -68,13 +63,54 @@ describe("blockREADME", () => {
6863
6964
## Usage
7065
66+
Test usage.
67+
68+
## Development
69+
70+
See [\`.github/CONTRIBUTING.md\`](./.github/CONTRIBUTING.md), then [\`.github/DEVELOPMENT.md\`](./.github/DEVELOPMENT.md).
71+
Thanks! 💖
72+
73+
",
74+
},
75+
}
76+
`);
77+
});
78+
79+
test("options.documentation", () => {
80+
const creation = testBlock(blockREADME, {
81+
options: {
82+
...optionsBase,
83+
documentation: {
84+
development: "Development docs.",
85+
readme: {
86+
additional: "Additional docs.",
87+
usage: "Use it.",
88+
},
89+
},
90+
},
91+
});
92+
93+
expect(creation).toMatchInlineSnapshot(`
94+
{
95+
"files": {
96+
"README.md": "<h1 align="center">Test Title</h1>
97+
98+
<p align="center">Test description</p>
99+
100+
<p align="center">
101+
<img alt="💪 TypeScript: Strict" src="https://img.shields.io/badge/%F0%9F%92%AA_typescript-strict-21bb42.svg" />
102+
</p>
103+
104+
## Usage
105+
71106
Use it.
72107
73108
## Development
74109
75110
See [\`.github/CONTRIBUTING.md\`](./.github/CONTRIBUTING.md), then [\`.github/DEVELOPMENT.md\`](./.github/DEVELOPMENT.md).
76111
Thanks! 💖
77112
113+
Additional docs.
78114
",
79115
},
80116
}
@@ -84,7 +120,7 @@ describe("blockREADME", () => {
84120
test("options.explainer", () => {
85121
const creation = testBlock(blockREADME, {
86122
options: {
87-
...options,
123+
...optionsBase,
88124
explainer: ["And a one.", "And a two."],
89125
},
90126
});
@@ -105,7 +141,7 @@ describe("blockREADME", () => {
105141
106142
## Usage
107143
108-
Use it.
144+
Test usage.
109145
110146
## Development
111147
@@ -121,7 +157,7 @@ describe("blockREADME", () => {
121157
test("options.logo without sizing", () => {
122158
const creation = testBlock(blockREADME, {
123159
options: {
124-
...options,
160+
...optionsBase,
125161
logo: {
126162
alt: "My logo",
127163
src: "img.jpg",
@@ -144,7 +180,7 @@ describe("blockREADME", () => {
144180
145181
## Usage
146182
147-
Use it.
183+
Test usage.
148184
149185
## Development
150186
@@ -160,7 +196,7 @@ describe("blockREADME", () => {
160196
test("options.logo with sizing", () => {
161197
const creation = testBlock(blockREADME, {
162198
options: {
163-
...options,
199+
...optionsBase,
164200
logo: {
165201
alt: "My logo",
166202
height: 100,
@@ -185,7 +221,7 @@ describe("blockREADME", () => {
185221
186222
## Usage
187223
188-
Use it.
224+
Test usage.
189225
190226
## Development
191227
@@ -201,7 +237,7 @@ describe("blockREADME", () => {
201237
test("options.explainer and options.logo", () => {
202238
const creation = testBlock(blockREADME, {
203239
options: {
204-
...options,
240+
...optionsBase,
205241
explainer: ["And a one.", "And a two."],
206242
logo: {
207243
alt: "My logo",
@@ -230,7 +266,7 @@ describe("blockREADME", () => {
230266
231267
## Usage
232268
233-
Use it.
269+
Test usage.
234270
235271
## Development
236272
@@ -244,9 +280,7 @@ describe("blockREADME", () => {
244280
});
245281

246282
test("without addons", () => {
247-
const creation = testBlock(blockREADME, {
248-
options,
249-
});
283+
const creation = testBlock(blockREADME, { options: optionsBase });
250284

251285
expect(creation).toMatchInlineSnapshot(`
252286
{
@@ -261,7 +295,7 @@ describe("blockREADME", () => {
261295
262296
## Usage
263297
264-
Use it.
298+
Test usage.
265299
266300
## Development
267301
@@ -295,7 +329,7 @@ describe("blockREADME", () => {
295329
notices: ["> Hello, world! 💖"],
296330
sections: [`## Other\n\nHello!`],
297331
},
298-
options,
332+
options: optionsBase,
299333
});
300334

301335
expect(creation).toMatchInlineSnapshot(`
@@ -314,7 +348,7 @@ describe("blockREADME", () => {
314348
315349
## Usage
316350
317-
Use it.
351+
Test usage.
318352
319353
## Development
320354

‎src/blocks/blockREADME.ts

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,13 +54,16 @@ ${formatBadges(badges)}
5454
${[logo, explainer].filter(Boolean).join("")}
5555
## Usage
5656
57-
${options.usage}
57+
${options.documentation.readme.usage}
5858
5959
## Development
6060
6161
See [\`.github/CONTRIBUTING.md\`](./.github/CONTRIBUTING.md), then [\`.github/DEVELOPMENT.md\`](./.github/DEVELOPMENT.md).
6262
Thanks! ${options.emoji}
63-
${sections.map((section) => `\n${section}`).join("")}
63+
${[...sections, options.documentation.readme.additional]
64+
.filter(Boolean)
65+
.map((section) => `\n${section}`)
66+
.join("")}
6467
${notices.length ? `\n${notices.map((notice) => notice.trim()).join("\n\n")}` : ""}`,
6568
},
6669
};

0 commit comments

Comments
 (0)