diff --git a/README.md b/README.md index 2a21221..5cc0e86 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,6 @@ yarn add -D doc-snippets - To inject a snippet: - `"$snippet: snippet-name"` - This gets replaced by the snippet with the given name. -Currently, `doc-snippets` extracts snippets from the following file types: -`.ts`, `.json`, `.yaml`, `.txt`, `.md`, `.graphql`, and `.cue`. - Snippets are injected only into `.md` files. ### Running `doc-snippets` @@ -45,6 +42,10 @@ doc-snippets combine ./snippets ./src/docs ./docs #### Options - `-i, --ignore ` - Ignore listed paths. Paths should be formatted according to the [gitignore spec 2.22.1](https://git-scm.com/docs/gitignore/2.22.1) + - By default, only `node_modules` is ignored. + +- `-e, --exts ` - Parse files with listed extensions + - By default, files with the following extensions are parsed: `.ts`, `.json`, `.yaml`, `.txt`, `.md`, `.graphql`, and `.cue` ### In your own code diff --git a/package.json b/package.json index 4f31011..52decb5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "doc-snippets", - "version": "0.2.0", + "version": "0.3.0", "description": "Extract and inject snippets from code into markdown files", "author": { "name": "Pileks", diff --git a/src/cli.ts b/src/cli.ts index a7df7cb..7f15fc1 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -14,14 +14,21 @@ export const run = async (argv: string[]): Promise => { .argument("", "The documentation directory") .argument("", "The output directory") .option("-i, --ignore ", "Ignore specified paths") + .option("-e, --exts ", "Extensions to parse") .action( async ( snippetsDir: string, docsDir: string, outputDir: string, - { ignore } + { ignore, exts } ) => { - await combineDocsAndSnippets(snippetsDir, docsDir, outputDir, ignore); + await combineDocsAndSnippets( + snippetsDir, + docsDir, + outputDir, + exts, + ignore + ); } ); diff --git a/src/lib/combine.ts b/src/lib/combine.ts index c0c5450..34cc6c1 100644 --- a/src/lib/combine.ts +++ b/src/lib/combine.ts @@ -8,6 +8,7 @@ export async function combineDocsAndSnippets( snippetsDir: string, docsDir: string, outputDir: string, + parseExts?: string[], ignorePaths?: string[] ): Promise { console.log(`- Copy ${docsDir} to ${outputDir}`); @@ -18,7 +19,10 @@ export async function combineDocsAndSnippets( fse.copySync(docsDir, outputDir, { overwrite: true }); console.log("- Extract Snippets"); - const snippets = await extractSnippets(snippetsDir, ignorePaths); + const snippets = await extractSnippets(snippetsDir, { + parseExts, + ignorePaths, + }); console.log("- Inject Snippets"); await injectSnippets(snippets, outputDir); diff --git a/src/lib/defaults/defaultIgnorePaths.ts b/src/lib/defaults/defaultIgnorePaths.ts new file mode 100644 index 0000000..8d3a36e --- /dev/null +++ b/src/lib/defaults/defaultIgnorePaths.ts @@ -0,0 +1 @@ +export const defaultIgnorePaths = ["node_modules"]; diff --git a/src/lib/defaults/defaultParseExts.ts b/src/lib/defaults/defaultParseExts.ts new file mode 100644 index 0000000..e139fa1 --- /dev/null +++ b/src/lib/defaults/defaultParseExts.ts @@ -0,0 +1,9 @@ +export const defaultParseExts = [ + ".ts", + ".json", + ".yaml", + ".txt", + ".md", + ".graphql", + ".cue", +]; diff --git a/src/lib/defaults/index.ts b/src/lib/defaults/index.ts new file mode 100644 index 0000000..d414fa7 --- /dev/null +++ b/src/lib/defaults/index.ts @@ -0,0 +1,2 @@ +export * from "./defaultIgnorePaths"; +export * from "./defaultParseExts"; diff --git a/src/lib/extract.ts b/src/lib/extract.ts index 017cd14..a2ba69e 100644 --- a/src/lib/extract.ts +++ b/src/lib/extract.ts @@ -1,25 +1,43 @@ +import { defaultParseExts, defaultIgnorePaths } from "./defaults"; + import path from "path"; import fs from "fs"; import ignore, { Ignore } from "ignore"; +/** + * @typedef ExtractSnippetsOptions + * @type {object} + * @property {string[]} [parseExts] A list of file extensions which will be parsed for Snippets + * @property {string[]} [ignorePaths] A list of paths in `gitignore` format which will be ignored when parsing + */ +type ExtractSnippetsOptions = { + parseExts?: string[]; + ignorePaths?: string[]; +}; + /** * Extract snippets from all files within a directory - * @param {string} dir - The directory to search and extract snippets from - * @returns + * @param {string} dir The directory to search and extract snippets from + * @param {ExtractSnippetsOptions} options Extraction options + * @returns {Record} A Record containing all extracted Snippets */ export async function extractSnippets( dir: string, - ignorePaths?: string[] + options?: ExtractSnippetsOptions ): Promise> { const snippets: Record = {}; const ignoreInstance = ignore(); - if (ignorePaths) { - ignoreInstance.add(ignorePaths); + if (options?.ignorePaths) { + ignoreInstance.add(options.ignorePaths); + } else { + ignoreInstance.add(defaultIgnorePaths); } - await searchAndExtractSnippetsFromDir(snippets, dir, ignoreInstance); + const exts = options?.parseExts ?? defaultParseExts; + + await searchAndExtractSnippetsFromDir(snippets, dir, exts, ignoreInstance); return snippets; } @@ -27,16 +45,11 @@ export async function extractSnippets( async function searchAndExtractSnippetsFromDir( snippets: Record, dir: string, + exts: string[], ignoreInstance: Ignore ) { const dirents = fs.readdirSync(dir, { withFileTypes: true }); - // Only search specific types of files - const exts = [".ts", ".json", ".yaml", ".txt", ".md", ".graphql", ".cue"]; - - // Ignore specific directories - const filter = ["node_modules"]; - const match = (str: string, tests: string[]) => { for (const test of tests) { if (str.indexOf(test) > -1) { @@ -55,10 +68,11 @@ async function searchAndExtractSnippetsFromDir( if (dirent.isFile() && match(dirent.name, exts)) { await extractSnippetsFromFile(snippets, direntPath); - } else if (dirent.isDirectory() && !match(dirent.name, filter)) { + } else if (dirent.isDirectory()) { await searchAndExtractSnippetsFromDir( snippets, direntPath, + exts, ignoreInstance ); }