doc-snippets - npm Package Compare versions

Comparing version 0.4.0-pre.2 to 0.4.0-pre.3

build/cli/cli.js

@@ -38,2 +38,13 @@ "use strict";
 };
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
@@ -68,6 +79,5 @@ return (mod && mod.__esModule) ? mod : { "default": mod };
                                 configFilePath = (_a = options.config) !== null && _a !== void 0 ? _a : "./package.json";
-                                config = parseDocSnippetsConfig(configFilePath);
+                                config = parseDocSnippetsConfigFile(configFilePath);
                                 applyCommandOptionsToConfig(options, config);
-                                console.log("OPTIONS", options);
-                                console.log("CONFIG", config);
+                                console.log("CONFIG:", config);
                                 return [4 /*yield*/, (0, combine_1.combineDocsAndSnippets)(config)];
@@ -88,3 +98,3 @@ case 1:
 exports.run = run;
-function parseDocSnippetsConfig(configFilePath) {
+function parseDocSnippetsConfigFile(configFilePath) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
@@ -107,4 +117,4 @@ var configFileContents = fs_1.default.readFileSync(configFilePath, {
         },
-        startToken: (_o = config.startToken) !== null && _o !== void 0 ? _o : defaults_1.defaultDocSnippetsConfig.startToken,
-        endToken: (_p = config.endToken) !== null && _p !== void 0 ? _p : defaults_1.defaultDocSnippetsConfig.endToken,
+        startTokens: (_o = config.startTokens) !== null && _o !== void 0 ? _o : defaults_1.defaultDocSnippetsConfig.startTokens,
+        endTokens: (_p = config.endTokens) !== null && _p !== void 0 ? _p : defaults_1.defaultDocSnippetsConfig.endTokens,
         injectToken: (_q = config.injectToken) !== null && _q !== void 0 ? _q : defaults_1.defaultDocSnippetsConfig.injectToken,
@@ -116,14 +126,71 @@ outputDir: (_r = config.outputDir) !== null && _r !== void 0 ? _r : defaults_1.defaultDocSnippetsConfig.outputDir,
 function applyCommandOptionsToConfig(options, config) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
-    config.extract.dir = (_a = options.extractDir) !== null && _a !== void 0 ? _a : config.extract.dir;
-    config.extract.include = (_b = options.extractInclude) !== null && _b !== void 0 ? _b : config.extract.include;
-    config.extract.ignore = (_c = options.extractIgnore) !== null && _c !== void 0 ? _c : config.extract.ignore;
-    config.inject.dir = (_d = options.extractDir) !== null && _d !== void 0 ? _d : config.inject.dir;
-    config.inject.include = (_e = options.extractInclude) !== null && _e !== void 0 ? _e : config.inject.include;
-    config.inject.ignore = (_f = options.extractIgnore) !== null && _f !== void 0 ? _f : config.inject.ignore;
-    config.startToken = (_g = options.startToken) !== null && _g !== void 0 ? _g : config.startToken;
-    config.endToken = (_h = options.endToken) !== null && _h !== void 0 ? _h : config.endToken;
-    config.injectToken = (_j = options.injectToken) !== null && _j !== void 0 ? _j : config.injectToken;
-    config.outputDir = (_k = options.outputDir) !== null && _k !== void 0 ? _k : config.outputDir;
+    var e_1, _a, e_2, _b, e_3, _c, e_4, _d;
+    var _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+    config.extract.dir = (_e = options.extractDir) !== null && _e !== void 0 ? _e : config.extract.dir;
+    config.extract.include = (_f = options.extractInclude) !== null && _f !== void 0 ? _f : config.extract.include;
+    config.extract.ignore = (_g = options.extractIgnore) !== null && _g !== void 0 ? _g : config.extract.ignore;
+    config.inject.dir = (_h = options.extractDir) !== null && _h !== void 0 ? _h : config.inject.dir;
+    config.inject.include = (_j = options.extractInclude) !== null && _j !== void 0 ? _j : config.inject.include;
+    config.inject.ignore = (_k = options.extractIgnore) !== null && _k !== void 0 ? _k : config.inject.ignore;
+    if ((_l = options.startTokens) !== null && _l !== void 0 ? _l : options.inlineStartTokens) {
+        var tokens = [];
+        try {
+            for (var _u = __values((_m = options.startTokens) !== null && _m !== void 0 ? _m : []), _v = _u.next(); !_v.done; _v = _u.next()) {
+                var token = _v.value;
+                tokens.push({ pattern: token, inline: false });
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_v && !_v.done && (_a = _u.return)) _a.call(_u);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        try {
+            for (var _w = __values((_o = options.inlineStartTokens) !== null && _o !== void 0 ? _o : []), _x = _w.next(); !_x.done; _x = _w.next()) {
+                var token = _x.value;
+                tokens.push({ pattern: token, inline: true });
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_x && !_x.done && (_b = _w.return)) _b.call(_w);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    }
+    if ((_p = options.endTokens) !== null && _p !== void 0 ? _p : options.inlineEndTokens) {
+        var tokens = [];
+        try {
+            for (var _y = __values((_q = options.endTokens) !== null && _q !== void 0 ? _q : []), _z = _y.next(); !_z.done; _z = _y.next()) {
+                var token = _z.value;
+                tokens.push({ pattern: token, inline: false });
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_z && !_z.done && (_c = _y.return)) _c.call(_y);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        try {
+            for (var _0 = __values((_r = options.inlineEndTokens) !== null && _r !== void 0 ? _r : []), _1 = _0.next(); !_1.done; _1 = _0.next()) {
+                var token = _1.value;
+                tokens.push({ pattern: token, inline: true });
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_1 && !_1.done && (_d = _0.return)) _d.call(_0);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+    }
+    config.injectToken = (_s = options.injectToken) !== null && _s !== void 0 ? _s : config.injectToken;
+    config.outputDir = (_t = options.outputDir) !== null && _t !== void 0 ? _t : config.outputDir;
 }
 //# sourceMappingURL=cli.js.map

build/cli/combineOptions.js

@@ -14,6 +14,8 @@ "use strict";
     "--inject-ignore <paths...>": "Ignore specified paths or glob patterns in snippet injection",
-    "--start-token <token>": "Token marking the start of the snippet",
-    "--end-token <token>": "Token marking the end of the snippet",
+    "--start-tokens <tokens...>": "Tokens marking the start of the snippet",
+    "--end-tokens <tokens...>": "Tokens marking the end of the snippet",
+    "--inline-start-tokens <tokens...>": "Inline Tokens marking the start of the snippet",
+    "--inline-end-tokens <tokens...>": "Inline Tokens marking the end of the snippet",
     "--inject-token <token>": "Token marking the point of snippet injection",
 };
 //# sourceMappingURL=combineOptions.js.map

build/lib/combine.js

@@ -67,3 +67,3 @@ "use strict";
                     console.log("- Extract Snippets");
-                    return [4 /*yield*/, (0, extract_1.extractSnippets)(config.extract, config.startToken, config.endToken)];
+                    return [4 /*yield*/, (0, extract_1.extractSnippets)(config.extract, config.startTokens, config.endTokens)];
                 case 1:
@@ -70,0 +70,0 @@ snippets = _c.sent();

build/lib/defaults/defaultDocSnippetsConfig.js

@@ -15,4 +15,4 @@ "use strict";
     },
-    startToken: "$start: ",
-    endToken: "$end",
+    startTokens: [{ pattern: "$start: ", inline: false }],
+    endTokens: [{ pattern: "$end", inline: false }],
     injectToken: "$snippet: ",
@@ -19,0 +19,0 @@ outputDir: "./docs",

build/lib/extract.d.ts

@@ -1,3 +0,3 @@
-import { SearchOptions } from "./types";
-export declare function extractSnippets(options: SearchOptions, snippetStartToken: string, snippetEndToken: string): Promise<Record<string, string>>;
-export declare function extractSnippetsFromFile(snippets: Record<string, string>, filePath: string, snippetStartToken: string, snippetEndToken: string): Promise<void>;
+import { SearchOptions, ExtractionToken } from "./types";
+export declare function extractSnippets(options: SearchOptions, startTokens: ExtractionToken[], endTokens: ExtractionToken[]): Promise<Record<string, string>>;
+export declare function extractSnippetsFromFile(snippets: Record<string, string>, filePath: string, snippetStartTokens: ExtractionToken[], snippetEndTokens: ExtractionToken[]): Promise<void>;

build/lib/extract.js

@@ -55,5 +55,7 @@ "use strict";
 var utils_1 = require("./utils");
+var regexp_1 = require("./utils/regexp");
+var getSnippetFromRegExpMatch_1 = require("./utils/regexp/getSnippetFromRegExpMatch");
 var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
-function extractSnippets(options, snippetStartToken, snippetEndToken) {
+function extractSnippets(options, startTokens, endTokens) {
     return __awaiter(this, void 0, void 0, function () {
@@ -75,3 +77,3 @@ var snippets, filePaths, filePaths_1, filePaths_1_1, filePath, e_1_1;
                     filePath = filePaths_1_1.value;
-                    return [4 /*yield*/, extractSnippetsFromFile(snippets, path_1.default.join(options.dir, filePath), snippetStartToken, snippetEndToken)];
+                    return [4 /*yield*/, extractSnippetsFromFile(snippets, path_1.default.join(options.dir, filePath), startTokens, endTokens)];
                 case 3:
@@ -100,34 +102,25 @@ _b.sent();
 exports.extractSnippets = extractSnippets;
-function extractSnippetsFromFile(snippets, filePath, snippetStartToken, snippetEndToken) {
+function extractSnippetsFromFile(snippets, filePath, snippetStartTokens, snippetEndTokens) {
     return __awaiter(this, void 0, void 0, function () {
-        var contents, index, startIdx, nameStartIdx, lineEndIdx, nameEndIdx, name, snippetStartIdx, snippetEndIdx, snippet;
-        return __generator(this, function (_a) {
-            contents = fs_1.default.readFileSync(filePath, "utf-8");
-            index = 0;
-            while (index < contents.length) {
-                startIdx = contents.indexOf(snippetStartToken, index);
-                if (startIdx < 0) {
-                    index = contents.length;
-                    continue;
+        var fileContents, foundSnippets, foundSnippets_1, foundSnippets_1_1, snippet;
+        var e_2, _a;
+        return __generator(this, function (_b) {
+            fileContents = fs_1.default.readFileSync(filePath, "utf-8");
+            foundSnippets = findSnippets(fileContents, snippetStartTokens, snippetEndTokens);
+            try {
+                for (foundSnippets_1 = __values(foundSnippets), foundSnippets_1_1 = foundSnippets_1.next(); !foundSnippets_1_1.done; foundSnippets_1_1 = foundSnippets_1.next()) {
+                    snippet = foundSnippets_1_1.value;
+                    console.log("- Extract Snippet", snippet.name);
+                    if (snippets[snippet.name]) {
+                        throw Error("Duplicate Snippet Definition: ".concat(snippet.name));
+                    }
+                    snippets[snippet.name] = snippet.contents;
                 }
-                nameStartIdx = startIdx + snippetStartToken.length;
-                lineEndIdx = contents.indexOf("\n", nameStartIdx);
-                nameEndIdx = contents.indexOf(" ", nameStartIdx);
-                if (nameEndIdx < 0 || nameEndIdx > lineEndIdx) {
-                    nameEndIdx = lineEndIdx;
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (foundSnippets_1_1 && !foundSnippets_1_1.done && (_a = foundSnippets_1.return)) _a.call(foundSnippets_1);
                 }
-                name = contents.substring(nameStartIdx, nameEndIdx);
-                snippetStartIdx = lineEndIdx + 1;
-                snippetEndIdx = contents.indexOf(snippetEndToken, snippetStartIdx);
-                // Walk back from the $end until we hit the first \n
-                while (contents[snippetEndIdx] !== "\n") {
-                    snippetEndIdx -= 1;
-                }
-                snippet = contents.substring(snippetStartIdx, snippetEndIdx);
-                console.log("- Extract Snippet", name);
-                if (snippets[name]) {
-                    throw Error("Duplicate Snippet Definition: ".concat(name));
-                }
-                snippets[name] = snippet;
-                index = snippetEndIdx + snippetEndToken.length;
+                finally { if (e_2) throw e_2.error; }
             }
@@ -139,2 +132,22 @@ return [2 /*return*/];
 exports.extractSnippetsFromFile = extractSnippetsFromFile;
+function findSnippets(contents, snippetStartTokens, snippetEndTokens) {
+    var e_3, _a;
+    var regExp = (0, regexp_1.getSnippetCaptureRegExp)(snippetStartTokens, snippetEndTokens);
+    var matches = contents.matchAll(regExp);
+    var snippets = [];
+    try {
+        for (var matches_1 = __values(matches), matches_1_1 = matches_1.next(); !matches_1_1.done; matches_1_1 = matches_1.next()) {
+            var match = matches_1_1.value;
+            snippets.push((0, getSnippetFromRegExpMatch_1.getSnippetFromRegExpMatch)(match));
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (matches_1_1 && !matches_1_1.done && (_a = matches_1.return)) _a.call(matches_1);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return snippets;
+}
 //# sourceMappingURL=extract.js.map

build/lib/types/docSnippetsConfig.d.ts

@@ -1,7 +0,7 @@
-import { SearchOptions } from ".";
+import { ExtractionToken, SearchOptions } from ".";
 export declare type DocSnippetsConfig = {
     extract: SearchOptions;
     inject: SearchOptions;
-    startToken: string;
-    endToken: string;
+    startTokens: ExtractionToken[];
+    endTokens: ExtractionToken[];
     injectToken: string;
@@ -13,6 +13,6 @@ outputDir: string;
     inject?: Partial<SearchOptions>;
-    startToken?: string;
-    endToken?: string;
+    startTokens?: ExtractionToken[];
+    endTokens?: ExtractionToken[];
     injectToken?: string;
     outputDir?: string;
 };

build/lib/types/index.d.ts

 export * from "./docSnippetsConfig";
 export * from "./searchOptions";
+export * from "./snippet";
+export * from "./token";

build/lib/types/index.js

@@ -19,2 +19,4 @@ "use strict";
 __exportStar(require("./searchOptions"), exports);
+__exportStar(require("./snippet"), exports);
+__exportStar(require("./token"), exports);
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "doc-snippets",
-  "version": "0.4.0-pre.2",
+  "version": "0.4.0-pre.3",
   "description": "Extract and inject snippets from code into markdown files",
@@ -5,0 +5,0 @@ "author": {

README.md

@@ -5,3 +5,3 @@ # doc-snippets
 
-## Installation
+# Installation
 
@@ -20,5 +20,5 @@ Using NPM:
 
-## Usage
+# Usage
 
-### Marking and injecting
+## Marking and injecting
 
@@ -33,5 +33,5 @@ `doc-snippets` extracts and injects snippets by using tokens:
 
-### Configuration
+## Configuration
 
-`doc-snippets` is, by defaut, configured using a JSON file that contains a `doc-snippets` object. By default, this file is `package.json`.
+The `doc-snippets` CLI is configured using a JSON file that contains a `doc-snippets` object. By default, this file is `package.json`.
 
@@ -52,4 +52,14 @@ The configuration object has the following structure (and default values):
   },
-  "startToken": "$start: ",
-  "endToken": "$end",
+  "startTokens": [
+    {
+      "pattern": "$start: ",
+      "inline": false
+    }
+  ],
+  "endTokens": [
+    {
+      "pattern": "$end",
+      "inline": false
+    }
+  ],
   "injectToken": "$snippet: ",
@@ -60,3 +70,3 @@ "outputDir": "./docs"
 
-#### `extract` and `inject`
+### `extract` and `inject`
 
@@ -74,2 +84,3 @@ The `extract` and `inject` objects both have the same structure:
 **Example `extract` object:**
+
 ```JSON
@@ -82,5 +93,7 @@ "extract": {
 ```
+
 In this example, `extract` will perform its search within the `./src` directory.
 
 It will include:
+
 - `./src/sample.sql`
@@ -90,2 +103,3 @@ - All files within `./src` and its subdirectories ending in `.js` and `.ts`
 It will ignore:
+
 - All directories and subdirectories of any `node_modules` directory found within `./src` and its subdirectories.
@@ -95,7 +109,100 @@
 
-#### `outputDir`
+### Extraction tokens (`startTokens` and `endTokens`)
 
+Extraction tokens mark the beginning and end of our snippets.
+
+The tokens have two properties:
+- `pattern` - the **exact string** that denotes the token
+- `inline` - defines whether the token is a **regular** or **inline** extraction token
+
+#### Regular and inline extraction tokens
+
+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.
+
+Let's take a look at an example:
+
+```typescript
+// $start: hello-snippet we can add comments here
+const greeting = "Hello World!";
+console.log(greeting);
+// $end
+```
+
+Using the default configuration, this code will yield a snippet called `hello-snippet` with the following contents:
+```
+const greeting = "Hello World!";
+console.log(greeting);
+```
+
+To allow for more flexible snippet extraction, we can use **inline** extraction tokens.
+
+For example, let's configure our extraction tokens as follows:
+
+```json
+{
+  //...
+  "startTokens": [
+    {
+      "pattern": "/* $start: {SNIPPET_NAME} */",
+      "inline": true
+    }
+  ],
+  "endTokens": [
+    {
+      "pattern": "/* $end */",
+      "inline": true
+    }
+  ]
+}
+```
+
+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.
+
+In addition, let's assume that we have a file with the following code:
+
+```typescript
+const greeting = /* $start: hello-inline-snippet */"Hello World!";
+console.log(greeting);/* $end */
+```
+
+Snippet extraction would now yield a snippet named `hello-inline-snippet` with the following contents:
+```
+"Hello World!";
+console.log(greeting);
+```
+
+Inline extraction tokens can be useful when you need to extract only part of your line.
+
+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.
+
+For reference:
+- When a  **regular start token** is encoutered, snippet extraction starts at the beginning of the next line.
+- When an **inline start token** is encountered, snippet extraction starts immediately after the token ends.
+- When a **regular end token** is encountered, snippet extraction ends at the end of the previous line.
+- When an **inline end token** is encountered, snippet extraction ends at the beginning of the token.
+
+### `injectionToken`
+
+The `injectionToken` is the **exact string** which will be replaced by your snippet during injection. The snippet must follow immediately after the `injectionToken`.
+
+For example, if you have the following `injectionToken`:
+
+```json
+{
+  // Note the space character at the end
+  "injectionToken": "$snippet: "
+}
+```
+
+the following text would be replaced by a snippet called `hello-snippet`:
+
+```md
+$snippet: hello-snippet
+```
+
+### `outputDir`
+
 The `outputDir` is the output directory for the documentation injected with snippets.
 
-### Running `doc-snippets`
+## Running `doc-snippets`
 
@@ -112,4 +219,6 @@ `doc-snippets` comes with a CLI tool which is designed to handle most scenarios.
 
-#### 'combine' command options
+All configuration options can be overridden using `combine`'s command options.
 
+### 'combine' command options
+
 - `-c --config <path>` - Path to configuration file (default: './package.json')
@@ -123,8 +232,10 @@ - `-o --output-dir <path>` - Combined documentation output directory
 - `--inject-ignore <paths...>` - Ignore specified paths or glob patterns in snippet injection
-- `--start-token <token>` - Token marking the start of the snippet
-- `--end-token <token>` - Token marking the end of the snippet
+- `--start-tokens <tokens...>` - Tokens marking the start of the snippet
+- `--end-tokens <tokens...>` - Tokens marking the end of the snippet
+- `--inline-start-tokens <tokens...>` - Inline Tokens marking the start of the snippet
+- `--inline-end-tokens <tokens...>` - Inline Tokens marking the end of the snippet
 - `--inject-token <token>` - Token marking the point of snippet injection
 
 
-### In your own code
+## In your own code
 
@@ -139,10 +250,30 @@ If you want to use `doc-snippets` programatically, it offers two exported functions:
   ignore: "./**/node_modules/**",
-  dir: "./src"
-}
+  dir: "./src",
+};
 
 //Returns snippets as `Record<string, string>`.
-const snippets = await extractSnippets(searchOptions, "$start: ", "$end");
+const startTokens = [
+  {
+    pattern: "$start: "
+  },
+  {
+    pattern: "/* $start: {SNIPPET_NAME} */",
+    inline: true
+  }
+];
 
+const endTokens = [
+  {
+    pattern: "$end"
+  },
+  {
+    pattern: "/* $end */",
+    inline: true
+  }
+];
+
+const snippets = await extractSnippets(searchOptions, startTokens, endTokens);
+
 //Injects `snippets` into `./dest/readme.md` replacing all instances of `$snippet: snippet-name` with the appropriate snippet
 await injectSnippetsIntoFile(snippets, "./dest/readme.md", "$snippet: ");
 ```

readme/README.md

@@ -5,3 +5,3 @@ # doc-snippets
 
-## Installation
+# Installation
 
@@ -20,5 +20,5 @@ Using NPM:
 
-## Usage
+# Usage
 
-### Marking and injecting
+## Marking and injecting
 
@@ -33,5 +33,5 @@ `doc-snippets` extracts and injects snippets by using tokens:
 
-### Configuration
+## Configuration
 
-`doc-snippets` is, by defaut, configured using a JSON file that contains a `doc-snippets` object. By default, this file is `package.json`.
+The `doc-snippets` CLI is configured using a JSON file that contains a `doc-snippets` object. By default, this file is `package.json`.
 
@@ -52,4 +52,14 @@ The configuration object has the following structure (and default values):
   },
-  "startToken": "$start: ",
-  "endToken": "$end",
+  "startTokens": [
+    {
+      "pattern": "$start: ",
+      "inline": false
+    }
+  ],
+  "endTokens": [
+    {
+      "pattern": "$end",
+      "inline": false
+    }
+  ],
   "injectToken": "$snippet: ",
@@ -60,3 +70,3 @@ "outputDir": "./docs"
 
-#### `extract` and `inject`
+### `extract` and `inject`
 
@@ -74,2 +84,3 @@ The `extract` and `inject` objects both have the same structure:
 **Example `extract` object:**
+
 ```JSON
@@ -82,5 +93,7 @@ "extract": {
 ```
+
 In this example, `extract` will perform its search within the `./src` directory.
 
 It will include:
+
 - `./src/sample.sql`
@@ -90,2 +103,3 @@ - All files within `./src` and its subdirectories ending in `.js` and `.ts`
 It will ignore:
+
 - All directories and subdirectories of any `node_modules` directory found within `./src` and its subdirectories.
@@ -95,7 +109,100 @@
 
-#### `outputDir`
+### Extraction tokens (`startTokens` and `endTokens`)
 
+Extraction tokens mark the beginning and end of our snippets.
+
+The tokens have two properties:
+- `pattern` - the **exact string** that denotes the token
+- `inline` - defines whether the token is a **regular** or **inline** extraction token
+
+#### Regular and inline extraction tokens
+
+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.
+
+Let's take a look at an example:
+
+```typescript
+// $start: hello-snippet we can add comments here
+const greeting = "Hello World!";
+console.log(greeting);
+// $end
+```
+
+Using the default configuration, this code will yield a snippet called `hello-snippet` with the following contents:
+```
+const greeting = "Hello World!";
+console.log(greeting);
+```
+
+To allow for more flexible snippet extraction, we can use **inline** extraction tokens.
+
+For example, let's configure our extraction tokens as follows:
+
+```json
+{
+  //...
+  "startTokens": [
+    {
+      "pattern": "/* $start: {SNIPPET_NAME} */",
+      "inline": true
+    }
+  ],
+  "endTokens": [
+    {
+      "pattern": "/* $end */",
+      "inline": true
+    }
+  ]
+}
+```
+
+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.
+
+In addition, let's assume that we have a file with the following code:
+
+```typescript
+const greeting = /* $start: hello-inline-snippet */"Hello World!";
+console.log(greeting);/* $end */
+```
+
+Snippet extraction would now yield a snippet named `hello-inline-snippet` with the following contents:
+```
+"Hello World!";
+console.log(greeting);
+```
+
+Inline extraction tokens can be useful when you need to extract only part of your line.
+
+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.
+
+For reference:
+- When a  **regular start token** is encoutered, snippet extraction starts at the beginning of the next line.
+- When an **inline start token** is encountered, snippet extraction starts immediately after the token ends.
+- When a **regular end token** is encountered, snippet extraction ends at the end of the previous line.
+- When an **inline end token** is encountered, snippet extraction ends at the beginning of the token.
+
+### `injectionToken`
+
+The `injectionToken` is the **exact string** which will be replaced by your snippet during injection. The snippet must follow immediately after the `injectionToken`.
+
+For example, if you have the following `injectionToken`:
+
+```json
+{
+  // Note the space character at the end
+  "injectionToken": "$snippet: "
+}
+```
+
+the following text would be replaced by a snippet called `hello-snippet`:
+
+```md
+$snippet: hello-snippet
+```
+
+### `outputDir`
+
 The `outputDir` is the output directory for the documentation injected with snippets.
 
-### Running `doc-snippets`
+## Running `doc-snippets`
 
@@ -112,7 +219,9 @@ `doc-snippets` comes with a CLI tool which is designed to handle most scenarios.
 
-#### 'combine' command options
+All configuration options can be overridden using `combine`'s command options.
 
+### 'combine' command options
+
 %snippet: combine-options
 
-### In your own code
+## In your own code
 
@@ -127,10 +236,30 @@ If you want to use `doc-snippets` programatically, it offers two exported functions:
   ignore: "./**/node_modules/**",
-  dir: "./src"
-}
+  dir: "./src",
+};
 
 //Returns snippets as `Record<string, string>`.
-const snippets = await extractSnippets(searchOptions, "$start: ", "$end");
+const startTokens = [
+  {
+    pattern: "$start: "
+  },
+  {
+    pattern: "/* $start: {SNIPPET_NAME} */",
+    inline: true
+  }
+];
 
+const endTokens = [
+  {
+    pattern: "$end"
+  },
+  {
+    pattern: "/* $end */",
+    inline: true
+  }
+];
+
+const snippets = await extractSnippets(searchOptions, startTokens, endTokens);
+
 //Injects `snippets` into `./dest/readme.md` replacing all instances of `$snippet: snippet-name` with the appropriate snippet
 await injectSnippetsIntoFile(snippets, "./dest/readme.md", "$snippet: ");
 ```

No alert changes

Improved metrics

Total package byte prevSize

81704

increased by36.86%

Number of package files

69

increased by43.75%

Lines of code

948

increased by36.21%

Number of lines in readme file

268

increased by95.62%

No dependency changes