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.
9
-
To support this, TypeDoc supports including documents (like this page!) which exist
10
-
as standalone `.md` files in your repository.
11
-
These files can then import code from other files using the `@includeCode` tag.
12
-
13
1
## The `@includeCode` Tag
14
2
15
-
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:
3
+
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.
4
+
As an example, this file is inserting the code block below using:
16
5
17
6
```md
18
7
{@includeCode ../reexports.ts}
@@ -21,51 +10,4 @@ The `@includeCode` tag can be placed in an md file to insert a code snippet at t
21
10
**Result:**
22
11
{@includeCode ../reexports.ts}
23
12
24
-
### Include parts of files
25
-
26
-
#### Using regions
27
-
28
-
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:
| Visual Basic |`#Region regionName`|`#End Region regionName`|
46
-
47
-
For example:
48
-
49
-
```md
50
-
{@includeCode ../enums.ts#simpleEnum}
51
-
```
52
-
53
-
**Result:**
54
-
55
-
{@includeCode ../enums.ts#simpleEnum}
56
-
57
-
#### Using line numbers
58
-
59
-
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.
60
-
61
-
For example:
62
-
63
-
```md
64
-
{@includeCode ../../package.json:2,6-7}
65
-
```
66
-
67
-
**Result:**
68
-
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.
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:
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.
| Visual Basic |`#Region regionName`|`#End Region regionName`|
55
75
56
-
##### Example
76
+
#### Using line numbers (risky)
77
+
78
+
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.
79
+
80
+
> **Warning:** Referencing line numbers should be avoided since the reference will likely break when every time the file changes.
57
81
58
82
```md
59
-
Here is a simple enum:
60
-
{@includeCode ../enums.js#simpleEnum}
83
+
{@includeCode ../../package.json:2,6-7}
61
84
```
62
85
63
-
#### Using line numbers
86
+
**Result:**
64
87
65
-
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.
88
+
{@includeCode ../../package.json:2,6-7}
66
89
67
-
##### Example
90
+
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).
68
91
69
-
```md
70
-
In package.json, notice the following information:
71
-
{@includeCode ../../package.json:2,6-7}
72
-
```
92
+
> **Note:** The first line in the file Line 1, not Line 0, just like you would see in most code editors.
73
93
74
-
> **Warning:** This makes it difficult to maintain the file, as you may need to update the line numbers if you change the code.
0 commit comments