executablebooks / markdown-it-plugin-template Goto Github PK

Quite possibly using sphinx + myst-parser + RTD.

It would also be quite nice to have a simple way of "showcasing" the markdown source -> rendered HTML from the plugin.

Otherwise JSON files cannot be imported

Errors here:

Seems like it should be fine to add this. I can't get anything to build without it.

Fixed up the types, should be good to go.

Originally posted by @rowanc1 in executablebooks/markdown-it-dollarmath#2 (comment)

As per a discussion in the EBP slack, I have opened a PR #3, that moves this to main. The default branch/branch protection has been updated.

I will let @chrisjsewell merge that in after review of the (minor) changes.

Originally posted by @chrisjsewell in executablebooks/markdown-it-docutils#19 (comment)

I'll take your word that it works and check it out when it's built on GH pages (would be great if there was a way to preview this documentation in the PR, like I do with https://docs.readthedocs.io/en/stable/pull-requests.html)

Should also upstream this to https://github.com/executablebooks/markdown-it-plugin-template

I think that we should add this to the tsconfig:
"moduleResolution": "node"

Ran into some places where we had to change this in a downstream package.

Right now I believe the process is commenting on/off the local script and just opening this up in any webserver or file://.

It would be great to add a npm run start or dev to bring up a live reloading server on file changes (including styles where appropriate). This is more helpful for the more complicated repos like docutils.

This also means the deploy might need to go into a github action (e.g. have done that here), that would allow us to rely on the locally built package rather than the deployed npm package (e.g. not ready to release, but still want the demo updated).

Add prettier to our lint test in the ci.

I have done this as npm run lint:format in the past (as well as a npm run lint:format:fix)

See example.

Happy to make the various PRs for this and #5.

Describe the bug

When you git clone the template, npm i fails due to eslint-config-standard.

Removing eslint-config-standard from package.json appears to be a quick fix, but I am sure that is not the intended solution.

Most likely the solution is a version bump, but I'm not great at node/js in gerneral

Reproduce the bug

acn@jy-virtual-machine ~/acn> ls
deployment  markdown-it-question-answer  note_plugin  notes  start_ssh_tunnel.sh  start_vms.sh  svm0860
acn@jy-virtual-machine ~/acn> git clone [email protected]:executablebooks/markdown-it-plugin-template.git
Cloning into 'markdown-it-plugin-template'...
The authenticity of host 'github.com (140.82.121.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
remote: Enumerating objects: 157, done.
remote: Counting objects: 100% (157/157), done.
remote: Compressing objects: 100% (112/112), done.
remote: Total 157 (delta 77), reused 105 (delta 33), pack-reused 0
Receiving objects: 100% (157/157), 211.87 KiB | 704.00 KiB/s, done.
Resolving deltas: 100% (77/77), done.
acn@jy-virtual-machine ~/acn> cd markdown-it-plugin-template/
acn@jy-virtual-machine ~/a/markdown-it-plugin-template (main)> npm i
Command 'npm' not found, but can be installed with:
sudo apt install npm
acn@jy-virtual-machine ~/a/markdown-it-plugin-template (main) [127]> nvm use lts
Now using Node v18.12.1 (npm 8.19.2) ~/.local/share/nvm/v18.12.1/bin/node
acn@jy-virtual-machine ~/a/markdown-it-plugin-template (main)> npm i
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/eslint-plugin-promise
npm ERR!   dev eslint-plugin-promise@"^6.0.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer eslint-plugin-promise@"^4.2.1 || ^5.0.0" from [email protected]
npm ERR! node_modules/eslint-config-standard
npm ERR!   dev eslint-config-standard@"^16.0.3" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: [email protected]
npm ERR! node_modules/eslint-plugin-promise
npm ERR!   peer eslint-plugin-promise@"^4.2.1 || ^5.0.0" from [email protected]
npm ERR!   node_modules/eslint-config-standard
npm ERR!     dev eslint-config-standard@"^16.0.3" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! See /home/acn/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/acn/.npm/_logs/2022-11-08T12_47_32_108Z-debug-0.log

List your environment

Using Fish on Ubuntu

acn@jy-virtual-machine ~/a/markdown-it-plugin-template (main)> uname -a
Linux jy-virtual-machine 5.15.0-52-generic #58-Ubuntu SMP Thu Oct 13 08:03:55 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
acn@jy-virtual-machine ~/a/markdown-it-plugin-template (main) [1]> npm --version
8.19.2
acn@jy-virtual-machine ~/a/markdown-it-plugin-template (main)> node --version
v18.12.1

Certainly compared to Python (one distribution works for all v3.x), JS/TS is a bit of a mess when it comes to packaging libraries: not only do you need to think about the version/format of javascript (and compatibility with third-party modules), but also node vs browser compatibility.

Essentially CommonJS modules are a legacy format, that many third party packages still use, whereas ES modules are now the ~official standard and "future" of javascript (and are now basically supported in all browsers: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules, see also https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/).
Again comparing to Python, it feels like JS/TS is in a similar situation to when python packages were transitioning from v2 to v3 (and so support was necessary for both).

Using rollup you can actually target multiple build formats:

• https://rollupjs.org/guide/en/#outputformat (default esm)
• https://rollupjs.org/guide/en/#why-are-es-modules-better-than-commonjs-modules

Currently, I have it set to do a "hybrid" build with: https://github.com/executablebooks/markdown-it-plugin-template/blob/master/rollup.config.js, and in package.json pointing to either with:

This is essentially what is recommended here, but then here it mentions a danger in "double transpiling".

Additionally confusing, is what to target in the tsconfig:

and also how babel fits in with rollup, and if @rollup/plugin-babel is actually needed (if you remove this plugin, it still builds fine at present):

It is of note that markdown-it itself uses the umd format (amd, cjs and iife), in its rollup config: https://github.com/markdown-it/markdown-it/blob/064d602c6890715277978af810a903ab014efc73/support/rollup.config.js#L13

Also a consideration of what is required for unpkg: mjackson/unpkg#34

Here is also a bunch of links about CommonJS vs ES Modules and building hybrid packages:

• rollup/rollup#3514
• https://redfin.engineering/node-modules-at-war-why-commonjs-and-es-modules-cant-get-along-9617135eeca1
• https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html
• https://blog.logrocket.com/es-modules-in-node-today/
• https://2ality.com/2019/10/hybrid-npm-packages.html