Merge pull request #117 from DavidWells/cursor/initial-codebase-assessment-4791

Initial codebase assessment

Author: DavidWells

README.md

@@ -59,7 +59,7 @@ This `README.md` is generated with `markdown-magic` [view the raw file](https://
 </details>
 <!-- ⛔️ MD-MAGIC-EXAMPLE:END -->
 
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START FILE src=./docs/1_Getting-Started.md -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START FILE src=./docs/1-getting-started.md -->
 ## Install
 
 **Via npm**
@@ -127,7 +127,7 @@ In NPM scripts, `npm run docs` would run the markdown magic and parse all the `.
 },
 ```
 
-If you have a `markdown.config.js` file where `markdown-magic` is invoked, it will automatically use that as the configuration unless otherwise specified by `--config` flag.
+If you have an `md.config.js` or `markdown.config.js` file where `markdown-magic` is invoked, it will automatically use that as the configuration unless otherwise specified by `--config` flag.
 
 ### Running programmatically
 
@@ -191,7 +191,7 @@ jobs:
 - [markdown-autodocs](https://github.com/dineshsonachalam/markdown-autodocs) - Auto-generate docs from code
 <!-- ⛔️ MD-MAGIC-EXAMPLE:END *-->
 
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (FILE:src=./docs/Syntax.md) -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (FILE:src=./docs/2-syntax-reference.md) -->
 ## Syntax Examples
 
 There are various syntax options. Choose your favorite.
@@ -669,7 +669,7 @@ const config = {
       return '**⊂◉‿◉つ**'
     },
     lolz() {
-      return `This section was generated by the cli config markdown.config.js file`
+      return `This section was generated by the cli config md.config.js file`
     },
     /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
     pluginExample: require('./plugin-example')({ addNewLine: true }),

docs/1-getting-started.md

@@ -18,9 +18,9 @@ npm install markdown-magic --save-dev
 Add comment blocks to your markdown files to define where content should be generated:
 
 ```md
-<!-- doc-gen remote url=http://url-to-raw-md-file.md -->
+<!-- docs remote url=http://url-to-raw-md-file.md -->
 This content will be dynamically replaced from the remote url
-<!-- end-doc-gen -->
+<!-- /docs -->
 ```
 
 Then run markdown-magic to process your files.
@@ -44,7 +44,7 @@ md-magic
 
 Process specific files with custom config:
 ```bash
-md-magic --path '**/*.md' --config ./config.file.js
+md-magic --files '**/*.md' --config ./config.file.js
 ```
 
 ### NPM Scripts Integration
@@ -54,7 +54,7 @@ Add to your `package.json`:
 ```json
 {
   "scripts": {
-    "docs": "md-magic --path '**/*.md'"
+    "docs": "md-magic --files '**/*.md'"
   }
 }
 ```
@@ -63,7 +63,7 @@ Run with: `npm run docs`
 
 ### Configuration File
 
-Create a `markdown.config.js` file in your project root for automatic configuration:
+Create an `md.config.js` or `markdown.config.js` file in your project root for automatic configuration:
 
 ```js
 module.exports = {

docs/2-syntax-reference.md

@@ -14,11 +14,11 @@ All transform blocks follow this basic structure:
 ```md
 <!-- matchWord transformName [options] -->
 Content to be replaced
-<!-- end-matchWord -->
+<!-- /matchWord -->
 ```
 
 Where:
-- `matchWord` is the opening keyword (default: `doc-gen`)
+- `matchWord` is the opening keyword (default: `docs`)
 - `transformName` is the name of the transform to apply
 - `options` are optional parameters for the transform
 - Content between the tags will be replaced by the transform output
@@ -30,74 +30,74 @@ Where:
 The simplest form - just specify the transform name and options:
 
 ```md
-<!-- doc-gen transformName optionOne='hello' optionTwo='there' -->
+<!-- docs transformName optionOne='hello' optionTwo='there' -->
 content to be replaced
-<!-- end-doc-gen -->
+<!-- /docs -->
 ```
 
 ### Curly Braces
 
 Wrap the transform name in curly braces:
 
 ```md
-<!-- doc-gen {transformName} optionOne='hello' optionTwo='there' -->
+<!-- docs {transformName} optionOne='hello' optionTwo='there' -->
 content to be replaced
-<!-- end-doc-gen -->
+<!-- /docs -->
 ```
 
 ### Square Brackets
 
 Wrap the transform name in square brackets:
 
 ```md
-<!-- doc-gen [transformName] optionOne='hello' optionTwo='there' -->
+<!-- docs [transformName] optionOne='hello' optionTwo='there' -->
 content to be replaced
-<!-- end-doc-gen -->
+<!-- /docs -->
 ```
 
 ### Parentheses
 
 Wrap the transform name in parentheses:
 
 ```md
-<!-- doc-gen (transformName) optionOne='hello' optionTwo='there' -->
+<!-- docs (transformName) optionOne='hello' optionTwo='there' -->
 content to be replaced
-<!-- end-doc-gen -->
+<!-- /docs -->
 ```
 
 ### Function Style
 
 Use function-like syntax with parentheses for options:
 
 ```md
-<!-- doc-gen transformName(
+<!-- docs transformName(
   foo='bar'
   baz=['qux', 'quux']
 ) -->
 content to be replaced
-<!-- end-doc-gen -->
+<!-- /docs -->
 ```
 
 ## Option Formats
 
 ### String Options
 ```md
-<!-- doc-gen transform option='string value' -->
+<!-- docs transform option='string value' -->
 ```
 
 ### Boolean Options
 ```md
-<!-- doc-gen transform enabled=true disabled=false -->
+<!-- docs transform enabled=true disabled=false -->
 ```
 
 ### Array Options
 ```md
-<!-- doc-gen transform items=['one', 'two', 'three'] -->
+<!-- docs transform items=['one', 'two', 'three'] -->
 ```
 
 ### Multiple Options
 ```md
-<!-- doc-gen transform 
+<!-- docs transform 
   url='https://example.com'
   format='json'
   cache=true
@@ -122,7 +122,7 @@ Then use it in your markdown:
 ```md
 <!-- auto-gen transformName -->
 content to be replaced
-<!-- end-auto-gen -->
+<!-- /auto-gen -->
 ```
 
 ## Best Practices

docs/3-plugin-development.md

@@ -9,38 +9,40 @@ Learn how to create custom transforms (plugins) for markdown-magic to extend its
 
 ## Transform Basics
 
-A transform is a function that takes content and options, then returns processed content:
+A transform is a function that takes a single API object and returns processed content:
 
 ```js
 // Basic transform structure
-function myTransform(content, options, config) {
+function myTransform(api) {
+  const { content, options, settings } = api
   // Process the content
   return processedContent
 }
 ```
 
-### Parameters
+### API Parameters
 
 - `content`: The content between the comment blocks
 - `options`: Parsed options from the comment block
-- `config`: Global markdown-magic configuration
+- `srcPath`: Current source markdown file path
+- `settings`: Global markdown-magic configuration
 
 ## Creating Your First Transform
 
 ### Simple String Transform
 
 ```js
 // transforms/greeting.js
-module.exports = function greeting(content, options) {
+module.exports = function greeting({ options }) {
   const name = options.name || 'World'
   return `Hello, ${name}!`
 }
 ```
 
 Usage:
 ```md
-<!-- doc-gen greeting name='Alice' -->
-<!-- end-doc-gen -->
+<!-- docs greeting name='Alice' -->
+<!-- /docs -->
 ```
 
 Result: `Hello, Alice!`
@@ -52,7 +54,7 @@ Result: `Hello, Alice!`
 const fs = require('fs')
 const path = require('path')
 
-module.exports = function include(content, options) {
+module.exports = function include({ content, options }) {
   if (!options.src) {
     throw new Error('include transform requires "src" option')
   }
@@ -70,8 +72,8 @@ module.exports = function include(content, options) {
 
 Usage:
 ```md
-<!-- doc-gen include src='./snippets/example.md' -->
-<!-- end-doc-gen -->
+<!-- docs include src='./snippets/example.md' -->
+<!-- /docs -->
 ```
 
 ## Async Transforms
@@ -82,7 +84,7 @@ For operations that require network requests or file system operations:
 // transforms/fetchContent.js
 const fetch = require('node-fetch')
 
-module.exports = async function fetchContent(content, options) {
+module.exports = async function fetchContent({ content, options }) {
   if (!options.url) {
     throw new Error('fetchContent requires "url" option')
   }
@@ -108,7 +110,7 @@ module.exports = async function fetchContent(content, options) {
 // transforms/template.js
 const mustache = require('mustache')
 
-module.exports = function template(content, options) {
+module.exports = function template({ content, options }) {
   const template = options.template || content
   const data = {
     ...options.data,
@@ -126,7 +128,7 @@ module.exports = function template(content, options) {
 // transforms/codeStats.js
 const fs = require('fs')
 
-module.exports = function codeStats(content, options) {
+module.exports = function codeStats({ options }) {
   if (!options.src) {
     throw new Error('codeStats requires "src" option')
   }
@@ -149,7 +151,7 @@ module.exports = function codeStats(content, options) {
 
 ```js
 // transforms/tableOfContents.js
-module.exports = function tableOfContents(content, options) {
+module.exports = function tableOfContents({ content, options }) {
   const format = options.format || 'markdown'
   const maxDepth = parseInt(options.maxDepth) || 3
   const minDepth = parseInt(options.minDepth) || 1
@@ -194,7 +196,7 @@ function extractHeadings(content, minDepth, maxDepth) {
 ### In Configuration File
 
 ```js
-// markdown.config.js
+// md.config.js
 const greeting = require('./transforms/greeting')
 const include = require('./transforms/include')
 
@@ -215,7 +217,7 @@ import markdownMagic from 'markdown-magic'
 
 const config = {
   transforms: {
-    myTransform: (content, options) => {
+    myTransform: ({ content, options }) => {
       return `Processed: ${content}`
     }
   }
@@ -231,7 +233,7 @@ markdownMagic('./docs/*.md', config)
 Markdown-magic automatically parses options from the comment block:
 
 ```md
-<!-- doc-gen myTransform 
+<!-- docs myTransform 
   stringOption='value'
   numberOption=42
   boolOption=true
@@ -242,7 +244,7 @@ Markdown-magic automatically parses options from the comment block:
 
 Access in transform:
 ```js
-module.exports = function myTransform(content, options) {
+module.exports = function myTransform({ options }) {
   console.log(options.stringOption) // 'value'
   console.log(options.numberOption) // 42
   console.log(options.boolOption)   // true
@@ -254,7 +256,7 @@ module.exports = function myTransform(content, options) {
 ### Default Options
 
 ```js
-module.exports = function myTransform(content, options) {
+module.exports = function myTransform({ options }) {
   const defaults = {
     format: 'markdown',
     includeTitle: true,
@@ -272,7 +274,7 @@ module.exports = function myTransform(content, options) {
 ### Validation
 
 ```js
-module.exports = function strictTransform(content, options) {
+module.exports = function strictTransform({ options }) {
   // Required options
   const required = ['url', 'format']
   for (const opt of required) {
@@ -294,7 +296,7 @@ module.exports = function strictTransform(content, options) {
 ### Graceful Degradation
 
 ```js
-module.exports = async function robustTransform(content, options) {
+module.exports = async function robustTransform({ content, options }) {
   try {
     // Attempt primary operation
     return await primaryOperation(options)
@@ -353,8 +355,8 @@ describe('transform integration', () => {
   beforeEach(() => {
     // Reset test file
     fs.writeFileSync(testFile, `
-<!-- doc-gen greeting name='Test' -->
-<!-- end-doc-gen -->
+<!-- docs greeting name='Test' -->
+<!-- /docs -->
     `.trim())
   })