support regions in @includeCode

CHANGELOG.md

@@ -4,6 +4,11 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+-   `@includeCode` can now inject parts of files using region names or line
+    numbers, #2816.
+
 ## v0.27.6 (2024-12-26)
 
 ### Features

example/src/documents/include-code.md

@@ -0,0 +1,13 @@
+## The `@includeCode` Tag
+
+For convenience, an `@includeCode` inline tag is also recognized, which will include the referenced file within a code block, using the file extension for selecting the syntax highlighting language.
+As an example, this file is inserting the code block below using:
+
+```md
+{@includeCode ../reexports.ts}
+```
+
+**Result:**
+{@includeCode ../reexports.ts}
+
+{@include ../../../site/tags/include.md#includePartsOfFiles}

example/src/documents/include.md

@@ -0,0 +1,19 @@
+---
+title: Include and Include Code
+category: Documents
+---
+
+# Including other files
+
+It can be convenient to write long-form guides/tutorials outside of doc comments.
+To support this, TypeDoc supports including documents (like this page!) which exist
+as standalone `.md` files in your repository.
+These files can then import other files using the `@include` tag.
+
+For example, the rest of this page is imported from `include-code.md` using:
+
+```md
+{@include ./include-code.md}
+```
+
+{@include ./include-code.md}

example/src/enums.ts

@@ -1,4 +1,7 @@
 /** Describes the status of a delivery order. */
+
+// #region simpleEnumRegion
+// #region simpleEnum
 export enum SimpleEnum {
     /** This order has just been placed and is yet to be processed. */
     Pending,
@@ -9,6 +12,8 @@ export enum SimpleEnum {
     /** The order has been delivered. */
     Complete = "COMPLETE",
 }
+// #endregion simpleEnum
+// #endregion simpleEnumRegion
 
 /**
  * [A crazy enum from the TypeScript

example/src/index.ts

@@ -7,6 +7,7 @@
  * @document documents/external-markdown.md
  * @document documents/markdown.md
  * @document documents/syntax-highlighting.md
+ * @document documents/include.md
  */
 export * from "./functions";
 export * from "./variables";

site/tags/include.md

@@ -16,7 +16,7 @@ selecting the syntax highlighting language.
 
 ## Example
 
-```js
+```ts
 /**
  * {@include ./doSomething_docs.md}
  *
@@ -30,6 +30,69 @@ selecting the syntax highlighting language.
 function doSomething() {}
 ```
 
+<!-- #region includePartsOfFiles -->
+
+### Include parts of files
+
+#### Using regions (preferred)
+
+The `@include` and `@includeCode` tags can also include only parts of a file by referring to a specific named region.
+
+For example:
+
+```md
+{@includeCode ../../example/src/enums.ts#simpleEnum}
+```
+
+Regions are specified in the files themselves via comments.
+
+In Typescript for example, the following would be a valid region:
+
+{@includeCode ../../example/src/enums.ts#simpleEnumRegion}
+
+**Result:**
+
+{@includeCode ../../example/src/enums.ts#simpleEnum}
+
+Language-dependent region syntax is meant to be compatible with VS Code [Folding](https://code.visualstudio.com/docs/editor/codebasics#_folding). Here is a reproduction of their table, but with `regionName` everywhere because we want to insist on named regions.
+
+| Language              | Start region                                           | End region                                                 |
+| --------------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
+| Bat                   | `::#region regionName` or `REM #region regionName`     | `::#endregion regionName` or `REM #endregion regionName`   |
+| C#                    | `#region regionName`                                   | `#endregion regionName`                                    |
+| C/C++                 | `#pragma region regionName`                            | `#pragma endregion regionName`                             |
+| CSS/Less/SCSS         | `/*#region regionName*/`                               | `/*#endregion regionName*/`                                |
+| Coffeescript          | `#region regionName`                                   | `#endregion regionName`                                    |
+| F#                    | `//#region regionName` or `(#_region) regionName`      | `//#endregion regionName` or `(#_endregion) regionName`    |
+| Java                  | `//#region regionName` or `//<editor-fold> regionName` | `//#endregion regionName` or `//</editor-fold> regionName` |
+| Markdown              | `<!-- #region regionName -->`                          | `<!-- #endregion regionName -->`                           |
+| Perl5                 | `#region regionName` or `=pod regionName`              | `#endregion regionName` or `=cut regionName`               |
+| PHP                   | `#region regionName`                                   | `#endregion regionName`                                    |
+| PowerShell            | `#region regionName`                                   | `#endregion regionName`                                    |
+| Python                | `#region regionName` or `# region regionName`          | `#endregion regionName` or `# endregion regionName`        |
+| TypeScript/JavaScript | `//#region regionName`                                 | `//#endregion regionName`                                  |
+| Visual Basic          | `#Region regionName`                                   | `#End Region regionName`                                   |
+
+#### Using line numbers (risky)
+
+When you can't add comments to define regions (in JSON files, for example) you can use line numbers instead to include a specific region of a file.
+
+> **Warning:** Referencing line numbers should be avoided since the reference will likely break when every time the file changes.
+
+```md
+{@includeCode ../../package.json:2,6-7}
+```
+
+**Result:**
+
+{@includeCode ../../package.json:2,6-7}
+
+A colon (`:`) separates the file path from the line numbers: a comma-separated list of numbers or ranges of the form `<start>-<end>` (`6-7` in the example above).
+
+> **Note:** The first line in the file Line 1, not Line 0, just like you would see in most code editors.
+
+<!-- #endregion includePartsOfFiles -->
+
 ## See Also
 
 -   The [jsdocCompatibility](../options/comments.md#jsdoccompatibility) option.