@salesforcedevs/sfdocs-remark-include-plugin 0.0.1-alpha

package/README.md

@@ -0,0 +1,49 @@
+# Remark Include plugin
+
+## About
+
+This is a custom plugin for including the contents of another file in a markdown document. It processes the include directive (`::include{src="..."}`) by reading the target file, parsing or processing it through the unified pipeline, and replacing the directive with the included content.
+
+Example:
+
+```markdown
+::include{src="../shared/snippet.md"}
+```
+
+When the included file path contains `/shared/`, image URLs in that content are rewritten to absolute paths using the content directory.
+
+## Usage
+
+Use with `remark-directive` in your unified pipeline:
+
+```javascript
+import unified from 'unified';
+import remarkParse from 'remark-parse';
+import remarkDirective from 'remark-directive';
+import includePlugin from '@salesforcedevs/sfdocs-remark-include-plugin';
+
+unified()
+  .use(remarkParse)
+  .use(remarkDirective)
+  .use(includePlugin())
+  .processSync(markdown);
+```
+
+Optional custom renderer (for custom HTML wrapping of included content):
+
+```javascript
+includePlugin({
+  renderInclude(metadata) {
+    const root = metadata.get('root');
+    const node = metadata.get('node');
+    const out = new Map();
+    out.set('outputDom', `<div class="include">${root}</div>`);
+    return out;
+  },
+});
+```
+
+## Development
+
+- `yarn build` — compile TypeScript
+- `yarn test` — run tests

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { Transformer } from 'unified';
+/**
+ * SFDocs Include Plugin
+ * Processes include directives (::include{src="path/to/file.md"}) by reading the file,
+ * parsing or processing it through the unified pipeline, and replacing the directive
+ * with the included content. Must be used after remark-directive.
+ * When the included file path contains /shared/, image URLs in that content are rewritten to absolute paths using the content directory.
+ *
+ * @param options - Optional { renderInclude } for custom HTML rendering of included content
+ * @returns Remark transformer function
+ */
+declare function includePlugin(options?: {
+    renderInclude?: (metadata: Map<string, unknown>) => Map<string, string>;
+}): () => Transformer;
+export default includePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAwCtC;;;;;;;;;GASG;AACH,iBAAS,aAAa,CAAC,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,WAAW,CAsC/H;AAED,eAAe,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const unist_util_visit_1 = __importDefault(require("unist-util-visit"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const vfile_1 = __importDefault(require("vfile"));
+const INCLUDE_DIRECTIVE = 'include';
+const LEAF_DIRECTIVE_TYPE = 'leafDirective';
+const CONTENT_FOLDER = '/content/';
+const SHARED_PATH_SEGMENT = '/shared/';
+function getContentDirPath(curFilePath) {
+    const position = curFilePath.indexOf(CONTENT_FOLDER);
+    if (position !== -1) {
+        return curFilePath.slice(0, position + CONTENT_FOLDER.length);
+    }
+    return '';
+}
+function getSubstringAfterMedia(folderPath) {
+    const idx = folderPath.indexOf('/media');
+    if (idx !== -1)
+        return folderPath.substring(idx + 1);
+    const idx2 = folderPath.indexOf('media');
+    if (idx2 !== -1)
+        return folderPath.substring(idx2);
+    return folderPath;
+}
+function transformImageLinksInTree(root, contentDir) {
+    if (!contentDir)
+        return;
+    (0, unist_util_visit_1.default)(root, 'image', (node) => {
+        const filePath = node.url;
+        const isRelativeUrl = !(filePath === null || filePath === void 0 ? void 0 : filePath.match(/^(https?:\/\/|www\.).*/));
+        if (isRelativeUrl && filePath) {
+            const afterMedia = getSubstringAfterMedia(filePath);
+            node.url = path_1.default.join(contentDir, afterMedia);
+        }
+    });
+}
+/**
+ * SFDocs Include Plugin
+ * Processes include directives (::include{src="path/to/file.md"}) by reading the file,
+ * parsing or processing it through the unified pipeline, and replacing the directive
+ * with the included content. Must be used after remark-directive.
+ * When the included file path contains /shared/, image URLs in that content are rewritten to absolute paths using the content directory.
+ *
+ * @param options - Optional { renderInclude } for custom HTML rendering of included content
+ * @returns Remark transformer function
+ */
+function includePlugin(options) {
+    return function includePluginImpl() {
+        const processor = this;
+        return function transformer(tree, file) {
+            (0, unist_util_visit_1.default)(tree, (node, i, parent) => {
+                var _a;
+                if (node.type !== LEAF_DIRECTIVE_TYPE || node.name !== INCLUDE_DIRECTIVE || !parent)
+                    return;
+                const src = (_a = node.attributes) === null || _a === void 0 ? void 0 : _a.src;
+                if (!src) {
+                    file.fail('Include directive requires a src attribute', node);
+                    return;
+                }
+                const filename = path_1.default.resolve(file.dirname || '', src);
+                if (!fs_1.default.existsSync(filename)) {
+                    file.fail(`File not found ${filename}`, node);
+                    return;
+                }
+                try {
+                    const includeFile = (0, vfile_1.default)({ path: filename, contents: fs_1.default.readFileSync(filename) });
+                    if (options === null || options === void 0 ? void 0 : options.renderInclude) {
+                        const root = processor.processSync(includeFile);
+                        const metadata = new Map([['root', root], ['node', node]]);
+                        const out = options.renderInclude(metadata).get('outputDom');
+                        parent.children.splice(i, 1, { type: 'html', value: out });
+                    }
+                    else {
+                        let root = processor.parse(includeFile);
+                        if (filename.includes(SHARED_PATH_SEGMENT)) {
+                            transformImageLinksInTree(root, getContentDirPath(filename));
+                        }
+                        parent.children.splice(i, 1, ...root.children);
+                    }
+                }
+                catch (err) {
+                    file.fail((err === null || err === void 0 ? void 0 : err.message) || `Failed to read file ${filename}`, node);
+                }
+            });
+        };
+    };
+}
+exports.default = includePlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "version": "0.0.1-alpha",
+  "name": "@salesforcedevs/sfdocs-remark-include-plugin",
+  "description": "SFDocs remark plugin for the include directive",
+  "author": "SFDocs Team",
+  "keywords": [
+    "sfdocs-plugin",
+    "remark-include"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "files": [
+    "dist/*",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "yarn compile",
+    "compile": "tsc -p tsconfig.json",
+    "prepublish": "yarn build",
+    "test": "jest",
+    "test:ci": "yarn test --maxWorkers=1 --ci --coverage",
+    "watch": "tsc --watch"
+  },
+  "types": "dist/index.d.ts",
+  "prettier": "@salesforcedevs/sfdocs-prettier",
+  "dependencies": {
+    "@salesforcedevs/sfdocs-prettier": "latest",
+    "rehype-raw": "^5.0.0",
+    "rehype-stringify": "^8.0.0",
+    "remark-directive": "^1.0.1",
+    "remark-gfm": "^1.0.0",
+    "remark-parse": "^9.0.0",
+    "remark-rehype": "^8.0.0",
+    "unified": "^9.0.0",
+    "unist-util-visit": "^2.0.3",
+    "vfile": "^4.2.0"
+  },
+  "devDependencies": {
+    "@babel/preset-typescript": "7.10.4",
+    "@types/jest": "^26.0.23",
+    "@types/node": "^15.6.1",
+    "jest": "^29.7.0",
+    "mock-fs": "^4.13.0",
+    "strip-indent": "^3.0.0",
+    "ts-jest": "^29.2.5",
+    "tslint": "^6.1.2",
+    "typescript": "^4.1.3"
+  }
+}