Skip to content

Initial codebase assessment #117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DavidWells merged 3 commits into from
Feb 21, 2026
Merged

Initial codebase assessment #117

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa5bc41
fix core transform reliability and align docs
cursoragent Feb 21, 2026
0b8a16b
Update packages/block-transformer/src/index.js
DavidWells Feb 21, 2026
f1394c4
fix(block-replacer): update test to reflect preloaded-content behavior
github-actions[bot] Feb 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 }),
Expand Down
10 changes: 5 additions & 5 deletions docs/1-getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -54,7 +54,7 @@ Add to your `package.json`:
```json
{
"scripts": {
"docs": "md-magic --path '**/*.md'"
"docs": "md-magic --files '**/*.md'"
}
}
```
Expand All @@ -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 = {
Expand Down
34 changes: 17 additions & 17 deletions docs/2-syntax-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
48 changes: 25 additions & 23 deletions docs/3-plugin-development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!`
Expand All @@ -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')
}
Expand All @@ -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
Expand All @@ -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')
}
Expand All @@ -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,
Expand All @@ -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')
}
Expand All @@ -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
Expand Down Expand Up @@ -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')

Expand All @@ -215,7 +217,7 @@ import markdownMagic from 'markdown-magic'

const config = {
transforms: {
myTransform: (content, options) => {
myTransform: ({ content, options }) => {
return `Processed: ${content}`
}
}
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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) {
Expand All @@ -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)
Expand Down Expand Up @@ -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())
})

Expand Down
Loading
Loading