markdown-magic 3.5.0 → 3.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdown-magic",
-  "version": "3.5.0",
+  "version": "3.6.2",
   "description": "Automatically update markdown files with content from external sources",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -9,6 +9,7 @@ const tocTransform = require('./transforms/toc')
 const sectionTocTransform = require('./transforms/sectionToc')
 const wordCountTransform = require('./transforms/wordCount')
 const remoteTransform = require('./transforms/remote')
+const installTransform = require('./transforms/install')
 const { getSyntaxInfo } = require('./utils/syntax')
 const { onlyUnique, getCodeLocation, pluralize } = require('./utils')
 const { readFile, resolveOutputPath, resolveFlatPath } = require('./utils/fs')
@@ -34,7 +35,8 @@ const defaultTransforms = {
   TOC: tocTransform,
   sectionToc: sectionTocTransform,
   wordCount: wordCountTransform,
-  remote: remoteTransform
+  remote: remoteTransform,
+  install: installTransform,
 }
 
 const defaultOptions = {

package/src/transforms/code/index.js

@@ -3,7 +3,13 @@ const path = require('path')
 const { remoteRequest } = require('../../utils/remoteRequest')
 const { isLocalPath } = require('../../utils/fs')
 const { deepLog } = require('../../utils/logs')
-const { getLineCount, getTextBetweenLines, stripMultiLineDoubleDashComments, stripHTMLComments } = require('../../utils/text')
+const { 
+  getLineCount,
+  getTextBetweenLines,
+  stripMultiLineDoubleSlashComments,
+  stripSingleLineDoubleSlashComments,
+  stripHTMLComments
+} = require('../../utils/text')
 const { resolveGithubContents, isGithubLink } = require('./resolve-github-file')
 
 const GITHUB_LINK = /https:\/\/github\.com\/([^/\s]*)\/([^/\s]*)\/blob\//
@@ -158,7 +164,7 @@ module.exports = async function CODE(api) {
     const endLineIndex = lines.findIndex(line => line.includes(`CODE_SECTION:${id}:END`));
     const endLine = endLineIndex !== -1 ? endLineIndex : lines.length - 1;
     // console.log('startLine', startLine)
-    // console.log('endLineendLine', endLine)
+    // console.log('endLine', endLine)
     if (startLine === -1 && endLine === -1) {
       throw new Error(`Missing ${id} code section from ${codeFilePath}`)
     }
@@ -179,10 +185,16 @@ module.exports = async function CODE(api) {
   if (options.header) {
     header = `\n${options.header}`
   }
+
+  if (options.trimSingleLineComments) {
+    if (syntax === 'js' || syntax === 'ts' || syntax === 'javascript' || syntax === 'typescript') {
+      code = stripSingleLineDoubleSlashComments(code)
+    }
+  }
   
   if (options.trimDeadCode) {
     if (syntax === 'js' || syntax === 'ts' || syntax === 'javascript' || syntax === 'typescript') {
-      code = stripMultiLineDoubleDashComments(code)
+      code = stripMultiLineDoubleSlashComments(code)
     } else if (syntax === 'html') {
       code = stripHTMLComments(code, { multilineOnly: true })
     }

package/src/transforms/file.js

@@ -1,8 +1,7 @@
 const path = require('path')
 const fs = require('fs')
 const isLocalPath = require('is-local-path')
-const { findFrontmatter } = require('@davidwells/md-utils/find-frontmatter')
-const { removeLeadingH1 } = require('@davidwells/md-utils/string-utils')
+const { formatMd } = require('../utils/format-md')
 
 module.exports = function FILE(api) {
   /*
@@ -32,27 +31,11 @@ module.exports = function FILE(api) {
   // trim leading and trailing spaces/line breaks in code and keeps the indentation of the first non-empty line
   fileContents = fileContents.replace(/^(?:[\t ]*(?:\r?\n|\r))+|\s+$/g, '')
 
-  if (options.removeLeadingH1) {
-    fileContents = removeLeadingH1(fileContents)
-  }
-
-  const isMarkdown = path.extname(options.src).toLowerCase() === '.md'
-  // Shift headers up or down by the specified number of levels if shiftHeaders is enabled and file is markdown
-  if (options.shiftHeaders && isMarkdown) {
-    fileContents = fileContents.replace(/^(#{1,6})\s/gm, (match, hashes) => {
-      const currentLevel = hashes.length;
-      const shiftAmount = options.shiftHeaders;
-      const newLevel = Math.max(1, Math.min(6, currentLevel + shiftAmount));
-      return '#'.repeat(newLevel) + ' ';
-    })
-  }
-
-  /* automatically trim frontmatter if file is markdown */
-  if (isMarkdown && options.trimFrontmatter !== false) {
-    const frontmatter = findFrontmatter(fileContents)
-    if (frontmatter && frontmatter.frontMatterRaw) {
-      fileContents = fileContents.replace(frontmatter.frontMatterRaw, '')
-    }
+  const ext = path.extname(options.src).toLowerCase()
+  const isMarkdown = ext === '.md' || ext === '.markdown' || ext === '.mdown' || ext === '.mdx'
+  
+  if (isMarkdown) {
+    fileContents = formatMd(fileContents, options)
   }
 
   if (options.textBefore) {

package/src/transforms/index.js

@@ -3,6 +3,7 @@ const file = require('./file')
 const remoteContent = require('./remote')
 const toc = require('./toc')
 const sectionToc = require('./sectionToc')
+const install = require('./install')
 
 const transforms = {
   /**
@@ -111,6 +112,32 @@ const transforms = {
    * @return {string} Updated content to place in the content block
    */
   REMOTE: remoteContent,
+  /**
+   * ### > install
+   *
+   * Generate installation instructions in a markdown table format
+   *
+   * **Options:**
+   * - `packageName` (optional): The name of the package to install. If not provided, will try to read from package.json
+   * - `isDev` (optional): Whether to install the package as a dev dependency. Default `false`
+   * - `header` (optional): The header to use for the installation instructions. Default `# Installation`
+   * - `body` (optional): The body to use for the installation instructions. Default `Install the \`${packageName}\` cli using your favorite package manager.`
+   *
+   * **Example:**
+   * ```md
+   * <!-- doc-gen install -->
+   * Installation instructions will be generated here
+   * <!-- end-doc-gen -->
+   * ```
+   *
+   * Default `matchWord` is `doc-gen`
+   *
+   * ---
+   * @param {string} content The current content of the comment block
+   * @param {object} options The options passed in from the comment declaration
+   * @return {string} Updated content to place in the content block
+   */
+  install: install,
 }
 
 module.exports = transforms

package/src/transforms/install.js

@@ -0,0 +1,72 @@
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * ### > INSTALL
+ *
+ * Generate installation instructions in a markdown table format
+ *
+ * **Options:**
+ * - `packageName` (optional): The name of the package to install. If not provided, will try to read from package.json
+ *
+ * **Example:**
+ * ```md
+ * <!-- doc-gen INSTALL packageName=my-package -->
+ * Installation instructions will be generated here
+ * <!-- end-doc-gen -->
+ * ```
+ *
+ * Default `matchWord` is `doc-gen`
+ *
+ * ---
+ * @param {string} content The current content of the comment block
+ * @param {object} options The options passed in from the comment declaration
+ * @return {string} Updated content to place in the content block
+ */
+function install(api) {
+  console.log('INSTALL API', api)
+  const { options } = api
+  const { isDev = false } = options
+  let packageName = options.packageName
+
+  // If no package name provided, try to read from package.json
+  if (!packageName) {
+    try {
+      const packageJsonPath = path.join(process.cwd(), 'package.json')
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+      packageName = packageJson.name
+    } catch (error) {
+      console.log('Could not read package.json:', error.message)
+      return 'Error: No package name provided and could not read from package.json'
+    }
+  }
+
+  let header = '# Installation'
+  if (options.header) {
+    header = (options.header.startsWith('#')) ? options.header : `# ${options.header}`
+  }
+  header = `${header}\n\n`
+
+  let body = `Install the \`${packageName}\` cli using your favorite package manager.`
+  if (options.body) {
+    body = (options.body.startsWith('\n')) ? options.body : `\n${options.body}`
+  }
+  body = `${body}\n`
+
+  if (!packageName) {
+    return 'Error: No package name provided'
+  }
+
+  const flag = isDev ? ' -D' : ' '
+  const space = isDev ? '  ' : ''
+
+  return `${header}${body}
+| package manager | command |
+| --------------- | ------- |
+| npm  | \`npm install ${packageName}${flag}\` |
+| pnpm | \`pnpm add ${packageName}${flag}\`    |
+| yarn | \`yarn add ${packageName}${flag}\`    |
+| bun  | \`bun install ${packageName}\`${space}  |`
+}
+
+module.exports = install

package/src/transforms/remote.js

@@ -1,18 +1,30 @@
+const path = require('path')
 const { remoteRequest } = require('../utils/remoteRequest')
+const { formatMd } = require('../utils/format-md')
 
 module.exports = async function REMOTE(api) {
   // console.log('REMOTE api', api)
   const { options, content, settings } = api
   const { regex } = settings
+  const remoteUrl = options.url || options.src || options.URL || options.Url
 
   // console.log('MAKE REMOTE REQUEST')
-  const remoteContent = await remoteRequest(options.url, settings, api.srcPath)
+  let remoteContent = await remoteRequest(remoteUrl, settings, api.srcPath)
   if (!remoteContent) {
     return content
   }
+
+  const ext = path.extname(remoteUrl).toLowerCase()
+  const isMarkdown = ext === '.md' || ext === '.markdown' || ext === '.mdown' || ext === '.mdx'
+  
+  if (isMarkdown) {
+    remoteContent = formatMd(remoteContent, options)
+  }
+
   if (options.keepComments) {
     return remoteContent
   }
+  
   // console.log('REMOTE', remoteContent)
   return remoteContent.replace(regex.open, '').replace(regex.close, '')
 }

package/src/utils/format-md.js

@@ -0,0 +1,33 @@
+const { findFrontmatter } = require('@davidwells/md-utils/find-frontmatter')
+const { removeLeadingH1 } = require('@davidwells/md-utils/string-utils')
+
+function formatMd(content, options = {}) {
+  let fileContents = content
+  if (options.removeLeadingH1 || options.stripFirstH1) {
+    fileContents = removeLeadingH1(fileContents)
+  }
+  
+  // Shift headers up or down by the specified number of levels if shiftHeaders is enabled and file is markdown
+  if (options.shiftHeaders) {
+    fileContents = fileContents.replace(/^(#{1,6})\s/gm, (match, hashes) => {
+      const currentLevel = hashes.length;
+      const shiftAmount = Number(options.shiftHeaders);
+      const newLevel = Math.max(1, Math.min(6, currentLevel + shiftAmount));
+      return '#'.repeat(newLevel) + ' ';
+    })
+  }
+
+  /* automatically trim frontmatter if file is markdown */
+  if (options.trimFrontmatter !== false) {
+    const frontmatter = findFrontmatter(fileContents)
+    if (frontmatter && frontmatter.frontMatterRaw) {
+      fileContents = fileContents.replace(frontmatter.frontMatterRaw, '')
+    }
+  }
+
+  return fileContents
+}
+
+module.exports = {
+  formatMd
+}

package/src/utils/text.js

@@ -197,10 +197,14 @@ function stripComments(str, syntax = 'md') {
 
 
 // https://regex101.com/r/nCnt2J/1
-function stripMultiLineDoubleDashComments(str = '') {
+function stripMultiLineDoubleSlashComments(str = '') {
   return str.replace(/(?:\n\s*\/\/.*){2,}/g, '')
 }
 
+function stripSingleLineDoubleSlashComments(str = '') {
+  return str.replace(/\/\/.*$/gm, '')
+}
+
 // https://regex101.com/r/plpXmr/1
 function stripOutMultilineJsComments(str = '') {
   return str.replace(/\/\*[\s\S]+?\*\/\s*\n?/g, (match) => {
@@ -351,7 +355,8 @@ module.exports = {
   dedentString,
   stripComments,
   convertCommentSyntax,
-  stripMultiLineDoubleDashComments,
+  stripSingleLineDoubleSlashComments,
+  stripMultiLineDoubleSlashComments,
   stripHTMLComments,
   // stripCommentBlockJS,
   trimString,