projen-modules 4.4.1 → 4.6.0

package/.jsii

@@ -99,7 +99,7 @@
   },
   "name": "projen-modules",
   "readme": {
-    "markdown": "# projen-modules\n\nA collection of custom projen modules, that can be used to bootstrap and maintain consistent project configuration, tooling, dependencies, and builds.\n\n## Getting Started\n\n```sh\nyarn install\nnpx projen build\n```\n\nThis will:\n* Install the dependencies\n* Apply any projen changes\n* Run tests\n* Package project locally\n\nAny files changed by projen should be committed to git.\n\nRunning the tests like this will update any snapshot files, this should be reviewed and committed to git.\n\n## Testing\n\nTypes of testing:\n* Snapshot - projen project outputs are stored as a snapshot in the corresponding `__snapshots__` directory. When the project changes then it is expected that these snapshots change too and should be reviewed committed alongside the project.\n* Unit tests - these assert on specific functionality of the project and should be written for any new functionality added.\n\n\n## GitHub Configuration\n\nAll pull requests are merged by the [Mergify](https://mergify.com) merge queue, configured in `.mergify.yml`. Once a pull request is approved, or is opened by `daveshepherd`, and its checks pass, Mergify queues it, brings it up to date with the default branch, waits for the checks again and squash merges it. Draft pull requests and those labelled `do-not-merge` are not merged.\n\nThe repository must be configured as below so that nothing can be merged without going through the queue.\n\n### Mergify\n\nInstall the [Mergify GitHub App](https://github.com/apps/mergify) and give it access to this repository.\n\n### Pull request settings\n\nIn **Settings → General → Pull Requests**:\n* Allow squash merging only (untick merge commits and rebase merging), matching the queue's merge method.\n* Untick **Allow auto-merge**, because GitHub's own auto-merge merges outside the queue.\n* Tick **Automatically delete head branches**.\n\n### Actions settings\n\nIn **Settings → Actions → General**, set **Approval for running fork pull request workflows from contributors** to **Require approval for all external contributors**. A pull request from a fork runs its own copy of the workflows, so it can change how the required checks pass.\n\n### Code scanning\n\nCodeQL runs from `.github/workflows/codeql.yml`, which is managed by projen. In **Settings → Advanced Security**, leave CodeQL **Default setup** off, because it cannot run alongside this workflow. Under **Protection rules**, keep the **Check run failure threshold** at **High or higher** for security alerts and **Errors** for other alerts, as this decides whether the `CodeQL` check fails. Private repositories also need GitHub Code Security enabled there for code scanning results to be uploaded.\n\n### Branch ruleset\n\nIn **Settings → Rules → Rulesets**, create a branch ruleset with enforcement **Active** that targets the default branch, and set:\n* **Bypass list**: the **Mergify** app only, in **Exempt** mode. Do not add admins or other roles, as anyone on this list can merge without the queue.\n* **Restrict updates**: only bypass actors can update the branch, so pull requests cannot be merged from the GitHub UI or CLI and commits cannot be pushed directly.\n* **Restrict deletions** and **Block force pushes**.\n* **Require a pull request before merging**, with 0 required approvals, because Mergify requires approvals itself for authors other than `daveshepherd` and is exempt from this rule. Tick **Dismiss stale pull request approvals when new commits are pushed**, so that commits pushed after an approval need approving again before the queue merges them.\n* **Require status checks to pass**, listing the checks that `.mergify.yml` waits for: `build`, `package-js`, `package-python`. Leave **Require branches to be up to date before merging** unticked, as the queue already updates and retests each pull request.\n* **Require code scanning results**, with the tool **CodeQL**, security alerts set to **High or higher** and alerts set to **Errors**. Mergify is exempt from this rule, so `.mergify.yml` also waits for the `CodeQL` check instead.\n\nDo not enable GitHub's own **Require merge queue** rule, as it competes with Mergify.\n\nIf the queue is unavailable and a change has to be merged, add yourself to the bypass list temporarily and remove yourself afterwards.\n\n## Creating a New Project\n\n\n```\nnpx projen new {project} --from projen-modules\n```\n\nSome projects may have required fields that need to be specified as part of this command, review any errors for details what needs to be specified.\n\n### Project Types\n\n| Project type                                   | Description                |\n| ---------------------------------------------- | -------------------------- |\n| [cdk-typescript-app](API.md#cdktypescriptapp-) | A typescript CDK app |\n| [npm-package](API.md#npmpackage-)              | A typescript npm package   |\n| [python-package](API.md#pythonpackage-)        | A python package           |\n| [jsii-package](API.md#jsiiproject-)            | A typescript JSII package  |\n\n## Project Structure\n\nAll source is located in `src` and is grouped by:\n* `components` - these are common building blocks that can be used by projects to implement specific project functionality.\n* `projects` - these are projects that can be built from this project (see #something)\n* `utils` - these are helper functions that are often reused\n\n`test` contains tests, and mirrors the `src` directory structure. Within here there are `__snapshots__` which contain snapshots of project tests (see #section).\n\n## Known Issues\n\n`cdk-typescript-app` defaults to Jest 30, which hoists `@sinonjs/fake-timers` 15 whose bundled types conflict with the `@types/sinon` used by `aws-sdk-client-mock`. Projects using `aws-sdk-client-mock` can set `compilerOptions.skipLibCheck` on the test tsconfig:\n\n```ts\nproject.tryFindObjectFile('test/tsconfig.json')?.addOverride('compilerOptions.skipLibCheck', true);\n```"
+    "markdown": "<!-- ~~ Generated by projen. To modify, edit .projenrc.ts and run \"npx projen\". -->\n\n# projen-modules\n\nA collection of custom projen modules, that can be used to bootstrap and maintain consistent project configuration, tooling, dependencies, and builds.\n\n## Getting Started\n\n```sh\nyarn install\nnpx projen build\n```\n\nThis will:\n* Install the dependencies\n* Apply any projen changes\n* Run tests\n* Package project locally\n\nAny files changed by projen should be committed to git.\n\nRunning the tests like this will update any snapshot files, this should be reviewed and committed to git.\n\n## Testing\n\nTypes of testing:\n* Snapshot - projen project outputs are stored as a snapshot in the corresponding `__snapshots__` directory. When the project changes then it is expected that these snapshots change too and should be reviewed committed alongside the project.\n* Unit tests - these assert on specific functionality of the project and should be written for any new functionality added.\n\n\n## Creating a New Project\n\n\n```\nnpx projen new {project} --from projen-modules\n```\n\nSome projects may have required fields that need to be specified as part of this command, review any errors for details what needs to be specified.\n\n### Project Types\n\n| Project type                                   | Description                |\n| ---------------------------------------------- | -------------------------- |\n| [cdk-typescript-app](API.md#cdktypescriptapp-) | A typescript CDK app |\n| [npm-package](API.md#npmpackage-)              | A typescript npm package   |\n| [python-package](API.md#pythonpackage-)        | A python package           |\n| [jsii-package](API.md#jsiiproject-)            | A typescript JSII package  |\n\n## Project Structure\n\nAll source is located in `src` and is grouped by:\n* `components` - these are common building blocks that can be used by projects to implement specific project functionality.\n* `projects` - these are projects that can be built from this project (see #something)\n* `utils` - these are helper functions that are often reused\n\n`test` contains tests, and mirrors the `src` directory structure. Within here there are `__snapshots__` which contain snapshots of project tests (see #section).\n\n## GitHub Configuration\n\nAll pull requests are merged by the [Mergify](https://mergify.com) merge queue, configured in `.mergify.yml`. Once a pull request is approved, or is opened by `daveshepherd`, and its checks pass, Mergify queues it, brings it up to date with the default branch, waits for the checks again and squash merges it. Draft pull requests and those labelled `do-not-merge` are not merged.\n\nThe repository must be configured as below so that nothing can be merged without going through the queue.\n\n### Mergify\n\nInstall the [Mergify GitHub App](https://github.com/apps/mergify) and give it access to this repository.\n\n### Pull request settings\n\nIn **Settings → General → Pull Requests**:\n* Allow squash merging only (untick merge commits and rebase merging), matching the queue's merge method.\n* Untick **Allow auto-merge**, because GitHub's own auto-merge merges outside the queue.\n* Tick **Automatically delete head branches**.\n\n### Actions settings\n\nIn **Settings → Actions → General**, set **Approval for running fork pull request workflows from contributors** to **Require approval for all external contributors**. A pull request from a fork runs its own copy of the workflows, so it can change how the required checks pass.\n\n### Code scanning\n\nCodeQL runs from `.github/workflows/codeql.yml`, which is managed by projen. In **Settings → Advanced Security**, leave CodeQL **Default setup** off, because it cannot run alongside this workflow. Under **Protection rules**, keep the **Check run failure threshold** at **High or higher** for security alerts and **Errors** for other alerts, as this decides whether the `CodeQL` check fails. Private repositories also need GitHub Code Security enabled there for code scanning results to be uploaded.\n\n### Branch ruleset\n\nIn **Settings → Rules → Rulesets**, create a branch ruleset with enforcement **Active** that targets the default branch, and set:\n* **Bypass list**: the **Mergify** app only, in **Exempt** mode. Do not add admins or other roles, as anyone on this list can merge without the queue.\n* **Restrict updates**: only bypass actors can update the branch, so pull requests cannot be merged from the GitHub UI or CLI and commits cannot be pushed directly.\n* **Restrict deletions** and **Block force pushes**.\n* **Require a pull request before merging**, with 0 required approvals, because Mergify requires approvals itself for authors other than `daveshepherd` and is exempt from this rule. Tick **Dismiss stale pull request approvals when new commits are pushed**, so that commits pushed after an approval need approving again before the queue merges them.\n* **Require status checks to pass**, listing the checks that `.mergify.yml` waits for: `build`, `package-js`, `package-python`. Leave **Require branches to be up to date before merging** unticked, as the queue already updates and retests each pull request.\n* **Require code scanning results**, with the tool **CodeQL**, security alerts set to **High or higher** and alerts set to **Errors**. Mergify is exempt from this rule, so `.mergify.yml` also waits for the `CodeQL` check instead.\n\nDo not enable GitHub's own **Require merge queue** rule, as it competes with Mergify.\n\nIf the queue is unavailable and a change has to be merged, add yourself to the bypass list temporarily and remove yourself afterwards.\n\n## Known Issues\n\n`cdk-typescript-app` defaults to Jest 30, which hoists `@sinonjs/fake-timers` 15 whose bundled types conflict with the `@types/sinon` used by `aws-sdk-client-mock`. Projects using `aws-sdk-client-mock` can set `compilerOptions.skipLibCheck` on the test tsconfig:\n\n```ts\nproject.tryFindObjectFile('test/tsconfig.json')?.addOverride('compilerOptions.skipLibCheck', true);\n```"
   },
   "repository": {
     "type": "git",
@@ -116,6 +116,42 @@
     }
   },
   "types": {
+    "projen-modules.AddSectionOptions": {
+      "assembly": "projen-modules",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "projen-modules.AddSectionOptions",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/components/readme/index.ts",
+        "line": 11
+      },
+      "name": "AddSectionOptions",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- `ReadmeOrder.DEFAULT`, or the existing order when replacing a section",
+            "remarks": "Sections with the\nsame order keep the order they were added in.",
+            "stability": "stable",
+            "summary": "Position of the section in the README, lowest first."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 18
+          },
+          "name": "order",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ],
+      "symbolId": "src/components/readme/index:AddSectionOptions"
+    },
     "projen-modules.CdkTypeScriptApp": {
       "assembly": "projen-modules",
       "base": "projen.awscdk.AwsCdkTypeScriptApp",
@@ -134,7 +170,7 @@
         },
         "locationInModule": {
           "filename": "src/projects/cdk-ts/index.ts",
-          "line": 61
+          "line": 62
         },
         "parameters": [
           {
@@ -148,7 +184,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/projects/cdk-ts/index.ts",
-        "line": 58
+        "line": 59
       },
       "name": "CdkTypeScriptApp",
       "properties": [
@@ -158,7 +194,7 @@
           },
           "locationInModule": {
             "filename": "src/projects/cdk-ts/index.ts",
-            "line": 59
+            "line": 60
           },
           "name": "readme",
           "type": {
@@ -3771,7 +3807,7 @@
         },
         "locationInModule": {
           "filename": "src/projects/jsii/index.ts",
-          "line": 42
+          "line": 43
         },
         "parameters": [
           {
@@ -3785,7 +3821,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/projects/jsii/index.ts",
-        "line": 39
+        "line": 40
       },
       "name": "JsiiProject",
       "properties": [
@@ -3795,7 +3831,7 @@
           },
           "locationInModule": {
             "filename": "src/projects/jsii/index.ts",
-            "line": 40
+            "line": 41
           },
           "name": "readme",
           "type": {
@@ -7097,7 +7133,7 @@
         },
         "locationInModule": {
           "filename": "src/projects/npm/index.ts",
-          "line": 41
+          "line": 42
         },
         "parameters": [
           {
@@ -7111,7 +7147,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/projects/npm/index.ts",
-        "line": 38
+        "line": 39
       },
       "name": "NpmPackage",
       "properties": [
@@ -7121,7 +7157,7 @@
           },
           "locationInModule": {
             "filename": "src/projects/npm/index.ts",
-            "line": 39
+            "line": 40
           },
           "name": "readme",
           "type": {
@@ -10128,7 +10164,7 @@
         },
         "locationInModule": {
           "filename": "src/projects/python/index.ts",
-          "line": 38
+          "line": 39
         },
         "parameters": [
           {
@@ -10142,7 +10178,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/projects/python/index.ts",
-        "line": 34
+        "line": 35
       },
       "name": "PythonPackage",
       "properties": [
@@ -10153,7 +10189,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/projects/python/index.ts",
-            "line": 35
+            "line": 36
           },
           "name": "autoMerge",
           "optional": true,
@@ -10167,7 +10203,7 @@
           },
           "locationInModule": {
             "filename": "src/projects/python/index.ts",
-            "line": 36
+            "line": 37
           },
           "name": "readme",
           "type": {
@@ -11389,7 +11425,7 @@
         },
         "locationInModule": {
           "filename": "src/components/readme/index.ts",
-          "line": 14
+          "line": 62
         },
         "parameters": [
           {
@@ -11410,16 +11446,44 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/components/readme/index.ts",
-        "line": 11
+        "line": 51
       },
       "methods": [
         {
           "docs": {
-            "stability": "stable"
+            "stability": "stable",
+            "summary": "The README of a project, if it has one."
+          },
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 55
+          },
+          "name": "of",
+          "parameters": [
+            {
+              "name": "project",
+              "type": {
+                "fqn": "projen.Project"
+              }
+            }
+          ],
+          "returns": {
+            "optional": true,
+            "type": {
+              "fqn": "projen-modules.Readme"
+            }
+          },
+          "static": true
+        },
+        {
+          "docs": {
+            "returns": "the section",
+            "stability": "stable",
+            "summary": "Adds a section, or replaces the section with the same title."
           },
           "locationInModule": {
             "filename": "src/components/readme/index.ts",
-            "line": 19
+            "line": 86
           },
           "name": "addSection",
           "parameters": [
@@ -11434,8 +11498,45 @@
               "type": {
                 "primitive": "string"
               }
+            },
+            {
+              "name": "options",
+              "optional": true,
+              "type": {
+                "fqn": "projen-modules.AddSectionOptions"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "projen-modules.Section"
+            }
+          }
+        },
+        {
+          "docs": {
+            "returns": "whether a section was removed",
+            "stability": "stable",
+            "summary": "Removes the section with the given title."
+          },
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 109
+          },
+          "name": "removeSection",
+          "parameters": [
+            {
+              "name": "title",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "primitive": "boolean"
             }
-          ]
+          }
         },
         {
           "docs": {
@@ -11444,7 +11545,7 @@
           },
           "locationInModule": {
             "filename": "src/components/readme/index.ts",
-            "line": 23
+            "line": 126
           },
           "name": "synthesizeContent",
           "overrides": "projen.FileBase",
@@ -11463,17 +11564,44 @@
               "primitive": "string"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "The section with the given title, if there is one."
+          },
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 121
+          },
+          "name": "tryFindSection",
+          "parameters": [
+            {
+              "name": "title",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "optional": true,
+            "type": {
+              "fqn": "projen-modules.Section"
+            }
+          }
         }
       ],
       "name": "Readme",
       "properties": [
         {
           "docs": {
-            "stability": "stable"
+            "stability": "stable",
+            "summary": "The sections, in the order they appear in the README."
           },
+          "immutable": true,
           "locationInModule": {
             "filename": "src/components/readme/index.ts",
-            "line": 13
+            "line": 77
           },
           "name": "sections",
           "type": {
@@ -11491,7 +11619,7 @@
           },
           "locationInModule": {
             "filename": "src/components/readme/index.ts",
-            "line": 12
+            "line": 59
           },
           "name": "description",
           "optional": true,
@@ -11536,6 +11664,91 @@
       ],
       "symbolId": "src/components/readme/index:ReadmeOptions"
     },
+    "projen-modules.ReadmeOrder": {
+      "assembly": "projen-modules",
+      "docs": {
+        "stability": "stable",
+        "summary": "Orders of the bands of sections in the README, leaving room for sections in between."
+      },
+      "fqn": "projen-modules.ReadmeOrder",
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/components/readme/index.ts",
+        "line": 25
+      },
+      "name": "ReadmeOrder",
+      "properties": [
+        {
+          "const": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Sections added without an order."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 37
+          },
+          "name": "DEFAULT",
+          "static": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "const": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Sections a reader needs first, such as getting started."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 29
+          },
+          "name": "INTRODUCTION",
+          "static": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "const": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Reference material, such as repository configuration and known issues."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 41
+          },
+          "name": "REFERENCE",
+          "static": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "const": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "How to use and operate the project."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/components/readme/index.ts",
+            "line": 33
+          },
+          "name": "USAGE",
+          "static": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ],
+      "symbolId": "src/components/readme/index:ReadmeOrder"
+    },
     "projen-modules.Section": {
       "assembly": "projen-modules",
       "docs": {
@@ -11601,6 +11814,6 @@
       "symbolId": "src/components/readme/elements/section:Section"
     }
   },
-  "version": "4.4.1",
-  "fingerprint": "/tqZemrChnpwV/43aTg2T0zcikN0vZiHq/wSxzjZZCk="
+  "version": "4.6.0",
+  "fingerprint": "FPqrAwKcURWT1wMe1KftZZZlz1y+mQUCz0KxMFkGumg="
 }

package/API.md

@@ -5275,7 +5275,9 @@ new Readme(project: Project, options?: ReadmeOptions)
 | <code><a href="#projen-modules.Readme.projectCreation">projectCreation</a></code> | Called once, right after `synthesize()`, only when the project is created for the first time. |
 | <code><a href="#projen-modules.Readme.synthesize">synthesize</a></code> | Writes the file to the project's output directory. |
 | <code><a href="#projen-modules.Readme.diff">diff</a></code> | Returns a unified diff of the old and new file contents with context lines and hunk headers. |
-| <code><a href="#projen-modules.Readme.addSection">addSection</a></code> | *No description.* |
+| <code><a href="#projen-modules.Readme.addSection">addSection</a></code> | Adds a section, or replaces the section with the same title. |
+| <code><a href="#projen-modules.Readme.removeSection">removeSection</a></code> | Removes the section with the given title. |
+| <code><a href="#projen-modules.Readme.tryFindSection">tryFindSection</a></code> | The section with the given title, if there is one. |
 
 ---
 
@@ -5406,9 +5408,11 @@ Number of context lines around changes.
 ##### `addSection` <a name="addSection" id="projen-modules.Readme.addSection"></a>
 
 ```typescript
-public addSection(title: string, body: string): void
+public addSection(title: string, body: string, options?: AddSectionOptions): Section
 ```
 
+Adds a section, or replaces the section with the same title.
+
 ###### `title`<sup>Required</sup> <a name="title" id="projen-modules.Readme.addSection.parameter.title"></a>
 
 - *Type:* string
@@ -5421,12 +5425,47 @@ public addSection(title: string, body: string): void
 
 ---
 
+###### `options`<sup>Optional</sup> <a name="options" id="projen-modules.Readme.addSection.parameter.options"></a>
+
+- *Type:* <a href="#projen-modules.AddSectionOptions">AddSectionOptions</a>
+
+---
+
+##### `removeSection` <a name="removeSection" id="projen-modules.Readme.removeSection"></a>
+
+```typescript
+public removeSection(title: string): boolean
+```
+
+Removes the section with the given title.
+
+###### `title`<sup>Required</sup> <a name="title" id="projen-modules.Readme.removeSection.parameter.title"></a>
+
+- *Type:* string
+
+---
+
+##### `tryFindSection` <a name="tryFindSection" id="projen-modules.Readme.tryFindSection"></a>
+
+```typescript
+public tryFindSection(title: string): Section
+```
+
+The section with the given title, if there is one.
+
+###### `title`<sup>Required</sup> <a name="title" id="projen-modules.Readme.tryFindSection.parameter.title"></a>
+
+- *Type:* string
+
+---
+
 #### Static Functions <a name="Static Functions" id="Static Functions"></a>
 
 | **Name** | **Description** |
 | --- | --- |
 | <code><a href="#projen-modules.Readme.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
 | <code><a href="#projen-modules.Readme.isComponent">isComponent</a></code> | Test whether the given construct is a component. |
+| <code><a href="#projen-modules.Readme.of">of</a></code> | The README of a project, if it has one. |
 
 ---
 
@@ -5478,6 +5517,22 @@ Test whether the given construct is a component.
 
 ---
 
+##### `of` <a name="of" id="projen-modules.Readme.of"></a>
+
+```typescript
+import { Readme } from 'projen-modules'
+
+Readme.of(project: Project)
+```
+
+The README of a project, if it has one.
+
+###### `project`<sup>Required</sup> <a name="project" id="projen-modules.Readme.of.parameter.project"></a>
+
+- *Type:* projen.Project
+
+---
+
 #### Properties <a name="Properties" id="Properties"></a>
 
 | **Name** | **Type** | **Description** |
@@ -5491,7 +5546,7 @@ Test whether the given construct is a component.
 | <code><a href="#projen-modules.Readme.property.marker">marker</a></code> | <code>string</code> | The projen marker, used to identify files as projen-generated. |
 | <code><a href="#projen-modules.Readme.property.executable">executable</a></code> | <code>boolean</code> | Indicates if the file should be marked as executable. |
 | <code><a href="#projen-modules.Readme.property.readonly">readonly</a></code> | <code>boolean</code> | Indicates if the file should be read-only or read-write. |
-| <code><a href="#projen-modules.Readme.property.sections">sections</a></code> | <code><a href="#projen-modules.Section">Section</a>[]</code> | *No description.* |
+| <code><a href="#projen-modules.Readme.property.sections">sections</a></code> | <code><a href="#projen-modules.Section">Section</a>[]</code> | The sections, in the order they appear in the README. |
 | <code><a href="#projen-modules.Readme.property.description">description</a></code> | <code>string</code> | *No description.* |
 
 ---
@@ -5616,6 +5671,8 @@ public readonly sections: Section[];
 
 - *Type:* <a href="#projen-modules.Section">Section</a>[]
 
+The sections, in the order they appear in the README.
+
 ---
 
 ##### `description`<sup>Optional</sup> <a name="description" id="projen-modules.Readme.property.description"></a>
@@ -5631,6 +5688,40 @@ public readonly description: string;
 
 ## Structs <a name="Structs" id="Structs"></a>
 
+### AddSectionOptions <a name="AddSectionOptions" id="projen-modules.AddSectionOptions"></a>
+
+#### Initializer <a name="Initializer" id="projen-modules.AddSectionOptions.Initializer"></a>
+
+```typescript
+import { AddSectionOptions } from 'projen-modules'
+
+const addSectionOptions: AddSectionOptions = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#projen-modules.AddSectionOptions.property.order">order</a></code> | <code>number</code> | Position of the section in the README, lowest first. |
+
+---
+
+##### `order`<sup>Optional</sup> <a name="order" id="projen-modules.AddSectionOptions.property.order"></a>
+
+```typescript
+public readonly order: number;
+```
+
+- *Type:* number
+- *Default:* `ReadmeOrder.DEFAULT`, or the existing order when replacing a section
+
+Position of the section in the README, lowest first.
+
+Sections with the
+same order keep the order they were added in.
+
+---
+
 ### CdkTypeScriptAppOptions <a name="CdkTypeScriptAppOptions" id="projen-modules.CdkTypeScriptAppOptions"></a>
 
 CdkTypeScriptAppOptions.
@@ -14566,6 +14657,72 @@ The description of the project.
 
 ## Classes <a name="Classes" id="Classes"></a>
 
+### ReadmeOrder <a name="ReadmeOrder" id="projen-modules.ReadmeOrder"></a>
+
+Orders of the bands of sections in the README, leaving room for sections in between.
+
+
+
+
+#### Constants <a name="Constants" id="Constants"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#projen-modules.ReadmeOrder.property.DEFAULT">DEFAULT</a></code> | <code>number</code> | Sections added without an order. |
+| <code><a href="#projen-modules.ReadmeOrder.property.INTRODUCTION">INTRODUCTION</a></code> | <code>number</code> | Sections a reader needs first, such as getting started. |
+| <code><a href="#projen-modules.ReadmeOrder.property.REFERENCE">REFERENCE</a></code> | <code>number</code> | Reference material, such as repository configuration and known issues. |
+| <code><a href="#projen-modules.ReadmeOrder.property.USAGE">USAGE</a></code> | <code>number</code> | How to use and operate the project. |
+
+---
+
+##### `DEFAULT`<sup>Required</sup> <a name="DEFAULT" id="projen-modules.ReadmeOrder.property.DEFAULT"></a>
+
+```typescript
+public readonly DEFAULT: number;
+```
+
+- *Type:* number
+
+Sections added without an order.
+
+---
+
+##### `INTRODUCTION`<sup>Required</sup> <a name="INTRODUCTION" id="projen-modules.ReadmeOrder.property.INTRODUCTION"></a>
+
+```typescript
+public readonly INTRODUCTION: number;
+```
+
+- *Type:* number
+
+Sections a reader needs first, such as getting started.
+
+---
+
+##### `REFERENCE`<sup>Required</sup> <a name="REFERENCE" id="projen-modules.ReadmeOrder.property.REFERENCE"></a>
+
+```typescript
+public readonly REFERENCE: number;
+```
+
+- *Type:* number
+
+Reference material, such as repository configuration and known issues.
+
+---
+
+##### `USAGE`<sup>Required</sup> <a name="USAGE" id="projen-modules.ReadmeOrder.property.USAGE"></a>
+
+```typescript
+public readonly USAGE: number;
+```
+
+- *Type:* number
+
+How to use and operate the project.
+
+---
+
 ### Section <a name="Section" id="projen-modules.Section"></a>
 
 #### Initializers <a name="Initializers" id="projen-modules.Section.Initializer"></a>