feat: support prism langs dependencies import validation

Koooooo-7 commented 3 months ago

Summary

The Prism code highlight requires a strict order per langs. It is hard for users to find out the right order to put the langs importing <script>. As per the Prism for highlight requires the strict dependencies import order for languages. When user add multi highlight support for much langs, it may put in wrong order.

Why provides the validation instead of the out of box solution:

The Prism provide an autoloader plugin to make it possible to auto load langs dependencies instead of user customize it.

Ideally, user can get the code highlight function directly. But it doesn't work very well especially --- remains lots of issues waiting fix PrismJS/autoloader and the PrismJS is not active maintained anymore. If we used the autoloader solution, we need facing the same or more issues also. And the configs provided from autoloader plugin is too less to do extension.
The markedjs or other code highlight libs, such as marked-highlight They can provided as extension for marked or another way to highlight code. But it will get lots of code styling changed and not support so much langs as PrismJS. It is not worthy to refactor the whole code highlight solution.
The limited situation for the issue happens. The issue occurs when user imports lots of langs with need lots of specific dependencies orders. Or some user import a langs but don't know it needs some extra lang dependencies, such as tsx. There is no strong voice about it when users use docsify.

Therefore, I think the dependencies validation with warning and the extra docs for Prism in the Prism section should be enough to resolve the unusually importing issue.

TODO: The doc update will finish later after the new callout labels done.

Screenshots

All is correct: Allfine

Missing import or in wrong order:

   // not import java
 <!-- <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script> -->

   // wrong import order, ruby should first
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-crystal.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-ruby.min.js"></script>

     // missing dependencies
    <!-- <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-jsx.min.js"></script> -->
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-tsx.min.js"></script>

Allwrong

Related issue, if any:

close #1952

What kind of change does this PR introduce?

Other

For any code change,

[ ] Related documentation has been updated, if needed
[ ] Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

Yes No

Tested in the following browsers:

[x] Chrome
[ ] Firefox
[ ] Safari
[ ] Edge

vercel[bot] commented 3 months ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docsify-preview	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 12, 2024 2:49am

trusktr commented 3 months ago

Hey @Koooooo-7 thanks for taking time to tackle this issue. I am wondering if it is worth adding code to support basically a legacy and unmaintained project, and if it would be better to pick a newer project that is written with ES Modules, because then the order of dependencies is of no worry.

I have been using codemirror. Examples on Lume site:

https://docs.lume.io/

Those examples are fully editable and show the live output, but the text editor can also be used readonly to display text only.

For the live code samples on Lume site, I created a <live-code> element:

https://github.com/lume/live-code (see demos there)

Here is the <code-mirror> element I made for easy usage of codemirror, which is what <live-code> uses for the text portion, it provides only the codemirror text rendering and editing:

https://github.com/lume/code-mirror-el (see demos there)

The demos there are editable, but it can be easily set to readonly for display. Also, similar to what I did in <live-code>, it is possible to add buttons for copy, reset (if code is editable), etc.

Anyway just sharing for ideas. Maybe there's something simpler, but that is published as ES Modules, that we could use. In any case, I believe it would be ideal to move forward with libs that are easy to support without having to write code like in this PR because ES Modules provide it for free already.

Koooooo-7 commented 3 months ago

Hi @trusktr , thx for the sharing. Cos the prism is more focus on the highlight code and it already supports tons of langs, and docsify uses it about over 7 years. For the highlight requirement, I think it could do well in the job, except the annoying dependencies order.

About the live-code, I think it is pretty cool tho. The highlight code is just a part of features of it. I suppose the live-code could be a plugin or we officially support it in docsify like the mermaid.

cc @docsifyjs/reviewers

trusktr commented 3 months ago

Btw, check out https://shiki.style/, a more modern syntax highligher than Prism, uses ES modules, etc.

Koooooo-7 commented 3 months ago

Btw, check out https://shiki.style/, a more modern syntax highligher than Prism, uses ES modules, etc.

The 式 lib looks pretty cool and it does the highlight from the HAST which is more deeper layer to calculate DOMs. Decide to change the Prism or not, I suppose we could have a discussion in chats before we just jump to do it.

Btw, I'm interesting in making something on it also, its transformer looks fun, hah.

docsifyjs / docsify