@salesforcedevs/sfdocs-remark-include-plugin 0.0.5-alpha → 0.1.0-alpha

package/README.md

@@ -1,21 +1,15 @@
 # Remark Include Plugin
 
-## Usage
-
-Use with `remark-directive` in your unified pipeline:
-
 ## Examples
 
-Basic include:
+Include another markdown file:
 
 ```
 ::include{src="../shared/snippet.md"}
 ```
 
-Include with shared media rewrite:
+The plugin reads the target file, parses it, and inserts its children into the current document.
 
-```
-::include{src="../shared/test_include.md"}
-```
+If the included file path contains `/shared/`, relative image URLs in that included content are rewritten to absolute content paths.
 
-If the included file path contains `/shared/`, relative media links inside that file are rewritten to content-root absolute paths.
+You can pass custom render functions as the plugin’s second argument, e.g. for a VS Code extension.

package/dist/index.d.ts

@@ -6,8 +6,9 @@ import { Transformer } from 'unified';
  * 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 customRenderFunctions - Optional; for custom rendering functions (e.g. `renderInclude`).
  * @returns Function that returns a Remark transformer
  */
-declare function includePlugin(): () => Transformer;
+declare function includePlugin(customRenderFunctions?: any): () => Transformer;
 export default includePlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAwCtC;;;;;;;;GAQG;AACH,iBAAS,aAAa,UACmB,WAAW,CAgCnD;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAoCtC;;;;;;;;;GASG;AACH,iBAAS,aAAa,CAAC,qBAAqB,CAAC,KAAA,SACJ,WAAW,CAiCnD;AAED,eAAe,aAAa,CAAC"}

package/dist/index.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const unist_util_visit_1 = __importDefault(require("unist-util-visit"));
-const hastscript_1 = __importDefault(require("hastscript"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const vfile_1 = __importDefault(require("vfile"));
@@ -12,6 +11,7 @@ const INCLUDE_DIRECTIVE = 'include';
 const LEAF_DIRECTIVE_TYPE = 'leafDirective';
 const CONTENT_FOLDER = '/content/';
 const SHARED_PATH_SEGMENT = '/shared/';
+const MEDIA_FOLDER = '/media';
 function getContentDirPath(curFilePath) {
     const position = curFilePath.indexOf(CONTENT_FOLDER);
     if (position !== -1) {
@@ -20,13 +20,8 @@ function getContentDirPath(curFilePath) {
     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;
+    const index = folderPath.indexOf(MEDIA_FOLDER);
+    return folderPath.substring(index);
 }
 function transformImageLinksInTree(root, contentDir) {
     if (!contentDir)
@@ -47,9 +42,10 @@ function transformImageLinksInTree(root, contentDir) {
  * 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 customRenderFunctions - Optional; for custom rendering functions (e.g. `renderInclude`).
  * @returns Function that returns a Remark transformer
  */
-function includePlugin() {
+function includePlugin(customRenderFunctions) {
     return function includePluginImpl() {
         const processor = this;
         return function transformer(tree, file) {
@@ -59,24 +55,26 @@ function includePlugin() {
                     return;
                 const src = (_a = node.attributes) === null || _a === void 0 ? void 0 : _a.src;
                 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 content = fs_1.default.readFileSync(filename);
                     const includeFile = (0, vfile_1.default)({ path: filename, contents: content });
-                    let root = processor.parse(includeFile);
-                    if (filename.includes(SHARED_PATH_SEGMENT)) {
-                        transformImageLinksInTree(root, getContentDirPath(filename));
+                    if (customRenderFunctions === null || customRenderFunctions === void 0 ? void 0 : customRenderFunctions.renderInclude) {
+                        const root = processor.processSync(includeFile);
+                        const metadata = new Map([
+                            ['root', root],
+                            ['node', node],
+                        ]);
+                        const out = customRenderFunctions.renderInclude(metadata).get('outputDom');
+                        parent.children.splice(i, 1, { type: 'html', value: out !== null && out !== void 0 ? out : '' });
+                    }
+                    else {
+                        let root = processor.parse(includeFile);
+                        if (filename.includes(SHARED_PATH_SEGMENT)) {
+                            transformImageLinksInTree(root, getContentDirPath(filename));
+                        }
+                        const { children } = root;
+                        parent.children.splice(i + 1, 0, ...(Array.isArray(children) ? children : []));
                     }
-                    const { children } = root;
-                    const data = node.data || (node.data = {});
-                    const hast = (0, hastscript_1.default)(INCLUDE_DIRECTIVE, node.attributes || {});
-                    // node.type = 'containerDirective';
-                    node.children = Array.isArray(children) ? children : [];
-                    data.hName = INCLUDE_DIRECTIVE;
-                    data.hProperties = hast.properties;
                 }
                 catch (err) {
                     file.fail((err === null || err === void 0 ? void 0 : err.message) || `Failed to read file ${filename}`, node);

package/dist/index.js.map

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

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.5-alpha",
+  "version": "0.1.0-alpha",
   "name": "@salesforcedevs/sfdocs-remark-include-plugin",
   "description": "SFDocs remark plugin for the include directive (::include)",
   "author": "SFDocs Team",

package/src/__tests__/index.test.ts

@@ -39,7 +39,7 @@ describe('Include plugin test', () => {
         jest.restoreAllMocks();
     });
 
-    test('Include from shared folder testing', async () => {
+    test('includes markdown content from a shared file', async () => {
         fs.mkdirSync(path.join(testRoot, 'abc/xyz/guides'), { recursive: true });
         fs.mkdirSync(path.join(testRoot, 'abc/xyz/shared'), { recursive: true });
         fs.writeFileSync(
@@ -54,11 +54,12 @@ describe('Include plugin test', () => {
         `);
         const file = vfile({ path: path.join(testRoot, 'abc/xyz/guides/parent.md'), contents: content });
         const transformedHtml = await processMarkdown(file);
+
         expect(transformedHtml.contents).toContain('<h2>Include file</h2>');
         expect(transformedHtml.contents).toContain('<p>shared content</p>');
     });
 
-    test('Include from shared folder with media image (rewrites image URL)', async () => {
+    test('rewrites shared include media image URL to content media path', async () => {
         fs.mkdirSync(path.join(testRoot, 'abc/xyz/content/guides'), { recursive: true });
         fs.mkdirSync(path.join(testRoot, 'abc/xyz/content/shared'), { recursive: true });
         fs.writeFileSync(
@@ -77,11 +78,12 @@ describe('Include plugin test', () => {
             contents: content,
         });
         const transformedHtml = await processMarkdown(file);
+
         expect(transformedHtml.contents).toContain('<h2>Include file</h2>');
         expect(transformedHtml.contents).toContain(path.join(testRoot, 'abc/xyz/content/media/test.jpeg'));
     });
 
-    test('Include from shared folder with media image in locale (rewrites image URL)', async () => {
+    test('rewrites localized shared include media image URL to root content media path', async () => {
         fs.mkdirSync(path.join(testRoot, 'abc/content/ja-jp/guides'), { recursive: true });
         fs.mkdirSync(path.join(testRoot, 'abc/content/ja-jp/shared'), { recursive: true });
         fs.writeFileSync(
@@ -100,6 +102,36 @@ describe('Include plugin test', () => {
             contents: content,
         });
         const transformedHtml = await processMarkdown(file);
+
         expect(transformedHtml.contents).toContain(path.join(testRoot, 'abc/content/media/test.jpeg'));
     });
+
+    test('renderInclude replaces directive with HTML from outputDom', async () => {
+        fs.mkdirSync(path.join(testRoot, 'guides'), { recursive: true });
+        fs.writeFileSync(path.join(testRoot, 'guides/included.md'), '# Included heading');
+        const content = stripIndent(`
+            ::include{src="included.md"}
+        `);
+        const file = vfile({ path: path.join(testRoot, 'guides/parent.md'), contents: content });
+        const transformedHtml = unified()
+            .use(parse)
+            .use(directive)
+            .use(
+                includePlugin({
+                    renderInclude: () => {
+                        const m = new Map<string, string>();
+                        m.set('outputDom', '<section class="include-custom">custom block</section>');
+                        return m;
+                    },
+                }),
+            )
+            .use(remark2rehype, { allowDangerousHtml: true })
+            .use(rawHtml)
+            .use(remarkGfm)
+            .use(html)
+            .processSync(file);
+
+        expect(transformedHtml.contents).toContain('<section class="include-custom">custom block</section>');
+        expect(transformedHtml.contents).not.toContain('Included heading');
+    });
 });

package/src/index.ts

@@ -1,5 +1,4 @@
 import visit from 'unist-util-visit';
-import h from 'hastscript';
 import { Transformer } from 'unified';
 import path from 'path';
 import fs from 'fs';
@@ -9,6 +8,7 @@ const INCLUDE_DIRECTIVE = 'include';
 const LEAF_DIRECTIVE_TYPE = 'leafDirective';
 const CONTENT_FOLDER = '/content/';
 const SHARED_PATH_SEGMENT = '/shared/';
+const MEDIA_FOLDER = '/media';
 
 function getContentDirPath(curFilePath: string): string {
     const position = curFilePath.indexOf(CONTENT_FOLDER);
@@ -18,14 +18,9 @@ function getContentDirPath(curFilePath: string): string {
     return '';
 }
 
-function getSubstringAfterMedia(folderPath: string): string {
-    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 getSubstringAfterMedia(folderPath: string) {
+    const index = folderPath.indexOf(MEDIA_FOLDER);
+    return folderPath.substring(index);
 }
 
 function transformImageLinksInTree(root: any, contentDir: string): void {
@@ -47,9 +42,10 @@ function transformImageLinksInTree(root: any, contentDir: string): void {
  * 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 customRenderFunctions - Optional; for custom rendering functions (e.g. `renderInclude`).
  * @returns Function that returns a Remark transformer
  */
-function includePlugin() {
+function includePlugin(customRenderFunctions?) {
     return function includePluginImpl(): Transformer {
         const processor = this;
         return function transformer(tree: any, file: VFile): void {
@@ -57,25 +53,26 @@ function includePlugin() {
                 if (node.type !== LEAF_DIRECTIVE_TYPE || node.name !== INCLUDE_DIRECTIVE || !parent) return;
                 const src = node.attributes?.src;
                 const filename = path.resolve(file.dirname || '', src);
-                if (!fs.existsSync(filename)) {
-                    file.fail(`File not found ${filename}`, node);
-                    return;
-                }
 
                 try {
                     const content = fs.readFileSync(filename);
                     const includeFile = vfile({ path: filename, contents: content });
-                    let root = processor.parse(includeFile);
-                    if (filename.includes(SHARED_PATH_SEGMENT)) {
-                        transformImageLinksInTree(root, getContentDirPath(filename));
+                    if (customRenderFunctions?.renderInclude) {
+                        const root = processor.processSync(includeFile);
+                        const metadata = new Map([
+                            ['root', root],
+                            ['node', node],
+                        ]);
+                        const out = customRenderFunctions.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));
+                        }
+                        const { children } = root;
+                        parent.children.splice(i + 1, 0, ...(Array.isArray(children) ? children : []));
                     }
-                    const { children } = root;
-                    const data = node.data || (node.data = {});
-                    const hast = h(INCLUDE_DIRECTIVE, node.attributes || {});
-                    // node.type = 'containerDirective';
-                    node.children = Array.isArray(children) ? children : [];
-                    data.hName = INCLUDE_DIRECTIVE;
-                    data.hProperties = hast.properties;
                 } catch (err: any) {
                     file.fail(err?.message || `Failed to read file ${filename}`, node);
                 }