docs: clarify extension types (#3182) #3797
Conversation
|
@rinas21 is attempting to deploy a commit to the MarkedJS Team on Vercel. A member of the Team first needs to authorize it. |
Summary of ChangesHello @rinas21, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the clarity of the Marked.js documentation by explicitly distinguishing between different types of extensions. The changes introduce precise terminology, detailed explanations, and practical examples to help developers better understand and utilize the extension system, ultimately improving the developer experience and reducing common points of confusion. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Clarify ambiguity around "extensions" #3182 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces significant improvements to the documentation by clarifying the different types of extensions in marked.js. A new document, EXTENSION_TYPES.md, is added to explain the distinction between MarkedExtension and TokenizerAndRendererExtension, and existing documentation is updated to use this new, clearer terminology. The changes are well-executed and greatly enhance the clarity of the extension API for developers. I have one suggestion to further improve the consistency of the new terminology in the documentation.
docs/EXTENSION_TYPES.md
Outdated
| - **MarkedExtension**: Configuration objects for `marked.use()` | ||
| - **TokenizerAndRendererExtension**: Custom parsing logic objects for the `extensions` array |
There was a problem hiding this comment.
For better clarity and grammatical correctness, it would be better to make the descriptions for MarkedExtension and TokenizerAndRendererExtension singular to match their type names.
For example:
- MarkedExtension: A configuration object for
marked.use() - TokenizerAndRendererExtension: A custom parsing logic object for the
extensionsarray
This would also align better with the headings on lines 9 and 36 if they were also made singular (e.g., ### 1. MarkedExtension (Configuration Object)), further improving consistency throughout this document.
| - **MarkedExtension**: Configuration objects for `marked.use()` | |
| - **TokenizerAndRendererExtension**: Custom parsing logic objects for the `extensions` array | |
| - **MarkedExtension**: A configuration object for `marked.use()` | |
| - **TokenizerAndRendererExtension**: A custom parsing logic object for the `extensions` array |
|
Fixed the issue , Clarify ambiguity around "extensions" #3182 |
docs/EXTENSION_TYPES.md
Outdated
| }); | ||
| ``` | ||
|
|
||
| ### 2. TokenizerAndRendererExtensions (Custom Parsing Logic) |
There was a problem hiding this comment.
I don't like calling this a TokenizerAndRendererExtension because it could contain a custom Tokenizer function or a customer Renderer function or both.
I think we should use CustomExtension or maybe SyntaxExtension?
There was a problem hiding this comment.
I've updated all references from TokenizerAndRendererExtension to SyntaxExtension in:
Documentation files: EXTENSION_TYPES.md, USING_PRO.md, USING_ADVANCED.md
Source code: src/MarkedOptions.ts
Test files: test/types/marked.ts
Type definitions: Updated the TypeScript interface
| ## Migration from Previous Versions | ||
|
|
||
| When upgrading from older versions of marked.js, you may need to separate your configuration: | ||
|
|
||
| ```javascript | ||
| // Old way (confusing) | ||
| const config = { | ||
| gfm: true, | ||
| extensions: [customExtension1, customExtension2] | ||
| }; | ||
|
|
||
| // New way (clear separation) | ||
| const markdownOptions = { | ||
| gfm: true | ||
| }; | ||
|
|
||
| const customExtensions = { | ||
| extensions: [customExtension1, customExtension2] | ||
| }; | ||
|
|
||
| marked.use(markdownOptions); | ||
| marked.use(customExtensions); | ||
| ``` |
There was a problem hiding this comment.
We do encourage setting them together. Often an external extension will set options and add syntax extensions and we want them to be easy to use.
I think we should remove this section
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I think this will be a breaking change since the typescript types are changing |
2 participants
Marked version:
Markdown flavor: Markdown.pl|CommonMark|GitHub Flavored Markdown|n/a
Description
Contributor
Committer
In most cases, this should be a different person than the contributor.