Original Question
How do I correctly "configure" the (unified, remark, remark-lint) remark-lint-no-undefined-references plugin/rule "allow" option for use with the remark-cli?
My goal is to configure the rule to ignore the Azure DevOps Wiki's non-standard table of contents tag, [[_TOC_]]
. My simplified setup entails:
- All packages globally installed. Probably not relevant.
- A parent folder in which I have:
- A
package.json
file. - A
Test
folder containing just the oneTest.md
file whose only content is this one line[[_TOC_]]
.
- A
- From a command prompt whose working folder is the aforementioned parent folder, I execute:
remark Test
Default Operation
The default operation, i.e. just the plugin/rule specified in the package.json
file, returns the expected warning. This is, presumably, due to the non-standard tag, [[_TOC_]]
. This is the warning I wish to turn off.
package.json (default)
{
"remarkConfig": {
"plugins": [
"remark-lint-no-undefined-references"
]
}
}
Execution and Expected Warning (default)
C:\..>remark Test
test\Test.md
1:1-1:10 warning Found reference to undefined definition no-undefined-references remark-lint
1:2-1:9 warning Found reference to undefined definition no-undefined-references remark-lint
‼ 2 warnings
What I've tried
I've tried to adapt remark-lint-no-undefined-references API example and Configuration, 'rules can be configured in one standard way' to my package.json
file. After much trial and error, I've ended up with this seemingly valid json:
package.json
{
"remarkConfig": {
"plugins": [
"remark-lint-no-undefined-references", [1, {
"allow": ["[[_TOC_]]"]
}]
]
}
}
The Online JSON Viewer and JSONLint indicate it's valid JSON. However, remark-cli yields this error. Other variations yielded different errors. I am stumped.
C:\..>
Test\Test.md
1:1 error Error: Cannot parse file `package.json`
Expected preset, not `1`
at Error (file:///C:/Users/scott.welker/AppData/Roaming/npm/node_modules/remark-cli/node_modules/fault/index.js:39:12)
at file:///C:/Users/scott.welker/AppData/Roaming/npm/node_modules/remark-cli/node_modules/unified-engine/lib/find-up.js:190:15
at done (file:///C:/Users/scott.welker/AppData/Roaming/npm/node_modules/remark-cli/node_modules/trough/index.js:145:7)
× 1 error
Update 03/14/2022
I've made some progress thanks to a bit of help on GitHub Issue (#210). However, that was not the right avenue and it is closed. My issue remains.
A Few Things are Apparent
- My initially inferred JSON,
package.json
, is incorrect. See Hacked my JSON below. - I failed to appreciate how the non-standard Azure DevOps Wiki table of contents tag,
[[_TOC_]]
, is interpreted. See Tag Interpretation (console-log) following. - My inferred
package.json
seemingly remains incorrect. See My JSON Must Still be Wrong below.
Hacked my JSON
To overcome ...Error: Cannot parse file 'package.json', Expected preset, not '1'
I hacked my file so that I now have the following. This change overcomes the error and enables me to continue but it is still seemingly incorrect. See My JSON Must Still be Wrong.
package.json file
{
"remarkConfig": {
"plugins": [
"remark-lint-no-undefined-references", {
"allow": ["_TOC_", "[_TOC_]"]
}
]
}
}
Tag Interpretation (console.log)
After hacking my JSON, I added a recommended console.log (..\npm\node_modules\remark-lint-no-undefined-references\index.js
) of id
. This reveals that the linting interprets the table of contents tag as two separate bits of concerning markdown, _TOC_
and [_TOC_]
. I did not appreciate this. However, the findings below suggest this may not be a problem. See My JSON Must Still be Wrong.
remark-cli
C:\..>remark Test
Id: _TOC_
Id: [_TOC_]
Test\Test.md
1:1-1:10 warning Found reference to undefined definition no-undefined-references remark-lint
1:2-1:9 warning Found reference to undefined definition no-undefined-references remark-lint
‼ 2 warnings
My JSON Must Still be Wrong
Referring to another location in the source here (line 126), when I replace that const allow
definition with this hard-coded declaration, const allow = new Set(["_TOC_", "[_TOC_]"])
, I get the desired behavior. E.g.:
remark-cli
C:\...>remark Test
Test\Test.md: no issues found
Next Steps:
- See whether I can forgo the
package.json
and instead use pure javascript. Either my JSON is incorrect or it isn't being interpreted correctly. - Continue to futz with the JSON. What I've inferred may well be wrong.
- The following guess also fails to suppress the unwanted warnings:
package.json
{
"remarkConfig": {
"plugins": [
"remark-lint-no-undefined-references", [{
"allow": ["_TOC_", "[_TOC_]"]
}]
]
}
}
Update 03/28/2022
CAUTION! |
---|
While the setup in this update is valid, the Test.js example code is flawed. See 03/30/2022 Update below. |
Following up on "Next Step, see whether I can forgo the package.json
and instead use pure javascript."
I seem to have made it work except it suppresses all warnings, not just the few (two) that I am targeting. More development and testing is needed.
New Setup
- A new parent Node.js application folder in which I have:
- Opted to re-install all packages, and some new ones, but not globally (this time):
npm install to-vfile
npm install vfile-reporter
npm install remark
npm install remark-lint
npm install remark-lint-no-undefined-references
- The
node_modules
folder. Created and populated by npm installs (dependencies). - A
package.json
file. Created and populated by npm installs. - A
package-lock.json
file. Created and populated by npm installs. - A copy of the same
Test
folder containing just the oneTest.md
file whose only content is this one line[[_TOC_]]
.
- Opted to re-install all packages, and some new ones, but not globally (this time):
- From a command prompt whose working folder is the aforementioned parent folder, I execute my new node/javascript code:
node Test.js
See following. Code comments illustrate the unexpected suppression of all warnings, even those not targeted.
Test.js
WARNING! This code is incorrect. See the 03/30/2022 Update below.
import {reporter} from 'vfile-reporter'
import {remark} from 'remark'
import remarkLint from 'remark-lint'
import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references'
import {read} from 'to-vfile'
main()
async function main() {
const file = await remark()
.use(remarkLint)
// This useage results in the expected warnings, '...Found reference to undefined definition...'
.use(remarkLintNoUndefinedReferences)
// This usage suppresses the warnings, as desired. However, note the next usage.
//.use(remarkLintNoUndefinedReferences[ { allow: [ '_TOC_', '[_TOC_]' ] }])
// This usage also suppresses the warning but it shoud not have done so.
//.use(remarkLintNoUndefinedReferences[ { allow: [ '...', '…' ] }])
// This usage (and related tests) seem to illustrate that anything in the allowed array suppresses all warnings.
//.use(remarkLintNoUndefinedReferences[ { allow: [ '' ] }])
.process(await read('.\\Test\\Test.md'))
console.error(reporter(file))
}
Update 03/30/2022
Here is a corrected Test.js
file where my invalid usages are commented out, marked WRONG
, and the two correct usages are marked GOOD
. The final usage corrects mistakes made in my 03/28/2022 update. I now have a working javascript version. I just need to adapt this known working version to the remark-cli's package.json
file. Getting very close.
I arrived at this CORRECT
, working usage through trial and error. My trial and error was aided by adding console.log()
statements to the ..\remark-lint-no-undefined-references\index.js
source and tweaking my javascript code as guided by repeated re-reading of the remark-lint Configure section.
Test.js
import {reporter} from 'vfile-reporter'
import {remark} from 'remark'
import remarkLint from 'remark-lint'
import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references'
import {read} from 'to-vfile'
main()
async function main() {
const file = await remark()
.use(remarkLint)
// WRONG: This usage seems to suppress the warnings, as desired. However, note the next usage.
//.use(remarkLintNoUndefinedReferences[ { allow: [ '_TOC_', '[_TOC_]' ] }])
// WRONG: This usage also seems to supresses the warnings but, it shoud not have done so.
//.use(remarkLintNoUndefinedReferences[ { allow: [ '...', '…' ] }])
// WRONG: This usage (and related tests) seem to illustrate that anything in the allowed array suppresses all warnings.
//.use(remarkLintNoUndefinedReferences[ { allow: [ '' ] }])
// GOOD: This usage results in the expected warnings, '...Found reference to undefined definition...'
//.use(remarkLintNoUndefinedReferences)
// GOOD: This usage seems to be correct!!
.use(remarkLintNoUndefinedReferences, [1, { allow: [ '_TOC_', '[_TOC_]' ] }])
.process(await read('.\\Test\\Test.md'))
console.error(reporter(file))
}
Execution and Output
C:\..>node Test.js
DEBUG remarkTest: allow contains 2 items.
DEBUG remarkTest Id: '_TOC_'
DEBUG remarkTest Id: '[_TOC_]'
.\Test\Test.md: no issues found
The
package.json
below correctly "configures" the remark-lint-no-undefined-references plugin/rule "allow" option for use with remark-cli.package.json
"dependencies". See following.package.json
I arrived at this by working from my 03/30/2022 update and futzing with varying syntax illustrated in the Unified Engine, Configuration, Schema section.
Again, my goal is to configure the rule to ignore the Azure DevOps Wiki's non-standard table of contents tag,
[[_TOC_]]
.Execution and Output
Note: my debug
console.log(...)
remains in place.