[add] add rehype-katex-notranslate plugin for docs

[PrinOrange]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

When a page contains a large number of katex formulas, if we want to use a tool to translate the webpage (such as the built-in translation tool of Google Chrome), the translation tool will often translate the symbols in the katex block, which will cause the formula to be destroyed.

So I wrote a rehype plugin rehype-katex-notranslate. This plugin add the attribute translate="no" to the katex formula generated by rehype-katex to prevent the formulas from being recognized and translated by webpage and browser translation tools.

[ChristianMurphy]

Thanks for sharing @PrinOrange! 🙇

General feedback on what gets included in the plugins list:

Some criteria to include packages in this list.

• Some documentation with at least some instructions on how to use the package.
• A CI job to run tests. (The tests are already there.)
• A prepack script and CI job to build the types. (The JSDoc types are already there.)
• The package should be published to npm.

source: syntax-tree/hast#24 (comment)

For your plugin I'm seeing:

• Documentation
• CI to run lint/tests
• Job to generate types
• Published to NPM

---

Some additional specific pointers.

• for ESM use resolution type node16 https://github.com/PrinOrange/rehype-katex-notranslate/blob/99e36529e26bee8fec5f9c0489104557c003822a/tsconfig.json#L3 with that set moduleResolution and esModuleInterop could be removed
• the plugin will be passed Root, no need to cast from Node https://github.com/PrinOrange/rehype-katex-notranslate/blob/99e36529e26bee8fec5f9c0489104557c003822a/src/index.ts#L6
• Using visit would likely be more type safe and easier than select https://github.com/PrinOrange/rehype-katex-notranslate/blob/99e36529e26bee8fec5f9c0489104557c003822a/src/index.ts#L9 to https://unifiedjs.com/learn/recipe/tree-traversal-typescript/

[PrinOrange]

Thank you for your review. I have done some changes and fixes issues you mentioned above.
I fixed the typescript module options and rewrite the process with visit. And I have add some test cases and make it auto-workflows

https://github.com/PrinOrange/rehype-katex-notranslate

[wooorm]

Hi!

I would really recommend that you type the input of your top function: tree: Root (which comes from the @types/hast package). Then you don’t need node: Element.

You are using some formatter to rewrite the table of contents.
That is not our style.
We use formatters too.
You can use those formatters by running npm test.
That should make tests and CI pass.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (9bc5528) to head (b0e9a72).
Report is 18 commits behind head on main.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #181   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            6         6           
  Lines          154       154           
=========================================
  Hits           154       154           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[remcohaszing]

I would really recommend that you type the input of your top function: tree: Root (which comes from the @types/hast package). Then you don’t need node: Element.

Even better: change the type annotation of the plugin from Plugin to Plugin<[], Root>. This is the type you want for your exports. The type of tree will be inferred.

Also replace the hast dependency with @types/hast.

[PrinOrange]

Oh, sorry, I have re-format the documents and make it passed the CLI check.

I also have followed your advice and rewrites the typing of tree: Root and plugin Plugin<[], Root>.

Thank you all.
https://github.com/PrinOrange/rehype-katex-notranslate

[wooorm]

@PrinOrange looks like the readme here still has an unwanted change? Can you revert that? Thanks!

[ChristianMurphy]

Thanks @PrinOrange!
Looks good!

---

Some other tips.

• hast (the implementation) isn't a thing anymore (replaced by rehype) you may want to install the types only package @types/hast to get the docs and typings https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/package.json#L43
• Considering widening the versions ranges to include the .0.0 release of each major to allow package managers to deduplicate more https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/package.json#L44
• include repository metadata so adopters can find the source repository from the npm package https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#repository
• Considering checking type coverage to ensure everything is typed https://github.com/plantain-00/type-coverage in addition a threshold can be set, most remark/rehype packages aim for 100%

  rehype/package.json

  Line 57 in 26ea958

  "typeCoverage": {

• checkout action is now on v4 https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/.github/workflows/test.yml#L21
• the node setup action is also on version 4 now https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/.github/workflows/test.yml#L24
• CSpell has a generic config file that works with more tools than vscode https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/.vscode/settings.json#L2 official configuration files https://cspell.org/configuration/
• esInterop may cause weirdness when combined with module: node16 https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/tsconfig.json#L7 Considering removing the esInterop flag
• most unified packages target ES2022 https://github.com/PrinOrange/rehype-katex-notranslate/blob/bd2358e3b3b02bbf06fce8a348c1cb37391f65a8/tsconfig.json#L4 for example rehype itself

  rehype/tsconfig.json

  Line 12 in 26ea958

  "target": "es2022"