docs: update Parcel MDX plugin for MDX 3 #2523
Conversation
Signed-off-by: South Drifted <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
❗ Your organization needs to install the Codecov GitHub app to enable full functionality. Additional details and impacted files@@ Coverage Diff @@
## main #2523 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 23 23
Lines 2693 2712 +19
Branches 2 2
=========================================
+ Hits 2693 2712 +19 ☔ View full report in Codecov by Sentry. |
|
Thanks for sharing @TechQuery! General feedback on what gets included in the plugins/guides list:
source: syntax-tree/hast#24 (comment) It looks like there aren't any types or tests included in the repository.
|
|
Thanks for quick reviewing @ChristianMurphy !
🚧This is my first Parcel plugin, I'm learning the best practice of developing Parcel plugins with ESM & TS:
This package is designed for NPM compatibility, andI use PNPM for developing, so it's no mix-using for users.
This plugin has the same goal of Parcel - Zero Configuration, so users can write Markdown files as what they do on GitHub immediately.
These lines just aim to find JSX configuration from all kinds of possible files without extra configuration , which recommends TypeScript and is compatible with Babel, this plugin doesn't control the compiler. |
I appreciate that, I don't think unified has a strict policy on license type for adoption (cc @wooorm @remcohaszing)
I'd still recommend building, testing, and publishing with one.
The plugins are remark and rehype based, you could leverage those files, similar to how eslint-mdx does
Even if they aren't published I'd recommend running
Sounds good |
In my opinion, LGPL is designed for libraries, why people keep worrying about it...
PNPM has more strict Dependency Checking, all packages worked in PNPM also work well in NPM & Yarn. In the other hand, NPM & Yarn have so bad performance, PNPM is saving my life. But I use it only for local Dependency Management & NPM scripts shorthands, all other things are compatible with NPM.
When I resolve EasyWebApp/Parcel-transformer-MDX#1, I will rewrite the whole project with TypeScript to replace the quick & dirty version (which is made as the reason of long time waiting for Parcel MDX plugin updating). |
Re license: I would very very strongly recommend going with MIT/ISC/similar. That’s what almost all packages in the JS ecosystem go with. Parcel too. And us. Only if you’d have a ton of knowledge about this, and thought this through, would I recommend going against 99% of the npm packages. I am rather bummed that Parcel hasn’t solved this after a couple years. This reflects poorly on the state of Parcel. |
In my mind, GPLs are for powerless individual coders, and others are for powerful companies, universities or foundations. Until now, no one of open sourcers arounded gives me a clear reason about this, just keeps saying: "Most people use it, so you should use it"... But why? No one knows the logic in it, it doesn't make sense. I will do anything for what makes me believe.
Yeah, as a long term user, I'm worrying about the team status of Parcel project. But after using webpack, Snowpack, MicroBundle & Vite, only Parcel make me, teammates and students happy on coding with Zero Configuration design.
I thought about that, but it'll be confused for users to find a plugin only support MDX 1.x in MDX 3.x document. |
Most software is from and for larger organizations and projects.
Concisely, Category X licenses, like LGPL, limit how software can be distributed https://www.apache.org/legal/resolved.html#prohibited
Presets can be created for other build tools and bundlers as well.
I think they'll be more confused if they go out searching for a parcel plugin, see the official one, and don't see it listed in the MDX docs anywhere. |
This plugin is came from Individual coders, for but not only for individuals. And most great Open Source projects were Toy projects at the beginning, such as Linux with GPL v2.
OK, I will do more research.
As I know, only Babel has presets, and other bundlers only have a bunch of configuration fields in their documents, which needs users to set them up manually.
This plugin is a result of my failed searching about MDX 3.x Parcel plugin, the Parcel official document will tell them that they only support MDX 1.x. |
Sure, I agree.
This concerns me a bit.
Any build tool can be wrapped to templated with defaults you like. |
I don’t think this understanding is correct; npm being 99% MIT shows that “powerless individual coders” are also using MIT.
You can ask? 😉 What do you want to know?
I don’t think I see that? I don’t think so? Why would someone be confused with a note? You can show 2 things in that section? I’d lean towards adding a note, as it’s something for now, and Parcel will solve it later? |
I'm sorry, my Speak-to-Text Input Method lost the not, I mean "Not only for individuals"😂
If a framework or bundler needs a bunch of scaffold codes to make it good to use, it's not good enough actually. Zero Configuration design is beyond the presets, because the Web standards are the best presets. Parcel bundles projects based on How we refer assets (build dependency graph with If users have some advanced requirements, Parcel's plugin system loads configurations of all the existed tool chains with the original ways ( The Web is simple before, and powerful but complex today. What Parcel does is to make the Web easier again. |
Good defaults are important, yes, so is the ability to configure.
Right, and so does every other bundler and build tool from the past 2-5 years 🙂
I'm glad you're excited about web development 🙂 |
There is a place for zero config stuff! There is also a place for tools, the stuff we make here in unified, that make all the other tools possible. Some of those tools have different needs! MDX, remark, unified, are configurable. And this is important. If you call your things MDX or unified, they must be configurable as well. If you want a zero-config tool, on top of MDX, you can make that, but it’s not MDX. I think you need a new name.
I personally don’t think the web has ever been simple. The web is about humans. Not even just humans: human--computer interaction, computer--computer interaction, human--human interaction. That’s always going to be incredibly complex. |
|
Re license: I recommend using MIT. It’s free, common, and simple. But you’re free to use whatever license you want. You can always relicense your own projects (but the old license applies to old versions). I don’t think we should block any (L)GPL licensed projects from being listed on the MDX website. I agree with @wooorm that an MDX integration for a build tool should support MDX options. The current implementation picks an arbritrary list of plugins. Some of these are common, other’s I haven’t even seen before. I think that shows there’s the need for the user to specify their own plugin list. |
Perhaps we should instead document to Parcel users how they can make their own plugin? I think the core code is: import {Transformer} from '@parcel/plugin'
import {compile} from '@mdx-js/mdx'
const transform = new Transformer({
async transform({asset}) {
const source = await asset.getCode()
const file = await compile(source)
asset.type = 'jsx' // Question: this is JS already, should it be `js`?
asset.setCode(String(file))
return [asset]
}
})
export default transform |
|
I haven’t used Parcel before, let alone dealt with plugins. I also haven’t looked in depth too much. Don’t they support any configuration options?
Or we could to it like
We should pass the file path to |
Parcel's plugin system is different than others, but easy to configure & customize. In the other hand, CRA's configuration/customization is suck.
webpack needs But Parcel uses relative paths hinted by IDE, and auto install all compilers & official plugins, which others do not. |
@wooorm Parcel team has few action on MDX upgrading, "later" is
As I said above:
so, a "Parcel-MDX plugin" means compile & bundle MDX with Zero Configuration first, and then it will be configurable for customization. I'm designing & implementing the configuration file, no renaming is needed. |
@TechQuery I agree, you're going after a straw-man, I'm not talking about webpack. 🙂
Your code could also shared as a PR to Parcel itself to upgrade the official MDX integration, right? |
For now, No one latest bundlers implements all Zero Configuration features of Parcel, such as relative paths & auto installation.
@ChristianMurphy I did, look up for the PR link. |
@remcohaszing All preset MDX plugins come from official "Guides" document, which should be common for most users. |
@wooorm My plugin came from parcel-bundler/parcel#7922 (comment), but we shouldn't make Parcel users to write it again & again. |
Users have a really wide variety of use cases for MDX. If you want to avoid users having to write a custom code for when the do want a plugin. |
@ChristianMurphy @wooorm @remcohaszing Custom Configuration support is released: https://github.com/EasyWebApp/Parcel-transformer-MDX/releases/tag/v0.4.0 |
@remcohaszing It would be nice if someone upgrades MDX Node.js loader to read configuration from a |
all good points!
a) ok, that linked code can be improved |
? I do not understand this issue you created on your repo? I am not so sure I think |
@wooorm I have exposed the whole MDX
I want to load MDX files directly in Node.js for Server-side Rendering, but So I need a |
Initial checklist
Description of changes
Parcel official MDX plugin is only support MDX 1, so I publish a new plugin for MDX 3.