@wixc3/docs - npm Package Compare versions

Comparing version 3.0.1 to 3.0.2

dist/cjs/build-docs.d.ts

@@ -1,6 +0,7 @@
-import { Macro } from './macros';
+import type { Macros } from './macros.types';
+export type { Macros };
 /**
  * Build docs markdown
  */
-export declare function buildDocs(conf: string, skipAnalyze?: boolean, macros?: Record<string, Macro>): void;
+export declare function buildDocs(conf: string, skipAnalyze?: boolean, macros?: Macros): void;
 //# sourceMappingURL=build-docs.d.ts.map

dist/cjs/build-docs.js

 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -9,6 +32,6 @@ exports.buildDocs = void 0;
 const process_macros_1 = require("./process-macros");
-const macros_1 = require("./macros");
 const MarkdownDocumenter_1 = require("@microsoft/api-documenter/lib/documenters/MarkdownDocumenter");
 const api_extractor_model_1 = require("@microsoft/api-extractor-model");
 const path_1 = require("path");
+const builtinMacros = __importStar(require("./macros"));
 /**
@@ -28,5 +51,5 @@ * Build docs markdown
         const typescriptCompilerFolder = (0, path_1.join)((0, path_1.dirname)(require.resolve('typescript')), '..');
-        (0, common_1.listPackages)(config).forEach((_package) => {
+        const analyzeFile = (path) => {
             try {
-                api_extractor_1.Extractor.loadConfigAndInvoke((0, common_1._packages)(config, _package, 'api-extractor.json'), {
+                api_extractor_1.Extractor.loadConfigAndInvoke(path, {
                     // at the time of writing this argument is ignored :(
@@ -37,6 +60,13 @@ typescriptCompilerFolder,
             catch (err) {
-                throw new Error(`Error analyzing ${(0, common_1._packages)(config, _package, 'api-extractor.json')}:
+                throw new Error(`Error analyzing ${path}:
                 ${err.message}`);
             }
-        });
+        };
+        (0, common_1.listPackages)(config).forEach((_package) => analyzeFile((0, common_1._packages)(config, _package, 'api-extractor.json')));
+        if ((0, common_1.isWixDocs)(config)) {
+            analyzeFile((0, common_1._packages)(config, 'docs', 'macros.api-extractor.json'));
+            const macrosDocsPath = (0, common_1._temp)(config, 'built-in-macros.api.json');
+            const macrosDocs = (0, fs_1.readFileSync)(macrosDocsPath, 'utf8');
+            (0, fs_1.writeFileSync)(macrosDocsPath, macrosDocs.replaceAll('@wixc3/docs', '@wixc3/docs-macros'));
+        }
         console.timeEnd('Analyzing APIs...');
@@ -47,3 +77,2 @@ }
     console.time('Building markdown files');
-    // execSync(`yarn api-documenter markdown -i ${_temp(config)} -o ${_docs(config)}`);
     const model = new api_extractor_model_1.ApiModel();
@@ -53,6 +82,9 @@ (0, common_1.listPackages)(config).forEach((path) => {
     });
+    if ((0, common_1.isWixDocs)(config)) {
+        model.loadPackage((0, common_1._temp)(config, 'built-in-macros.api.json'));
+    }
     const dm = new MarkdownDocumenter_1.MarkdownDocumenter({
         apiModel: model,
         outputFolder: (0, common_1._docs)(config),
-        documenterConfig: undefined
+        documenterConfig: undefined,
     });
@@ -67,3 +99,3 @@ dm.generateFiles();
         modifier: (0, process_macros_1.createHeadersModifier)(config),
-        macros: { ...macros_1.macros, ...macros }
+        macros: { ...builtinMacros, ...macros },
     };
@@ -70,0 +102,0 @@ (0, fs_1.readdirSync)((0, common_1._docs)(config), { withFileTypes: true })

dist/cjs/common.d.ts

 import { Nullable } from '@wixc3/common';
-import type { Macro } from './macros';
+import type { Macro } from './macros.types';
 export declare function listPackages({ base, packages }: UserConfig): string[];
@@ -41,2 +41,3 @@ export declare const stripName: (name: string) => string;
 export declare const _temp: ({ base, temp }: UserConfig, ...path: string[]) => string;
+export declare function isWixDocs(config: Config): boolean;
 //# sourceMappingURL=common.d.ts.map

dist/cjs/common.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._temp = exports._config = exports._docs = exports._packages = exports.writeConfig = exports.loadConfig = exports.getRepo = exports.execMacro = exports.parseMacro = exports.stripName = exports.listPackages = void 0;
+exports.isWixDocs = exports._temp = exports._config = exports._docs = exports._packages = exports.writeConfig = exports.loadConfig = exports.getRepo = exports.execMacro = exports.parseMacro = exports.stripName = exports.listPackages = void 0;
 const common_1 = require("@wixc3/common");
@@ -28,3 +28,3 @@ const child_process_1 = require("child_process");
 const execMacro = (data, replace) => {
-    for (const match of data.matchAll(/(?<!\*)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
+    for (const match of data.matchAll(/(?<!`|<code>)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
         const { all, macro, args } = parseMacro(match);
@@ -90,2 +90,6 @@ const v = replace[macro];
 exports._temp = _temp;
+function isWixDocs(config) {
+    return config.git.github === 'https://github.com/wixplosives/core3-utils';
+}
+exports.isWixDocs = isWixDocs;
 //# sourceMappingURL=common.js.map

dist/cjs/index.d.ts

@@ -30,8 +30,6 @@ /**
  * There are many awesome macros you can use in your TDDocs.
- * Using macros look like this *[[[macro and args]]]
+ * Using macros look like this `[[[macro and args]]]`
  *
- * Available macros are:
+ * [[[include ./docs-macros.md]]]
  *
- * [[[listMacros]]]
- *
  */
@@ -38,0 +36,0 @@ export * from './build-docs';

dist/cjs/index.js

@@ -47,8 +47,6 @@ "use strict";
  * There are many awesome macros you can use in your TDDocs.
- * Using macros look like this *[[[macro and args]]]
+ * Using macros look like this `[[[macro and args]]]`
  *
- * Available macros are:
+ * [[[include ./docs-macros.md]]]
  *
- * [[[listMacros]]]
- *
  */
@@ -55,0 +53,0 @@ __exportStar(require("./build-docs"), exports);

dist/cjs/init.d.ts

 import { UserConfig } from './common';
+export { UserConfig };
 /**
@@ -3,0 +4,0 @@ * Initialize docs pre-requisites:

dist/cjs/init.js

@@ -31,3 +31,3 @@ "use strict";
             temp: (0, common_1._temp)(config),
-            confPath: (0, common_1._config)(config)
+            confPath: (0, common_1._config)(config),
         });
@@ -34,0 +34,0 @@ writeConfFile(resource, mod);

dist/cjs/macros.d.ts

@@ -1,22 +0,114 @@
-import { ProcessingConfig } from './common';
-export declare type Macro = (config: ProcessingConfig, filename: string, ...args: string[]) => string;
-export declare class MacroError extends Error {
-    config: ProcessingConfig;
-    file: string;
-    constructor(config: ProcessingConfig, file: string, fn: Macro, _message: string);
-}
-export declare const macros: {
-    rootPackageName: Macro;
-    packageNameUrl: Macro;
-    packageName: Macro;
-    unscopedPackageName: Macro;
-    github: Macro;
-    githubPages: Macro;
-    gitRepo: Macro;
-    include: Macro;
-    listMacros: Macro;
-    npmBadge: Macro;
-    githubBuildStatus: Macro;
-    h: Macro;
-};
+import type { Macro } from './macros.types';
+/**
+ *
+ * Project's root package name
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[rootPackageName]]]`
+ */
+export declare const rootPackageName: Macro;
+/**
+ *
+ * Project's current package name
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageName]]]`
+ *
+ * Will be replace by the full package name, i.e `@wixc3/docs`
+ */
+export declare const packageName: Macro;
+/**
+ *
+ * Project's current package name, unscoped
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ * *[[[unscopedPackageName]]]
+ *
+ * Will be replace by the full package name, i.e `bla` for `@wixc3/bla`
+ */
+export declare const unscopedPackageName: Macro;
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageNameUrl]]]`
+ *
+ * This is useful for generating links and badges
+ */
+export declare const packageNameUrl: Macro;
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[gitRepo field?]]]`
+ *
+ * where field can be: host | org | repo | pages | github
+ */
+export declare const gitRepo: Macro;
+/**
+ *
+ * A link to the project's github pages
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubPages uri? caption?]]]`
+ *
+ * where uri can be an inner page
+ *
+ * if caption is provided a markdown link will be created, otherwise the raw root URL will replace the macro
+ *
+ */
+export declare const githubPages: Macro;
+/**
+ *
+ * A github build status badge
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubBuildStatus]]]`
+ */
+export declare const githubBuildStatus: Macro;
+export declare const npmBadge: Macro;
+/**
+ *
+ * A link to the package on github
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[github caption?]]]`
+ */
+export declare const github: Macro;
+/**
+ *
+ * Include another markdown file (that may also have macros)
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[include path]]]`
+ */
+export declare const include: Macro;
+/**
+ *
+ * Heading - since ts-docs to not natively allow for markdown
+ * formatting, this macro is used to create a #, ##, ## etc
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[h level title]]]`
+ */
+export declare const h: Macro;
+/**
+ * Lists all the available macros
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[listMacros]]]`
+ */
+export declare const listMacros: Macro;
 //# sourceMappingURL=macros.d.ts.map

dist/cjs/macros.js

@@ -6,3 +6,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.macros = exports.MacroError = void 0;
+exports.listMacros = exports.h = exports.include = exports.github = exports.npmBadge = exports.githubBuildStatus = exports.githubPages = exports.gitRepo = exports.packageNameUrl = exports.unscopedPackageName = exports.packageName = exports.rootPackageName = void 0;
 const fs_utils_1 = require("@wixc3/fs-utils");
@@ -13,21 +13,62 @@ const node_1 = __importDefault(require("@file-services/node"));
 const common_2 = require("@wixc3/common");
-class MacroError extends Error {
-    config;
-    file;
-    constructor(config, file, fn, _message) {
-        super(`Macro error in ${(0, common_1._docs)(config, file)} - [[[${fn.name}]]]:
-    ${_message}`);
-        this.config = config;
-        this.file = file;
-    }
-}
-exports.MacroError = MacroError;
+/**
+ *
+ * Project's root package name
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[rootPackageName]]]`
+ */
 const rootPackageName = ({ base }) => (0, fs_utils_1.readPackageJson)(base, node_1.default).name || '';
-const packageName = (config, name) => (0, fs_utils_1.readPackageJson)((0, common_1._packages)(config, (0, common_1.stripName)(name)), node_1.default).name?.toString() || '';
-const unscopedPackageName = (config, name) => exports.macros.packageName(config, name).replace(/.*\//, '');
-const packageNameUrl = (config, name) => exports.macros
-    .packageName(config, name)
+exports.rootPackageName = rootPackageName;
+/**
+ *
+ * Project's current package name
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageName]]]`
+ *
+ * Will be replace by the full package name, i.e `@wixc3/docs`
+ */
+const packageName = (config, name) => config.git.github === 'https://github.com/wixplosives/core3-utils' && name.startsWith('docs-macros')
+    ? '@wixc3/docs'
+    : (0, fs_utils_1.readPackageJson)((0, common_1._packages)(config, (0, common_1.stripName)(name)), node_1.default).name?.toString() || '';
+exports.packageName = packageName;
+/**
+ *
+ * Project's current package name, unscoped
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ * *[[[unscopedPackageName]]]
+ *
+ * Will be replace by the full package name, i.e `bla` for `@wixc3/bla`
+ */
+const unscopedPackageName = (config, name) => (0, exports.packageName)(config, name).replace(/.*\//, '');
+exports.unscopedPackageName = unscopedPackageName;
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageNameUrl]]]`
+ *
+ * This is useful for generating links and badges
+ */
+const packageNameUrl = (config, name) => (0, exports.packageName)(config, name)
     .split('@')
     .map((i) => encodeURIComponent(i))
     .join('@');
+exports.packageNameUrl = packageNameUrl;
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[gitRepo field?]]]`
+ *
+ * where field can be: host | org | repo | pages | github
+ */
 const gitRepo = (config, name, field = 'github') => {
@@ -38,46 +79,91 @@ const { git } = config;
     }
-    throw new MacroError(config, name, gitRepo, `Invalid argument "${field}" options are:
+    throw new Error(`Invalid argument "${field}" options are:
         ${Object.keys(git).join(', ')}`);
 };
-const githubPages = ({ git: { pages } }, _name = '', uri = '', caption = '') => {
+exports.gitRepo = gitRepo;
+/**
+ *
+ * A link to the project's github pages
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubPages uri? caption?]]]`
+ *
+ * where uri can be an inner page
+ *
+ * if caption is provided a markdown link will be created, otherwise the raw root URL will replace the macro
+ *
+ */
+const githubPages = ({ git: { pages } }, _name, uri = '', caption = '') => {
     return caption === '' ? pages : `[${caption}](${pages}/${uri})`;
 };
+exports.githubPages = githubPages;
+/**
+ *
+ * A github build status badge
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubBuildStatus]]]`
+ */
 const githubBuildStatus = ({ git: { github } }) => `[![Build Status](${github}/workflows/tests/badge.svg)](${github}/actions)`;
+exports.githubBuildStatus = githubBuildStatus;
 const npmBadge = (config, name) => {
-    const pkg = packageNameUrl(config, name);
+    const pkg = (0, exports.packageNameUrl)(config, name);
     return `[![npm version](https://badge.fury.io/js/${pkg}.svg)](https://badge.fury.io/js/${pkg})`;
 };
-const github = (config, name) => `[${packageName(config, name)} on Github](${config.git.github}/tree/master/${config.packages}/${unscopedPackageName(config, name)})`;
+exports.npmBadge = npmBadge;
+/**
+ *
+ * A link to the package on github
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[github caption?]]]`
+ */
+const github = (config, name, caption) => {
+    caption = caption || `${(0, exports.packageName)(config, name)} on Github`;
+    return `[${caption}](${config.git.github}/tree/master/${config.packages}/${(0, exports.unscopedPackageName)(config, name)})`;
+};
+exports.github = github;
+/**
+ *
+ * Include another markdown file (that may also have macros)
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[include path]]]`
+ */
 const include = (config, name, target = '') => {
     if (!target) {
-        throw new MacroError(config, name, include, 'Missing target argument');
+        throw new Error('Missing target argument');
     }
     return (0, process_macros_1.processMacros)(config, target, name);
 };
-const h = (_, __, level, ...text) => `${(0, common_2.repeat)('#', parseInt(level))} ${text.join(' ')}\n`;
-const listMacros = () => {
-    return Object.keys(exports.macros)
+exports.include = include;
+/**
+ *
+ * Heading - since ts-docs to not natively allow for markdown
+ * formatting, this macro is used to create a #, ##, ## etc
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[h level title]]]`
+ */
+const h = (_, __, level, ...title) => `${(0, common_2.repeat)('#', parseInt(level))} ${title.join(' ')}\n`;
+exports.h = h;
+/**
+ * Lists all the available macros
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[listMacros]]]`
+ */
+const listMacros = ({ macros }) => {
+    return Object.keys(macros)
         .sort()
-        .map((name) => ` - *\\[\\[\\[${name}\\]\\]\\]`)
+        .map((name) => ` - [*\\[\\[\\[${name}\\]\\]\\]](./docs-macros.${name}.md)`)
         .join('\n');
 };
-exports.macros = {
-    // Package name
-    rootPackageName,
-    packageNameUrl,
-    packageName,
-    unscopedPackageName,
-    // git & github
-    github,
-    githubPages,
-    gitRepo,
-    // utility
-    include,
-    listMacros,
-    // badges
-    npmBadge,
-    githubBuildStatus,
-    // Formatting
-    h,
-};
+exports.listMacros = listMacros;
 //# sourceMappingURL=macros.js.map

dist/cjs/process-macros.js

@@ -8,5 +8,6 @@ "use strict";
 const common_2 = require("@wixc3/common");
+const macros_types_1 = require("./macros.types");
 const createHeadersModifier = (config) => {
     const headers = (0, path_1.relative)(config.docs, config.conf);
-    return (name, content) => {
+    return function addHeaders(name, content) {
         let file = 'item';
@@ -29,4 +30,11 @@ if (name === 'index.md') {
     const mod = config.modifier && !filenameOverride ? config.modifier(filename, source) : source;
-    const macrosCtx = (0, common_2.mapValues)(config.macros, (m) => (...args) => m(config, filenameOverride || filename, ...args));
-    const processed = (0, common_1.execMacro)(mod, macrosCtx).replaceAll(/\*(\\\[){3}/g, (0, common_2.repeat)('\\[', 3));
+    const macrosCtx = (0, common_2.mapValues)(config.macros, (m) => (...args) => {
+        try {
+            return m(config, filenameOverride || filename, ...args);
+        }
+        catch (err) {
+            throw new macros_types_1.MacroError(config, filenameOverride || filename, m, args, err.message);
+        }
+    });
+    const processed = (0, common_1.execMacro)(mod, macrosCtx);
     if (source !== processed) {
@@ -33,0 +41,0 @@ (0, fs_1.writeFileSync)((0, common_1._docs)(config, filenameOverride || filename), processed, { encoding: 'utf8' });

dist/esm/build-docs.d.ts

@@ -1,6 +0,7 @@
-import { Macro } from './macros';
+import type { Macros } from './macros.types';
+export type { Macros };
 /**
  * Build docs markdown
  */
-export declare function buildDocs(conf: string, skipAnalyze?: boolean, macros?: Record<string, Macro>): void;
+export declare function buildDocs(conf: string, skipAnalyze?: boolean, macros?: Macros): void;
 //# sourceMappingURL=build-docs.d.ts.map

dist/esm/build-docs.js

 /* eslint-disable no-console */
 import { Extractor } from '@microsoft/api-extractor';
-import { readdirSync } from 'fs';
-import { listPackages, loadConfig, _docs, _packages, _temp } from './common';
+import { readdirSync, readFileSync, writeFileSync } from 'fs';
+import { isWixDocs, listPackages, loadConfig, _docs, _packages, _temp } from './common';
 import { createHeadersModifier, processMacros } from './process-macros';
-import { macros as builtinMacros } from './macros';
 import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter';
 import { ApiModel } from '@microsoft/api-extractor-model';
 import { dirname, join } from 'path';
+import * as builtinMacros from './macros';
 /**
@@ -23,5 +23,5 @@ * Build docs markdown
         const typescriptCompilerFolder = join(dirname(require.resolve('typescript')), '..');
-        listPackages(config).forEach((_package) => {
+        const analyzeFile = (path) => {
             try {
-                Extractor.loadConfigAndInvoke(_packages(config, _package, 'api-extractor.json'), {
+                Extractor.loadConfigAndInvoke(path, {
                     // at the time of writing this argument is ignored :(
@@ -32,6 +32,13 @@ typescriptCompilerFolder,
             catch (err) {
-                throw new Error(`Error analyzing ${_packages(config, _package, 'api-extractor.json')}:
+                throw new Error(`Error analyzing ${path}:
                 ${err.message}`);
             }
-        });
+        };
+        listPackages(config).forEach((_package) => analyzeFile(_packages(config, _package, 'api-extractor.json')));
+        if (isWixDocs(config)) {
+            analyzeFile(_packages(config, 'docs', 'macros.api-extractor.json'));
+            const macrosDocsPath = _temp(config, 'built-in-macros.api.json');
+            const macrosDocs = readFileSync(macrosDocsPath, 'utf8');
+            writeFileSync(macrosDocsPath, macrosDocs.replaceAll('@wixc3/docs', '@wixc3/docs-macros'));
+        }
         console.timeEnd('Analyzing APIs...');
@@ -42,3 +49,2 @@ }
     console.time('Building markdown files');
-    // execSync(`yarn api-documenter markdown -i ${_temp(config)} -o ${_docs(config)}`);
     const model = new ApiModel();
@@ -48,6 +54,9 @@ listPackages(config).forEach((path) => {
     });
+    if (isWixDocs(config)) {
+        model.loadPackage(_temp(config, 'built-in-macros.api.json'));
+    }
     const dm = new MarkdownDocumenter({
         apiModel: model,
         outputFolder: _docs(config),
-        documenterConfig: undefined
+        documenterConfig: undefined,
     });
@@ -62,3 +71,3 @@ dm.generateFiles();
         modifier: createHeadersModifier(config),
-        macros: { ...builtinMacros, ...macros }
+        macros: { ...builtinMacros, ...macros },
     };
@@ -65,0 +74,0 @@ readdirSync(_docs(config), { withFileTypes: true })

dist/esm/common.d.ts

 import { Nullable } from '@wixc3/common';
-import type { Macro } from './macros';
+import type { Macro } from './macros.types';
 export declare function listPackages({ base, packages }: UserConfig): string[];
@@ -41,2 +41,3 @@ export declare const stripName: (name: string) => string;
 export declare const _temp: ({ base, temp }: UserConfig, ...path: string[]) => string;
+export declare function isWixDocs(config: Config): boolean;
 //# sourceMappingURL=common.d.ts.map

dist/esm/common.js

@@ -22,3 +22,3 @@ import { first } from '@wixc3/common';
 export const execMacro = (data, replace) => {
-    for (const match of data.matchAll(/(?<!\*)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
+    for (const match of data.matchAll(/(?<!`|<code>)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
         const { all, macro, args } = parseMacro(match);
@@ -76,2 +76,5 @@ const v = replace[macro];
 export const _temp = ({ base, temp }, ...path) => join(base, temp, ...path);
+export function isWixDocs(config) {
+    return config.git.github === 'https://github.com/wixplosives/core3-utils';
+}
 //# sourceMappingURL=common.js.map

dist/esm/index.d.ts

@@ -30,8 +30,6 @@ /**
  * There are many awesome macros you can use in your TDDocs.
- * Using macros look like this *[[[macro and args]]]
+ * Using macros look like this `[[[macro and args]]]`
  *
- * Available macros are:
+ * [[[include ./docs-macros.md]]]
  *
- * [[[listMacros]]]
- *
  */
@@ -38,0 +36,0 @@ export * from './build-docs';

dist/esm/index.js

@@ -30,8 +30,6 @@ /**
  * There are many awesome macros you can use in your TDDocs.
- * Using macros look like this *[[[macro and args]]]
+ * Using macros look like this `[[[macro and args]]]`
  *
- * Available macros are:
+ * [[[include ./docs-macros.md]]]
  *
- * [[[listMacros]]]
- *
  */
@@ -38,0 +36,0 @@ export * from './build-docs';

dist/esm/init.d.ts

 import { UserConfig } from './common';
+export { UserConfig };
 /**
@@ -3,0 +4,0 @@ * Initialize docs pre-requisites:

dist/esm/init.js

@@ -28,3 +28,3 @@ import { join, relative } from 'path';
             temp: _temp(config),
-            confPath: _config(config)
+            confPath: _config(config),
         });
@@ -31,0 +31,0 @@ writeConfFile(resource, mod);

dist/esm/macros.d.ts

@@ -1,22 +0,114 @@
-import { ProcessingConfig } from './common';
-export declare type Macro = (config: ProcessingConfig, filename: string, ...args: string[]) => string;
-export declare class MacroError extends Error {
-    config: ProcessingConfig;
-    file: string;
-    constructor(config: ProcessingConfig, file: string, fn: Macro, _message: string);
-}
-export declare const macros: {
-    rootPackageName: Macro;
-    packageNameUrl: Macro;
-    packageName: Macro;
-    unscopedPackageName: Macro;
-    github: Macro;
-    githubPages: Macro;
-    gitRepo: Macro;
-    include: Macro;
-    listMacros: Macro;
-    npmBadge: Macro;
-    githubBuildStatus: Macro;
-    h: Macro;
-};
+import type { Macro } from './macros.types';
+/**
+ *
+ * Project's root package name
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[rootPackageName]]]`
+ */
+export declare const rootPackageName: Macro;
+/**
+ *
+ * Project's current package name
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageName]]]`
+ *
+ * Will be replace by the full package name, i.e `@wixc3/docs`
+ */
+export declare const packageName: Macro;
+/**
+ *
+ * Project's current package name, unscoped
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ * *[[[unscopedPackageName]]]
+ *
+ * Will be replace by the full package name, i.e `bla` for `@wixc3/bla`
+ */
+export declare const unscopedPackageName: Macro;
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageNameUrl]]]`
+ *
+ * This is useful for generating links and badges
+ */
+export declare const packageNameUrl: Macro;
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[gitRepo field?]]]`
+ *
+ * where field can be: host | org | repo | pages | github
+ */
+export declare const gitRepo: Macro;
+/**
+ *
+ * A link to the project's github pages
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubPages uri? caption?]]]`
+ *
+ * where uri can be an inner page
+ *
+ * if caption is provided a markdown link will be created, otherwise the raw root URL will replace the macro
+ *
+ */
+export declare const githubPages: Macro;
+/**
+ *
+ * A github build status badge
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubBuildStatus]]]`
+ */
+export declare const githubBuildStatus: Macro;
+export declare const npmBadge: Macro;
+/**
+ *
+ * A link to the package on github
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[github caption?]]]`
+ */
+export declare const github: Macro;
+/**
+ *
+ * Include another markdown file (that may also have macros)
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[include path]]]`
+ */
+export declare const include: Macro;
+/**
+ *
+ * Heading - since ts-docs to not natively allow for markdown
+ * formatting, this macro is used to create a #, ##, ## etc
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[h level title]]]`
+ */
+export declare const h: Macro;
+/**
+ * Lists all the available macros
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[listMacros]]]`
+ */
+export declare const listMacros: Macro;
 //# sourceMappingURL=macros.d.ts.map

dist/esm/macros.js

 import { readPackageJson } from '@wixc3/fs-utils';
 import nodeFs from '@file-services/node';
-import { stripName, _docs, _packages } from './common';
+import { stripName, _packages } from './common';
 import { processMacros } from './process-macros';
 import { repeat } from '@wixc3/common';
-export class MacroError extends Error {
-    config;
-    file;
-    constructor(config, file, fn, _message) {
-        super(`Macro error in ${_docs(config, file)} - [[[${fn.name}]]]:
-    ${_message}`);
-        this.config = config;
-        this.file = file;
-    }
-}
-const rootPackageName = ({ base }) => readPackageJson(base, nodeFs).name || '';
-const packageName = (config, name) => readPackageJson(_packages(config, stripName(name)), nodeFs).name?.toString() || '';
-const unscopedPackageName = (config, name) => macros.packageName(config, name).replace(/.*\//, '');
-const packageNameUrl = (config, name) => macros
-    .packageName(config, name)
+/**
+ *
+ * Project's root package name
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[rootPackageName]]]`
+ */
+export const rootPackageName = ({ base }) => readPackageJson(base, nodeFs).name || '';
+/**
+ *
+ * Project's current package name
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageName]]]`
+ *
+ * Will be replace by the full package name, i.e `@wixc3/docs`
+ */
+export const packageName = (config, name) => config.git.github === 'https://github.com/wixplosives/core3-utils' && name.startsWith('docs-macros')
+    ? '@wixc3/docs'
+    : readPackageJson(_packages(config, stripName(name)), nodeFs).name?.toString() || '';
+/**
+ *
+ * Project's current package name, unscoped
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ * *[[[unscopedPackageName]]]
+ *
+ * Will be replace by the full package name, i.e `bla` for `@wixc3/bla`
+ */
+export const unscopedPackageName = (config, name) => packageName(config, name).replace(/.*\//, '');
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageNameUrl]]]`
+ *
+ * This is useful for generating links and badges
+ */
+export const packageNameUrl = (config, name) => packageName(config, name)
     .split('@')
     .map((i) => encodeURIComponent(i))
     .join('@');
-const gitRepo = (config, name, field = 'github') => {
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[gitRepo field?]]]`
+ *
+ * where field can be: host | org | repo | pages | github
+ */
+export const gitRepo = (config, name, field = 'github') => {
     const { git } = config;
@@ -29,46 +67,83 @@ if (field in git) {
     }
-    throw new MacroError(config, name, gitRepo, `Invalid argument "${field}" options are:
+    throw new Error(`Invalid argument "${field}" options are:
         ${Object.keys(git).join(', ')}`);
 };
-const githubPages = ({ git: { pages } }, _name = '', uri = '', caption = '') => {
+/**
+ *
+ * A link to the project's github pages
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubPages uri? caption?]]]`
+ *
+ * where uri can be an inner page
+ *
+ * if caption is provided a markdown link will be created, otherwise the raw root URL will replace the macro
+ *
+ */
+export const githubPages = ({ git: { pages } }, _name, uri = '', caption = '') => {
     return caption === '' ? pages : `[${caption}](${pages}/${uri})`;
 };
-const githubBuildStatus = ({ git: { github } }) => `[![Build Status](${github}/workflows/tests/badge.svg)](${github}/actions)`;
-const npmBadge = (config, name) => {
+/**
+ *
+ * A github build status badge
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubBuildStatus]]]`
+ */
+export const githubBuildStatus = ({ git: { github } }) => `[![Build Status](${github}/workflows/tests/badge.svg)](${github}/actions)`;
+export const npmBadge = (config, name) => {
     const pkg = packageNameUrl(config, name);
     return `[![npm version](https://badge.fury.io/js/${pkg}.svg)](https://badge.fury.io/js/${pkg})`;
 };
-const github = (config, name) => `[${packageName(config, name)} on Github](${config.git.github}/tree/master/${config.packages}/${unscopedPackageName(config, name)})`;
-const include = (config, name, target = '') => {
+/**
+ *
+ * A link to the package on github
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[github caption?]]]`
+ */
+export const github = (config, name, caption) => {
+    caption = caption || `${packageName(config, name)} on Github`;
+    return `[${caption}](${config.git.github}/tree/master/${config.packages}/${unscopedPackageName(config, name)})`;
+};
+/**
+ *
+ * Include another markdown file (that may also have macros)
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[include path]]]`
+ */
+export const include = (config, name, target = '') => {
     if (!target) {
-        throw new MacroError(config, name, include, 'Missing target argument');
+        throw new Error('Missing target argument');
     }
     return processMacros(config, target, name);
 };
-const h = (_, __, level, ...text) => `${repeat('#', parseInt(level))} ${text.join(' ')}\n`;
-const listMacros = () => {
+/**
+ *
+ * Heading - since ts-docs to not natively allow for markdown
+ * formatting, this macro is used to create a #, ##, ## etc
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[h level title]]]`
+ */
+export const h = (_, __, level, ...title) => `${repeat('#', parseInt(level))} ${title.join(' ')}\n`;
+/**
+ * Lists all the available macros
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[listMacros]]]`
+ */
+export const listMacros = ({ macros }) => {
     return Object.keys(macros)
         .sort()
-        .map((name) => ` - *\\[\\[\\[${name}\\]\\]\\]`)
+        .map((name) => ` - [*\\[\\[\\[${name}\\]\\]\\]](./docs-macros.${name}.md)`)
         .join('\n');
 };
-export const macros = {
-    // Package name
-    rootPackageName,
-    packageNameUrl,
-    packageName,
-    unscopedPackageName,
-    // git & github
-    github,
-    githubPages,
-    gitRepo,
-    // utility
-    include,
-    listMacros,
-    // badges
-    npmBadge,
-    githubBuildStatus,
-    // Formatting
-    h,
-};
 //# sourceMappingURL=macros.js.map

dist/esm/process-macros.js

 import { readFileSync, writeFileSync } from 'fs';
 import { join, relative } from 'path';
 import { execMacro, _docs } from './common';
-import { mapValues, repeat } from '@wixc3/common';
+import { mapValues } from '@wixc3/common';
+import { MacroError } from './macros.types';
 export const createHeadersModifier = (config) => {
     const headers = relative(config.docs, config.conf);
-    return (name, content) => {
+    return function addHeaders(name, content) {
         let file = 'item';
@@ -24,4 +25,11 @@ if (name === 'index.md') {
     const mod = config.modifier && !filenameOverride ? config.modifier(filename, source) : source;
-    const macrosCtx = mapValues(config.macros, (m) => (...args) => m(config, filenameOverride || filename, ...args));
-    const processed = execMacro(mod, macrosCtx).replaceAll(/\*(\\\[){3}/g, repeat('\\[', 3));
+    const macrosCtx = mapValues(config.macros, (m) => (...args) => {
+        try {
+            return m(config, filenameOverride || filename, ...args);
+        }
+        catch (err) {
+            throw new MacroError(config, filenameOverride || filename, m, args, err.message);
+        }
+    });
+    const processed = execMacro(mod, macrosCtx);
     if (source !== processed) {
@@ -28,0 +36,0 @@ writeFileSync(_docs(config, filenameOverride || filename), processed, { encoding: 'utf8' });

package.json

 {
   "name": "@wixc3/docs",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "API ",
@@ -27,3 +27,5 @@ "main": "dist/cjs/index.js",
     "@microsoft/api-extractor-model": "^7.25.2",
-    "yargs": "^17.6.0"
+    "@wixc3/common": "^3.0.2",
+    "@wixc3/fs-utils": "^3.0.2",
+    "yargs": "^17.6.2"
   },
@@ -30,0 +32,0 @@ "devDependencies": {

resources/api-extractor.base.json

@@ -138,3 +138,3 @@ /**
      */
-    "enabled": false
+    "enabled": false,
 
@@ -165,3 +165,3 @@ /**
      */
-    ,"reportFolder": "<projectFolder>/[[[temp]]]/"
+    "reportFolder": "<projectFolder>/[[[temp]]]/",
 
@@ -181,3 +181,3 @@ /**
      */
-    ,"reportTempFolder": "<projectFolder>/[[[temp]]]/"
+    "reportTempFolder": "<projectFolder>/[[[temp]]]/"
 
@@ -201,3 +201,3 @@ /**
      */
-    "enabled": true
+    "enabled": true,
 
@@ -213,3 +213,3 @@ /**
      */
-    ,"apiJsonFilePath": "<projectFolder>/[[[temp]]]/<unscopedPackageName>.api.json"
+    "apiJsonFilePath": "<projectFolder>/[[[temp]]]/<unscopedPackageName>.api.json"
 
@@ -216,0 +216,0 @@ /**

src/build-docs.ts

 /* eslint-disable no-console */
 import { Extractor } from '@microsoft/api-extractor';
-import { readdirSync } from 'fs';
-import { Config, listPackages, loadConfig, ProcessingConfig, _docs, _packages, _temp } from './common';
+import { readdirSync, readFileSync, writeFileSync } from 'fs';
+import { Config, isWixDocs, listPackages, loadConfig, ProcessingConfig, _docs, _packages, _temp } from './common';
 import { createHeadersModifier, processMacros } from './process-macros';
-import { Macro, macros as builtinMacros } from './macros';
-import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter'
-import { ApiModel } from '@microsoft/api-extractor-model'
+import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter';
+import { ApiModel } from '@microsoft/api-extractor-model';
 import { dirname, join } from 'path';
-
+import type { Macros } from './macros.types';
+import * as builtinMacros from './macros';
+export type { Macros };
 /**
  * Build docs markdown
  */
-export function buildDocs(conf: string, skipAnalyze = false, macros?: Record<string, Macro>) {
+export function buildDocs(conf: string, skipAnalyze = false, macros?: Macros) {
     const config = loadConfig(conf);
@@ -25,15 +26,21 @@
         console.time('Analyzing APIs...');
-        const typescriptCompilerFolder = join(dirname(require.resolve('typescript')), '..')
-
-        listPackages(config).forEach((_package) => {
+        const typescriptCompilerFolder = join(dirname(require.resolve('typescript')), '..');
+        const analyzeFile = (path: string) => {
             try {
-                Extractor.loadConfigAndInvoke(_packages(config, _package, 'api-extractor.json'), {
+                Extractor.loadConfigAndInvoke(path, {
                     // at the time of writing this argument is ignored :(
                     typescriptCompilerFolder,
-                })
+                });
             } catch (err) {
-                throw new Error(`Error analyzing ${_packages(config, _package, 'api-extractor.json')}:
-                ${(err as Error).message}`)
+                throw new Error(`Error analyzing ${path}:
+                ${(err as Error).message}`);
             }
-        });
+        };
+        listPackages(config).forEach((_package) => analyzeFile(_packages(config, _package, 'api-extractor.json')));
+        if (isWixDocs(config)) {
+            analyzeFile(_packages(config, 'docs', 'macros.api-extractor.json'));
+            const macrosDocsPath = _temp(config, 'built-in-macros.api.json');
+            const macrosDocs = readFileSync(macrosDocsPath, 'utf8');
+            writeFileSync(macrosDocsPath, macrosDocs.replaceAll('@wixc3/docs', '@wixc3/docs-macros'));
+        }
         console.timeEnd('Analyzing APIs...');
@@ -45,23 +52,25 @@ }
     console.time('Building markdown files');
-    // execSync(`yarn api-documenter markdown -i ${_temp(config)} -o ${_docs(config)}`);
-    const model = new ApiModel()
+    const model = new ApiModel();
     listPackages(config).forEach((path) => {
-        model.loadPackage(_temp(config, `${path}.api.json`))
+        model.loadPackage(_temp(config, `${path}.api.json`));
     });
+    if (isWixDocs(config)) {
+        model.loadPackage(_temp(config, 'built-in-macros.api.json'));
+    }
     const dm = new MarkdownDocumenter({
         apiModel: model,
         outputFolder: _docs(config),
-        documenterConfig: undefined
-    })
-    dm.generateFiles()
+        documenterConfig: undefined,
+    });
+
+    dm.generateFiles();
     console.timeEnd('Building markdown files');
 }
 
-function evaluateMacros(config: Config, macros: Record<string, Macro> | undefined) {
+function evaluateMacros(config: Config, macros: Macros | undefined) {
     console.time('Processing macros');
-
     const pConf: ProcessingConfig = {
         ...config,
         modifier: createHeadersModifier(config),
-        macros: { ...builtinMacros, ...macros }
+        macros: { ...builtinMacros, ...macros },
     };
@@ -68,0 +77,0 @@ readdirSync(_docs(config), { withFileTypes: true })

src/common.ts

@@ -5,3 +5,3 @@ import { first, Nullable } from '@wixc3/common';
 import { basename, join } from 'path';
-import type { Macro } from './macros';
+import type { Macro } from './macros.types';
 
@@ -27,3 +27,3 @@ export function listPackages({ base, packages }: UserConfig) {
 export const execMacro = (data: string, replace: Record<string, string | ((...args: string[]) => string)>) => {
-    for (const match of data.matchAll(/(?<!\*)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
+    for (const match of data.matchAll(/(?<!`|<code>)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
         const { all, macro, args } = parseMacro(match);
@@ -45,5 +45,5 @@ const v = replace[macro];
 };
-export function getRepo(assert: true,  overrideOrigin?:string): Repo;
+export function getRepo(assert: true, overrideOrigin?: string): Repo;
 export function getRepo(): Nullable<Repo>;
-export function getRepo(assert = false, overrideOrigin?:string): Nullable<Repo> {
+export function getRepo(assert = false, overrideOrigin?: string): Nullable<Repo> {
     try {
@@ -74,6 +74,6 @@ const res = (overrideOrigin || execSync('git remote -v')).toString().split('\n')[1];
 export type UserConfig = {
-    conf: string
+    conf: string;
     base: string;
     packages: string;
-    temp: string
+    temp: string;
     docs: string;
@@ -88,5 +88,4 @@ siteUrl?: string;
 export type ProcessingConfig = Config & {
-    modifier?: (name: string, content: string) => string,
-    macros: Record<string, Macro>
-
+    modifier?: (name: string, content: string) => string;
+    macros: Record<string, Macro>;
 };
@@ -104,3 +103,3 @@
 export function writeConfig(config: Config, force: boolean) {
-    const path = join(config.base, config.conf, 'config.json')
+    const path = join(config.base, config.conf, 'config.json');
     if (force || !existsSync(path)) {
@@ -111,9 +110,9 @@ writeFileSync(path, JSON.stringify(config, null, 2), 'utf8');
 
-export const _packages = ({ base, packages }: UserConfig, ...path: string[]) =>
-    join(base, packages, ...path)
-export const _docs = ({ base, docs }: UserConfig, ...path: string[]) =>
-    join(base, docs, ...path)
-export const _config = ({ base, conf }: UserConfig, ...path: string[]) =>
-    join(base, conf, ...path)
-export const _temp = ({ base, temp }: UserConfig, ...path: string[]) =>
-    join(base, temp, ...path)
+export const _packages = ({ base, packages }: UserConfig, ...path: string[]) => join(base, packages, ...path);
+export const _docs = ({ base, docs }: UserConfig, ...path: string[]) => join(base, docs, ...path);
+export const _config = ({ base, conf }: UserConfig, ...path: string[]) => join(base, conf, ...path);
+export const _temp = ({ base, temp }: UserConfig, ...path: string[]) => join(base, temp, ...path);
+
+export function isWixDocs(config: Config) {
+    return config.git.github === 'https://github.com/wixplosives/core3-utils';
+}

src/index.ts

@@ -30,8 +30,6 @@ /**
  * There are many awesome macros you can use in your TDDocs.
- * Using macros look like this *[[[macro and args]]]
+ * Using macros look like this `[[[macro and args]]]`
  *
- * Available macros are:
+ * [[[include ./docs-macros.md]]]
  *
- * [[[listMacros]]]
- *
  */
@@ -38,0 +36,0 @@ export * from './build-docs';

src/init.ts

@@ -5,2 +5,4 @@ import { join, relative } from 'path';
 
+export { UserConfig };
+
 /**
@@ -15,11 +17,11 @@ * Initialize docs pre-requisites:
  */
-export function init(config: UserConfig, force = false, overrideOrigin?:string) {
-    const relConfig = relative(_packages(config,'pkg'), _config(config))
+export function init(config: UserConfig, force = false, overrideOrigin?: string) {
+    const relConfig = relative(_packages(config, 'pkg'), _config(config));
     const resources = join(__dirname, '..', '..', 'resources');
     const writeConfFile = (filename: string, data: string | object) => {
-        const path = _config(config, filename)
+        const path = _config(config, filename);
         if (force || !existsSync(path)) {
             writeFileSync(path, typeof data === 'string' ? data : JSON.stringify(data), 'utf8');
         }
-    }
+    };
     const template = (resource: string) => {
@@ -31,3 +33,3 @@ const template = readFileSync(join(resources, resource), 'utf8');
             temp: _temp(config),
-            confPath: _config(config)
+            confPath: _config(config),
         });
@@ -38,6 +40,9 @@ writeConfFile(resource, mod);
     mkdirSync(_config(config), { recursive: true });
-    writeConfig({
-        ...config,
-        git: getRepo(true, overrideOrigin),
-    }, force);
+    writeConfig(
+        {
+            ...config,
+            git: getRepo(true, overrideOrigin),
+        },
+        force
+    );
     template('api-extractor.base.json');
@@ -44,0 +49,0 @@ template('api-extractor.json');

src/macros.ts

 import { readPackageJson } from '@wixc3/fs-utils';
 import nodeFs from '@file-services/node';
-import { ProcessingConfig, Repo, stripName, _docs, _packages } from './common';
+import { Repo, stripName, _docs, _packages } from './common';
 import { processMacros } from './process-macros';
 import { repeat } from '@wixc3/common';
+import type { Macro } from './macros.types';
 
-export type Macro = (config: ProcessingConfig, filename: string, ...args: string[]) => string;
-export class MacroError extends Error {
-    constructor(public config: ProcessingConfig, public file: string, fn: Macro, _message: string) {
-        super(`Macro error in ${_docs(config, file)} - [[[${fn.name}]]]:
-    ${_message}`);
-    }
-}
+/**
+ *
+ * Project's root package name
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[rootPackageName]]]`
+ */
+export const rootPackageName: Macro = ({ base }) => readPackageJson(base, nodeFs).name || '';
 
-const rootPackageName: Macro = ({base}) => readPackageJson(base, nodeFs).name || '';
+/**
+ *
+ * Project's current package name
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageName]]]`
+ *
+ * Will be replace by the full package name, i.e `@wixc3/docs`
+ */
+export const packageName: Macro = (config, name) =>
+    config.git.github === 'https://github.com/wixplosives/core3-utils' && name.startsWith('docs-macros')
+        ? '@wixc3/docs'
+        : readPackageJson(_packages(config, stripName(name)), nodeFs).name?.toString() || '';
 
-const packageName: Macro = (config, name) =>
-    readPackageJson(_packages(config, stripName(name)), nodeFs).name?.toString() || '';
+/**
+ *
+ * Project's current package name, unscoped
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ * *[[[unscopedPackageName]]]
+ *
+ * Will be replace by the full package name, i.e `bla` for `@wixc3/bla`
+ */
+export const unscopedPackageName: Macro = (config, name) => packageName(config, name).replace(/.*\//, '');
 
-const unscopedPackageName: Macro = (config, name) => macros.packageName(config, name).replace(/.*\//, '');
-
-const packageNameUrl: Macro = (config, name) =>
-    macros
-        .packageName(config, name)
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block of a package:
+ *
+ * `[[[packageNameUrl]]]`
+ *
+ * This is useful for generating links and badges
+ */
+export const packageNameUrl: Macro = (config, name) =>
+    packageName(config, name)
         .split('@')
@@ -29,3 +60,13 @@ .map((i: string) => encodeURIComponent(i))
 
-const gitRepo: Macro = (config, name, field = 'github') => {
+/**
+ *
+ * Project's current package name, in a url friendly format
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[gitRepo field?]]]`
+ *
+ * where field can be: host | org | repo | pages | github
+ */
+export const gitRepo: Macro = (config, name, field = 'github') => {
     const { git } = config;
@@ -35,6 +76,3 @@ if (field in git) {
     }
-    throw new MacroError(
-        config,
-        name,
-        gitRepo,
+    throw new Error(
         `Invalid argument "${field}" options are:
@@ -45,10 +83,31 @@ ${Object.keys(git).join(', ')}`
 
-const githubPages: Macro = ({ git: { pages } }, _name = '', uri = '', caption = '') => {
+/**
+ *
+ * A link to the project's github pages
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubPages uri? caption?]]]`
+ *
+ * where uri can be an inner page
+ *
+ * if caption is provided a markdown link will be created, otherwise the raw root URL will replace the macro
+ *
+ */
+export const githubPages: Macro = ({ git: { pages } }, _name, uri = '', caption = '') => {
     return caption === '' ? pages : `[${caption}](${pages}/${uri})`;
 };
 
-const githubBuildStatus: Macro = ({ git: { github } }) =>
+/**
+ *
+ * A github build status badge
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[githubBuildStatus]]]`
+ */
+export const githubBuildStatus: Macro = ({ git: { github } }) =>
     `[![Build Status](${github}/workflows/tests/badge.svg)](${github}/actions)`;
 
-const npmBadge: Macro = (config, name) => {
+export const npmBadge: Macro = (config, name) => {
     const pkg = packageNameUrl(config, name);
@@ -58,11 +117,26 @@ return `[![npm version](https://badge.fury.io/js/${pkg}.svg)](https://badge.fury.io/js/${pkg})`;
 
-const github: Macro = (config, name) =>
-    `[${packageName(config, name)} on Github](${config.git.github}/tree/master/${config.packages}/${unscopedPackageName(
-        config,
-        name
-    )})`;
+/**
+ *
+ * A link to the package on github
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[github caption?]]]`
+ */
+export const github: Macro = (config, name, caption?) => {
+    caption = caption || `${packageName(config, name)} on Github`;
+    return `[${caption}](${config.git.github}/tree/master/${config.packages}/${unscopedPackageName(config, name)})`;
+};
 
-const include: Macro = (config, name, target = '') => {
+/**
+ *
+ * Include another markdown file (that may also have macros)
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[include path]]]`
+ */
+export const include: Macro = (config, name, target = '') => {
     if (!target) {
-        throw new MacroError(config, name, include, 'Missing target argument');
+        throw new Error('Missing target argument');
     }
@@ -72,29 +146,25 @@ return processMacros(config, target, name);
 
-const h: Macro = (_, __, level, ...text) => `${repeat('#', parseInt(level))} ${text.join(' ')}\n`;
+/**
+ *
+ * Heading - since ts-docs to not natively allow for markdown
+ * formatting, this macro is used to create a #, ##, ## etc
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[h level title]]]`
+ */
+export const h: Macro = (_, __, level, ...title) => `${repeat('#', parseInt(level))} ${title.join(' ')}\n`;
 
-const listMacros: Macro = () => {
+/**
+ * Lists all the available macros
+ *
+ * Usage: inside a ts-docs comment block:
+ *
+ * `[[[listMacros]]]`
+ */
+export const listMacros: Macro = ({ macros }) => {
     return Object.keys(macros)
         .sort()
-        .map((name) => ` - *\\[\\[\\[${name}\\]\\]\\]`)
+        .map((name) => ` - [*\\[\\[\\[${name}\\]\\]\\]](./docs-macros.${name}.md)`)
         .join('\n');
 };
-
-export const macros = {
-    // Package name
-    rootPackageName,
-    packageNameUrl,
-    packageName,
-    unscopedPackageName,
-    // git & github
-    github,
-    githubPages,
-    gitRepo,
-    // utility
-    include,
-    listMacros,
-    // badges
-    npmBadge,
-    githubBuildStatus,
-    // Formatting
-    h,
-};

src/process-macros.ts

@@ -1,15 +0,16 @@
-import {  readFileSync, writeFileSync } from 'fs';
+import { readFileSync, writeFileSync } from 'fs';
 import { join, relative } from 'path';
 import { ProcessingConfig, execMacro, Config, _docs } from './common';
-import { mapValues, repeat } from '@wixc3/common';
+import { mapValues } from '@wixc3/common';
+import { MacroError } from './macros.types';
 
 export const createHeadersModifier = (config: Config) => {
-    const headers = relative(config.docs, config.conf)
-    return (name: string, content: string) => {
-        let file = 'item'
+    const headers = relative(config.docs, config.conf);
+    return function addHeaders(name: string, content: string) {
+        let file = 'item';
         if (name === 'index.md') {
-            file = 'index'
+            file = 'index';
         } else {
             if (name.split('.').length === 2) {
-                file = 'package'
+                file = 'package';
             }
@@ -19,3 +20,3 @@ }
 ${content}`;
-    }
+    };
 };
@@ -26,9 +27,10 @@
     const mod = config.modifier && !filenameOverride ? config.modifier(filename, source) : source;
-    const macrosCtx = mapValues(
-        config.macros,
-        (m) =>
-            (...args: string[]) =>
-                m(config, filenameOverride || filename, ...args)
-    );
-    const processed = execMacro(mod, macrosCtx).replaceAll(/\*(\\\[){3}/g, repeat('\\[', 3));
+    const macrosCtx = mapValues(config.macros, (m) => (...args: string[]) => {
+        try {
+            return m(config, filenameOverride || filename, ...args);
+        } catch (err) {
+            throw new MacroError(config, filenameOverride || filename, m, args, (err as Error).message);
+        }
+    });
+    const processed = execMacro(mod, macrosCtx);
     if (source !== processed) {
@@ -35,0 +37,0 @@ writeFileSync(_docs(config, filenameOverride || filename), processed, { encoding: 'utf8' });

src/test/build.unit.ts

 /* eslint-disable @typescript-eslint/no-unsafe-return */
-import { expect } from "chai"
-import { buildDocs } from "../build-docs"
-import { setup, clean, config, overwriteTemplate, readDoc, docExists, runMacro } from "./test-common"
-import { macros } from '../macros'
-import { existsSync, rmSync } from "fs"
-import { _config, _docs, _temp } from "../common"
+import { expect } from 'chai';
+import { buildDocs } from '../build-docs';
+import { setup, clean, config, overwriteTemplate, readDoc, docExists, runMacro } from './test-common';
+import * as macros from '../macros';
+import { existsSync, rmSync } from 'fs';
+import { _config, _docs, _temp } from '../common';
+import type { Macro, Macros } from '../macros.types';
 
 describe('buildDocs', function () {
-    this.timeout(10_000)
-    before(setup)
+    before(setup);
     before(function () {
-        this.timeout(5_000)
-        buildDocs(_config(config), false)
-    })
-    after(clean)
+        this.timeout(10_000);
+        buildDocs(_config(config), false);
+    });
+    after(clean);
     it('builds readme files in the docs directory', function () {
-        expect(docExists('index.md')).to.equal(true)
-        expect(docExists('one.md')).to.equal(true)
-        expect(docExists('one.test1.md')).to.equal(true)
-        expect(docExists('two.md')).to.equal(true)
-        expect(docExists('two.test1.md')).to.equal(true)
-    })
+        expect(docExists('index.md')).to.equal(true);
+        expect(docExists('one.md')).to.equal(true);
+        expect(docExists('one.test1.md')).to.equal(true);
+        expect(docExists('two.md')).to.equal(true);
+        expect(docExists('two.test1.md')).to.equal(true);
+    });
     it('generate api jsons in the temp directory', () => {
-        expect(existsSync(_temp(config, 'one.api.json'))).to.equal(true)
-        expect(existsSync(_temp(config, 'two.api.json'))).to.equal(true)
-    })
+        expect(existsSync(_temp(config, 'one.api.json'))).to.equal(true);
+        expect(existsSync(_temp(config, 'two.api.json'))).to.equal(true);
+    });
     it('includes headers', function () {
-        overwriteTemplate('index.md', 'INDEX_HEADER')
-        overwriteTemplate('item.md', 'ITEM_HEADER')
-        overwriteTemplate('package.md', 'PACKAGE_HEADER')
+        overwriteTemplate('index.md', 'INDEX_HEADER');
+        overwriteTemplate('item.md', 'ITEM_HEADER');
+        overwriteTemplate('package.md', 'PACKAGE_HEADER');
 
-        buildDocs(_config(config), true)
+        buildDocs(_config(config), true);
 
-        expect(readDoc('index.md')).to.match(/INDEX_HEADER/)
-        expect(readDoc('one.md')).to.match(/PACKAGE_HEADER/)
-        expect(readDoc('two.test1.md')).to.match(/ITEM_HEADER/)
-    })
+        expect(readDoc('index.md')).to.match(/INDEX_HEADER/);
+        expect(readDoc('one.md')).to.match(/PACKAGE_HEADER/);
+        expect(readDoc('two.test1.md')).to.match(/ITEM_HEADER/);
+    });
     it('evaluates macros, passing config filename and args', function () {
-        overwriteTemplate('index.md', '[[[macro 1 !]]]')
+        overwriteTemplate('index.md', '[[[macro 1 !]]]');
 
         buildDocs(_config(config), true, {
             macro: (conf, docFileName, a, b) => {
-                expect(conf).to.deep.include(config)
-                expect(docFileName).to.eql('index.md')
-                return `MACRO${a}${b}`
-            }
-        })
+                expect(conf).to.deep.include(config);
+                expect(docFileName).to.eql('index.md');
+                return `MACRO${a}${b}`;
+            },
+        } as Macros);
 
-        expect(readDoc('index.md')).to.match(/MACRO1!/)
-    })
+        expect(readDoc('index.md')).to.match(/MACRO1!/);
+    });
 
     describe('builtin macros', () => {
         before(function () {
-            this.timeout(5_000)
-            buildDocs(_config(config), false)
-        })
+            this.timeout(10_000);
+            buildDocs(_config(config), false);
+        });
         beforeEach(() => {
-            rmSync(_docs(config), { recursive: true })
-        })
+            rmSync(_docs(config), { recursive: true });
+        });
         it('runMacro', () => {
-            expect(runMacro('NO_SUCH_MACRO')).to.equal('[[[NO_SUCH_MACRO ]]]')
-            expect(runMacro('NO_SUCH_MACRO', 'one.md')).to.equal('[[[NO_SUCH_MACRO ]]]')
-            expect(runMacro('NO_SUCH_MACRO', 'one.test1.md')).to.equal('[[[NO_SUCH_MACRO ]]]')
-        })
+            expect(runMacro('NO_SUCH_MACRO')).to.equal('[[[NO_SUCH_MACRO ]]]');
+            expect(runMacro('NO_SUCH_MACRO', 'one.md')).to.equal('[[[NO_SUCH_MACRO ]]]');
+            expect(runMacro('NO_SUCH_MACRO', 'one.test1.md')).to.equal('[[[NO_SUCH_MACRO ]]]');
+        });
 
+        it('does not run macro comments - `[[[comment]]]`', () => {
+            const comment: Macro = () => 'error';
+            overwriteTemplate('index.md', '`[[[comment]]]`');
+            buildDocs(_config(config), true, { comment });
+            const content = readDoc('index.md');
+            expect(content).to.match(/`\[\[\[comment\]\]\]`/g);
+            expect(content).not.to.match(/error/g);
+        });
+
         it('rootPackageName', () => {
-            expect(runMacro(macros.rootPackageName)).to.eql('main')
-        })
+            expect(runMacro(macros.rootPackageName)).to.eql('main');
+        });
 
         it('packageNameUrl', () => {
-            expect(runMacro(macros.packageNameUrl, 'one.md')).to.equal('@test%2Fone')
-        })
+            expect(runMacro(macros.packageNameUrl, 'one.md')).to.equal('@test%2Fone');
+        });
 
         it('packageName', () => {
-            expect(runMacro(macros.packageName, 'one.md')).to.equal('@test/one')
-        })
+            expect(runMacro(macros.packageName, 'one.md')).to.equal('@test/one');
+        });
 
         it('unscopedPackageName', () => {
-            expect(runMacro(macros.unscopedPackageName, 'one.md')).to.equal('one')
-        })
+            expect(runMacro(macros.unscopedPackageName, 'one.md')).to.equal('one');
+        });
 
@@ -86,34 +95,32 @@ it('github', () => {
                 '[@test/two on Github](https://github.com/org/repo/tree/master/packages/two)'
-            )
+            );
             expect(runMacro(macros.github, 'two.test1.md')).to.equal(
                 '[@test/two on Github](https://github.com/org/repo/tree/master/packages/two)'
-            )
+            );
             expect(runMacro(macros.github)).to.equal(
                 '[main on Github](https://github.com/org/repo/tree/master/packages/main)'
-            )
-        })
+            );
+        });
         it('githubPages', () => {
-            expect(runMacro(macros.githubPages)).to.equal(
-                'https://org.github.io/repo')
-        })
+            expect(runMacro(macros.githubPages)).to.equal('https://org.github.io/repo');
+        });
         it('gitRepo', () => {
-            expect(runMacro(macros.gitRepo)).to.equal(
-                'https://github.com/org/repo')
-            expect(runMacro(macros.gitRepo, 'one.md', 'org')).to.equal(
-                'org')
-            expect(() => runMacro(macros.gitRepo, 'one.md', 'invalid')).to.throw()
-        })
+            expect(runMacro(macros.gitRepo)).to.equal('https://github.com/org/repo');
+            expect(runMacro(macros.gitRepo, 'one.md', 'org')).to.equal('org');
+            expect(() => runMacro(macros.gitRepo, 'one.md', 'invalid')).to.throw();
+        });
         it('include', () => {
-            expect(runMacro(macros.include, 'index.md', '../include.md')).to.equal(
-                'Included!')
-        })
+            expect(runMacro(macros.include, 'index.md', '../include.md')).to.equal('Included!');
+        });
         it('npmBadge', () => {
             expect(runMacro(macros.npmBadge)).to.equal(
-                '[![npm version](https://badge.fury.io/js/main.svg)](https://badge.fury.io/js/main)')
-        })
+                '[![npm version](https://badge.fury.io/js/main.svg)](https://badge.fury.io/js/main)'
+            );
+        });
         it('githubBuildStatus', () => {
             expect(runMacro(macros.githubBuildStatus)).to.equal(
-                '[![Build Status](https://github.com/org/repo/workflows/tests/badge.svg)](https://github.com/org/repo/actions)')
-        })
-    })
-})
+                '[![Build Status](https://github.com/org/repo/workflows/tests/badge.svg)](https://github.com/org/repo/actions)'
+            );
+        });
+    });
+});

src/test/init.unit.ts

@@ -5,40 +5,41 @@ /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 
-import { existsSync } from "fs";
-import { join, resolve } from "path";
-import { expect } from "chai";
-import { loadJson, config, setup, clean } from "./test-common";
-import { _config, _packages, _temp } from "../common";
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { expect } from 'chai';
+import { loadJson, config, setup, clean } from './test-common';
+import { _config, _packages, _temp } from '../common';
 
 describe('init', function () {
-    // since this this is a longish process, 
+    // since this this is a longish process,
     // ini t is called only once, all test are checking the resulting files
     // tests do not mutate anything
     // init is executed in "setup"
-    this.timeout(10_000)
-    before(setup)
-    after(clean)
+    this.timeout(10_000);
+    before(setup);
+    after(clean);
     it('generates docs config files and templates', () => {
-        const base = loadJson(_config(config, 'api-extractor.base.json'))
+        const base = loadJson(_config(config, 'api-extractor.base.json'));
         // input
-        expect(base?.mainEntryPointFilePath).to.equal(`<projectFolder>/${_packages(config)}/<unscopedPackageName>/dist/cjs/index.d.ts`)
+        expect(base?.mainEntryPointFilePath).to.equal(
+            `<projectFolder>/${_packages(config)}/<unscopedPackageName>/dist/cjs/index.d.ts`
+        );
         // temp dir
-        expect(base?.apiReport?.reportFolder).to.equal(`<projectFolder>/${_temp(config)}/`)
-        expect(base?.apiReport?.reportTempFolder).to.equal(`<projectFolder>/${_temp(config)}/`)
-        expect(base?.docModel?.apiJsonFilePath).to.equal(`<projectFolder>/${_temp(config)}/<unscopedPackageName>.api.json`)
+        expect(base?.apiReport?.reportFolder).to.equal(`<projectFolder>/${_temp(config)}/`);
+        expect(base?.apiReport?.reportTempFolder).to.equal(`<projectFolder>/${_temp(config)}/`);
+        expect(base?.docModel?.apiJsonFilePath).to.equal(
+            `<projectFolder>/${_temp(config)}/<unscopedPackageName>.api.json`
+        );
         // output
-
-    })
+    });
     it('generates a "api-extractor.json" in each package', () => {
-        const one = _packages(config, 'one')
-        const apiExConf1 = loadJson(one, 'api-extractor.json')
-        expect(resolve(one, apiExConf1?.extends)).to.equal(
-            resolve(_config(config, 'api-extractor.base.json')))
-        const two = _packages(config, 'two')
-        const apiExConf2 = loadJson(one, 'api-extractor.json')
-        expect(resolve(two, apiExConf2?.extends)).to.equal(
-            resolve(_config(config, 'api-extractor.base.json')))
-    })
+        const one = _packages(config, 'one');
+        const apiExConf1 = loadJson(one, 'api-extractor.json');
+        expect(resolve(one, apiExConf1?.extends)).to.equal(resolve(_config(config, 'api-extractor.base.json')));
+        const two = _packages(config, 'two');
+        const apiExConf2 = loadJson(one, 'api-extractor.json');
+        expect(resolve(two, apiExConf2?.extends)).to.equal(resolve(_config(config, 'api-extractor.base.json')));
+    });
     it('creates a github action that updates github pages', () => {
-        expect(existsSync(join(config.base, '.github', 'workflows', 'jekyll-gh-pages.yml')))
-    })
-})
+        expect(existsSync(join(config.base, '.github', 'workflows', 'jekyll-gh-pages.yml')));
+    });
+});

src/test/resources/api-extractor.test.base.json

@@ -138,3 +138,3 @@ /**
      */
-    "enabled": false
+    "enabled": false,
 
@@ -165,3 +165,3 @@ /**
      */
-    ,"reportFolder": "<projectFolder>/temp-test/"
+    "reportFolder": "<projectFolder>/temp-test/",
 
@@ -181,3 +181,3 @@ /**
      */
-    ,"reportTempFolder": "<projectFolder>/temp-test/"
+    "reportTempFolder": "<projectFolder>/temp-test/"
 
@@ -201,3 +201,3 @@ /**
      */
-    "enabled": true
+    "enabled": true,
 
@@ -213,3 +213,3 @@ /**
      */
-    ,"apiJsonFilePath": "<projectFolder>/temp-test/<unscopedPackageName>.api.json"
+    "apiJsonFilePath": "<projectFolder>/temp-test/<unscopedPackageName>.api.json"
 
@@ -216,0 +216,0 @@ /**

src/test/resources/project/include.md

@@ -1,1 +0,1 @@
-Included!
+Included!

src/test/resources/project/package.json

 {
-    "name": "main",
-    "workspaces":["packages/*"]
-}
+  "name": "main",
+  "workspaces": [
+    "packages/*"
+  ]
+}

src/test/resources/project/packages/one/dist/cjs/index.js

@@ -5,8 +5,6 @@ "use strict";
 function test1() {
-    // [[[example
     const a = 1;
     return a;
-    // ]]]
 }
 exports.test1 = test1;
 //# sourceMappingURL=index.js.map

src/test/resources/project/packages/one/package.json

 {
-    "name": "@test/one"
-}
+  "name": "@test/one"
+}

src/test/resources/project/packages/one/src/index.ts

@@ -1,6 +0,4 @@
-export function test1(){
-    // [[[example
-    const a=1;
+export function test1() {
+    const a = 1;
     return a;
-    // ]]]
 }

src/test/resources/project/packages/two/package.json

 {
-    "name": "@test/two"
-}
+  "name": "@test/two"
+}

src/test/resources/project/packages/two/src/index.ts

@@ -1,3 +0,3 @@
-export function test1(){
-    return 1
-}
+export function test1() {
+    return 1;
+}

src/test/test-common.ts

@@ -1,8 +0,8 @@
-import { cpSync, existsSync, mkdirSync, readFileSync,  rmSync,  writeFileSync } from "fs";
-import { join } from "path";
-import { UserConfig, _config, _docs } from "../common";
-import { init } from "../init";
-import { buildDocs } from "../build-docs";
-import { escapeRegExp, isString, naiveStripComments } from "@wixc3/common";
-import type { Macro } from "../macros";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { UserConfig, _config, _docs } from '../common';
+import { init } from '../init';
+import { buildDocs } from '../build-docs';
+import { escapeRegExp, isString, naiveStripComments } from '@wixc3/common';
+import type { Macro } from '../macros.types';
 
@@ -15,49 +15,64 @@ export const config: UserConfig = {
     temp: 'test-temp',
-}
+};
 
 export const loadJson = (...paths: string[]) => {
-    const path=join(...paths);
-    const content = naiveStripComments(readFileSync(path, 'utf8'))
+    const path = join(...paths);
+    const content = naiveStripComments(readFileSync(path, 'utf8'));
     try {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        return JSON.parse(content) 
+        return JSON.parse(content);
     } catch (err) {
-        throw new Error(`${err}\n${path}\n${content}`)
+        throw new Error(`${err}\n${path}\n${content}`);
     }
-}
+};
 
+// eslint-disable-next-line no-console
+const config_log = console.log;
+
 export const setup = () => {
-    clean()
-    mkdirSync(config.base, { recursive: true })
-    // const resources = join(__dirname, 'resources');
+    clean();
+    // eslint-disable-next-line no-console
+    console.log = () => {
+        /* */
+    };
+    mkdirSync(config.base, { recursive: true });
     cpSync(join(__dirname, '..', '..', '..', 'src', 'test', 'resources', 'project'), config.base, { recursive: true });
-    // cpSync(join(resources, 'project'), config.base, { recursive: true });
-    init(config, true,  `origin	[e-mail]:org/repo.git (fetch)
-origin	[e-mail]:org/repo.git (push)`)
-}
+    init(
+        config,
+        true,
+        `origin	[e-mail]:org/repo.git (fetch)
+origin	[e-mail]:org/repo.git (push)`
+    );
+};
 
-export const clean = () =>{
+export const clean = () => {
+    // eslint-disable-next-line no-console
+    console.log = config_log;
     if (existsSync(config.base)) {
         rmSync(config.base, {
-            recursive: true, force:true
-        })
+            recursive: true,
+            force: true,
+        });
     }
-}
+};
 
-export const readDoc = (name:string) => readFileSync(_docs(config, name), 'utf8')
-export const docExists = (name:string) => existsSync(_docs(config, name))
-export const overwriteTemplate = (name:string, content:string) => writeFileSync(_config(config, name), content, 'utf8')
-export const runMacro = (macro:Macro|string, filename = 'index.md', ...args: string[]) => {
+export const readDoc = (name: string) => readFileSync(_docs(config, name), 'utf8');
+export const docExists = (name: string) => existsSync(_docs(config, name));
+export const overwriteTemplate = (name: string, content: string) =>
+    writeFileSync(_config(config, name), content, 'utf8');
+export const runMacro = (macro: Macro | string, filename = 'index.md', ...args: string[]) => {
     const header = `
     >>>>>>>
-    [[[${isString(macro) ? macro: macro.name} ${args.join(' ')}]]]
+    [[[${isString(macro) ? macro : macro.name} ${args.join(' ')}]]]
     <<<<<<<
-    `
-    overwriteTemplate('index.md', header )
-    overwriteTemplate('package.md', header )
-    overwriteTemplate('item.md', header )
+    `;
+    overwriteTemplate('index.md', header);
+    overwriteTemplate('package.md', header);
+    overwriteTemplate('item.md', header);
 
-    buildDocs(_config(config), true)
-    return readDoc(filename).replaceAll(/>>>>>>>(.*)<<<<<<<.*$/gs, '$1').trim()
-}
-export const asRegex = (str:string) => new RegExp(escapeRegExp(str))
+    buildDocs(_config(config), true);
+    return readDoc(filename)
+        .replaceAll(/>>>>>>>(.*)<<<<<<<.*$/gs, '$1')
+        .trim();
+};
+export const asRegex = (str: string) => new RegExp(escapeRegExp(str));

src/tsconfig.esm.json

@@ -7,6 +7,3 @@ {
   },
-  "references": [
-    { "path": "../../common/src/tsconfig.esm.json" },
-    { "path": "../../fs-utils/src/tsconfig.esm.json" }
-  ]
+  "references": [{ "path": "../../common/src/tsconfig.esm.json" }, { "path": "../../fs-utils/src/tsconfig.esm.json" }]
 }

src/tsconfig.json

 {
   "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
-    "types": [
-      "node",
-      "mocha"
-    ],
+    "types": ["node", "mocha"],
     "outDir": "../dist/cjs"
   },
-  "references": [
-    { "path": "../../common/src" },
-    { "path": "../../fs-utils/src" }
-  ]
-}
+  "references": [{ "path": "../../common/src" }, { "path": "../../fs-utils/src" }]
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

186484

increased by18.41%

Number of package files

114

increased by9.62%

Lines of code

3348

increased by20.04%

Number of lines in readme file

95

increased by313.04%

Worsened metrics

Dependency count

6

increased by50%

Dependency changes

• + Added@wixc3/common@^3.0.2

• + Added@wixc3/fs-utils@^3.0.2

• + Added@file-services/memory@7.4.0(transitive)

• + Added@file-services/path@7.4.0(transitive)

• + Added@file-services/types@7.4.0(transitive)

• + Added@file-services/utils@7.4.0(transitive)

• + Added@wixc3/common@3.0.7(transitive)

• + Added@wixc3/fs-utils@3.0.7(transitive)

• + Addedpromise-assist@1.3.0(transitive)

• Updatedyargs@^17.6.2