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
`doc-snippets` is a simple tool that allows you to extract and inject snippets from code into markdown files.
4
4
5
-
##Installation
5
+
# Installation
6
6
7
7
Using NPM:
8
8
@@ -16,9 +16,9 @@ Using Yarn:
16
16
yarn add -D doc-snippets
17
17
```
18
18
19
-
##Usage
19
+
# Usage
20
20
21
-
###Marking and injecting
21
+
## Marking and injecting
22
22
23
23
`doc-snippets` extracts and injects snippets by using tokens:
24
24
@@ -28,7 +28,7 @@ yarn add -D doc-snippets
28
28
- To inject a snippet:
29
29
-`$snippet: snippet-name` - This gets replaced by the snippet with the given name.
30
30
31
-
###Configuration
31
+
## Configuration
32
32
33
33
`doc-snippets` is, by defaut, configured using a JSON file that contains a `doc-snippets` object. By default, this file is `package.json`.
34
34
@@ -46,14 +46,24 @@ The configuration object has the following structure (and default values):
46
46
"ignore": [],
47
47
"dir": "./src/docs"
48
48
},
49
-
"startToken": "$start: ",
50
-
"endToken": "$end",
49
+
"startTokens": [
50
+
{
51
+
"pattern": "$start: ",
52
+
"inline": false
53
+
}
54
+
],
55
+
"endTokens": [
56
+
{
57
+
"pattern": "$end",
58
+
"inline": false
59
+
}
60
+
],
51
61
"injectToken": "$snippet: ",
52
62
"outputDir": "./docs"
53
63
}
54
64
```
55
65
56
-
####`extract` and `inject`
66
+
### `extract` and `inject`
57
67
58
68
The `extract` and `inject` objects both have the same structure:
59
69
@@ -66,29 +76,107 @@ The `extract` object specifies which files will be parsed for snippets to extrac
66
76
The `inject` object specifies which files will be copied into `outputDir` and have snippets injected into them.
67
77
68
78
**Example `extract` object:**
79
+
69
80
```JSON
70
81
"extract": {
71
82
"include": ["sample.sql", "./**/*.{js,ts}"],
72
83
"ignore": "./**/node_modules/**",
73
84
"dir": "./src"
74
85
}
75
86
```
87
+
76
88
In this example, `extract` will perform its search within the `./src` directory.
77
89
78
90
It will include:
91
+
79
92
-`./src/sample.sql`
80
93
- All files within `./src` and its subdirectories ending in `.js` and `.ts`
81
94
82
95
It will ignore:
96
+
83
97
- All directories and subdirectories of any `node_modules` directory found within `./src` and its subdirectories.
84
98
85
99
The same principles apply for the `inject` object.
86
100
87
-
#### `outputDir`
101
+
### Extraction tokens (`startTokens` and `endTokens`)
102
+
103
+
Extraction tokens mark the beginning and end of our snippets.
104
+
105
+
The tokens have two properties:
106
+
-`pattern` - the **exact string** that denotes the token
107
+
-`inline` - defines whether the token is a **regular** or **inline** extraction token
108
+
109
+
#### Regular and inline extraction tokens
110
+
111
+
By default, extraction tokens are designed to be written within their own lines. Anything else written within the token's line will be ignored when extracting snippets.
112
+
113
+
Let's take a look at an example:
114
+
115
+
```typescript
116
+
// $start: hello-snippet we can add comments here
117
+
const greeting ="Hello World!";
118
+
console.log(greeting);
119
+
// $end
120
+
```
121
+
122
+
Using the default configuration, this code will yield a snippet called `hello-snippet` with the following contents:
123
+
```
124
+
const greeting = "Hello World!";
125
+
console.log(greeting);
126
+
```
127
+
128
+
To allow for more flexible snippet extraction, we can use **inline** extraction tokens.
129
+
130
+
For example, let's configure our extraction tokens as follows:
131
+
132
+
```json
133
+
{
134
+
//...
135
+
"startTokens": [
136
+
{
137
+
"pattern": "/* $start: {SNIPPET_NAME} */",
138
+
"inline": true
139
+
}
140
+
],
141
+
"endTokens": [
142
+
{
143
+
"pattern": "/* $end */",
144
+
"inline": true
145
+
}
146
+
]
147
+
}
148
+
```
149
+
150
+
Note that there is a special token within the start token's `pattern` property: **`{SNIPPET_NAME}`**. This denotes where in the inline token the snippet name will appear.
151
+
152
+
In addition, let's assume that we have a file with the following code:
Snippet extraction would now yield a snippet named `hello-inline-snippet` with the following contents:
160
+
```
161
+
"Hello World!";
162
+
console.log(greeting);
163
+
```
164
+
165
+
Inline extraction tokens can be useful when you need to extract only part of your line.
166
+
167
+
Regular and inline extraction tokens can be used at the same time, and snippet extraction will always search for **any** end token after it encounters **any** start token.
168
+
169
+
For reference:
170
+
- When a **regular start token** is encoutered, snippet extraction starts at the beginning of the next line.
171
+
- When an **inline start token** is encountered, snippet extraction starts immediately after the token ends.
172
+
- When a **regular end token** is encountered, snippet extraction ends at the end of the previous line.
173
+
- When an **inline end token** is encountered, snippet extraction ends at the beginning of the token.
174
+
175
+
### `outputDir`
88
176
89
177
The `outputDir` is the output directory for the documentation injected with snippets.
90
178
91
-
###Running `doc-snippets`
179
+
## Running `doc-snippets`
92
180
93
181
`doc-snippets` comes with a CLI tool which is designed to handle most scenarios.
94
182
@@ -100,7 +188,7 @@ doc-snippets combine
100
188
101
189
The `combine` command reads a `"doc-snippets"` section from a configuration file (by default this is `package.json`) and performs snippet extraction and injection, and outputs documentation with injected snippets into an `outputDir`.
102
190
103
-
####'combine' command options
191
+
### 'combine' command options
104
192
105
193
-`-c --config <path>` - Path to configuration file (default: './package.json')
0 commit comments