You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It can be convenient to write long-form guides/tutorials outside of doc comments.
8
+
To support this, TypeDoc supports including documents (like this page!) which exist
9
+
as standalone `.md` files in your repository.
10
+
These files can then import code from other files using the `@includeCode` tag.
11
+
12
+
## The `@includeCode` Tag
13
+
The `@includeCode` tag can be placed in an md file to insert a code snippet at that location. As an example, this file is inserting the code block below using:
14
+
15
+
```md
16
+
{@includeCode ../reexports.ts}
17
+
```
18
+
19
+
**Result:**
20
+
{@includeCode ../reexports.ts}
21
+
22
+
### Include parts of files
23
+
24
+
#### Using regions
25
+
The `@includeCode` tag can also include only parts of a file using language-dependent region syntax as defined in the VS Code documentation for [Folding](https://code.visualstudio.com/docs/editor/codebasics#_folding), reproduced here for convenience:
26
+
27
+
Language | Start region | End region
28
+
---------|--------------|------------
29
+
Bat | `::#region regionName` or `REM #region regionName` | `::#endregion regionName` or `REM #endregion regionName`
Visual Basic | `#Region regionName` | `#End Region regionName`
43
+
44
+
For example:
45
+
46
+
```md
47
+
{@includeCode ../enums.ts#simpleEnum}
48
+
```
49
+
50
+
**Result:**
51
+
52
+
{@includeCode ../enums.ts#simpleEnum}
53
+
54
+
#### Using line numbers
55
+
For cases where you can't modify the source file or where comments are not allowed (in JSON files, for example), you can use line numbers to include a specific region of a file.
56
+
57
+
For example:
58
+
59
+
```md
60
+
{@includeCode ../../package.json:2,6-7}
61
+
```
62
+
63
+
**Result:**
64
+
65
+
{@includeCode ../../package.json:2,6-7}
66
+
67
+
> **Warning:** This makes it difficult to maintain the file, as you may need to update the line numbers if you change the code.
Copy file name to clipboardexpand all lines: site/tags/include.md
+40
Original file line number
Diff line number
Diff line change
@@ -30,6 +30,46 @@ selecting the syntax highlighting language.
30
30
functiondoSomething() {}
31
31
```
32
32
33
+
### Include parts of files
34
+
35
+
#### Using regions
36
+
The `@include` and `@includeCode` tags can also include only parts of a file using language-dependent region syntax as defined in the VS Code documentation for [Folding](https://code.visualstudio.com/docs/editor/codebasics#_folding), reproduced here for convenience:
37
+
38
+
Language | Start region | End region
39
+
---------|--------------|------------
40
+
Bat | `::#region regionName` or `REM #region regionName` | `::#endregion regionName` or `REM #endregion regionName`
Visual Basic | `#Region regionName` | `#End Region regionName`
54
+
55
+
##### Example
56
+
57
+
```md
58
+
Here is a simple enum:
59
+
{@includeCode ../enums.js#simpleEnum}
60
+
```
61
+
62
+
#### Using line numbers
63
+
For cases where you can't modify the source file or where comments are not allowed (in JSON files, for example), you can use line numbers to include a specific region of a file.
64
+
65
+
##### Example
66
+
67
+
```md
68
+
In package.json, notice the following information:
69
+
{@includeCode ../../package.json:2,6-7}
70
+
```
71
+
> **Warning:** This makes it difficult to maintain the file, as you may need to update the line numbers if you change the code.
72
+
33
73
## See Also
34
74
35
75
- The [jsdocCompatibility](../options/comments.md#jsdoccompatibility) option.
0 commit comments