feat(docusaurus-theme-common): classify Chinese tag into alphabet

[MarkShawn2020]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

The Chinese tags in blog tag list page would be categoried into the first word, e.g. 测(from 测试), and 开(from 开发), which leads to the problem of managing tags, since there are too many Chinese characters rather than just 26 in English.

Research

There are a few of solutions to force the Chinese tag to be categoried into English alphebet, e.g. rearrange the doms on the frontend. But indeed, the best choice is to enhance the prior function of getTagLetter in packages/docusaurus-theme-common/src/utils/tagsUtils.ts, since it's just where the job works, i.e. converting the input string to be the first letter.

Solution

I got one copy of Chinese map (pinyin -> character) from the project of simple-pinyin (if it's illegal please tell me since I do not know licence relative well), and transformed into the reversed shape (character -> pinyin), so that we can do one step furtuer (pinyin -> alphebet).

I did think about the extensible problem, since it would be costly if we added the otherwise unnecessary step to check whether a tag is Chinese. Hence, I added one parameter of lang in order to compat with other potential languages.

Result

Notes

1. packages/docusaurus-theme-common/src/utils/pinyin/src/index.ts provides the interface to get leading pinyin from a Chinese word, which is integrated with docusaurus-theme-common.
2. packages/docusaurus-theme-common/src/utils/pinyin/src/genMap/* are for generating the target map, which is individual with the main processs.
3. Now there is 6743 Chinese charaters (check at packages/docusaurus-theme-common/src/utils/pinyin/data/pinyin.json), which covers the majority of tagging scenarios, and it's quite easy to be extended (e.g. 繁體字).

Test Plan

Test links

No test links to be shared, except a sample at: https://markshawn2020.github.io/keeps-learning/blog/tags.

And the unit-test is at: packages/docusaurus-theme-common/src/utils/__tests__/ChineseWord2Pinyin.ts.

Related issues/PRs

None.

[facebook-github-bot]

Hi @MarkShawn2020!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	702a010
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/62e2865f4bc246000800bbdd
😎 Deploy Preview	https://deploy-preview-7843--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 84	🟢 100	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 84	🟢 100	🟢 100	🟢 100	🟢 90	Report

[Josh-Cena]

Hi—sorry, I don't really want to take this. It's a hassle for the team to maintain (despite me being Chinese), and it bloats the bundle size for everybody. You are free to implement this solution in userland through swizzling. Thank you for taking interest in this!

Once we make theme enhancements more ergonomic (tracked in #4530), you can consider publishing this as a community theme.

[MarkShawn2020]

Hi—sorry, I don't really want to take this. It's a hassle for the team to maintain (despite me being Chinese), and it bloats the bundle size for everybody. You are free to implement this solution in userland through swizzling. Thank you for taking interest in this!

Once we make theme enhancements more ergonomic (tracked in #4530), you can consider publishing this as a community theme.

I tried sizzling but it only provides the ability to customize UI layer, so I do suggest exposing more functional-hooks, just like what the remark/rehype plugin does.

[Josh-Cena]

theme-common is theme-side—while remark/rehype is server-side. If you could do it at server-side (by exposing some kind of metadata) then great; but here you are still doing it in a UI layer, just abstracting it into a hook.

[MarkShawn2020]

Yep, just abstracting it into a hook, and indeed we really do not care too much which side the code would be running.

[MarkShawn2020]

First, thanks for your real-time work yesterday @Josh-Cena .

By the way, could you please provide me a best-practice on how to develop and deploy my own site based on docusaurus, when I had to customize some implementations individually?

There seems to be two optional solutions for me:

1. keep working on a self-dev branch based on main, customizetheme-common or any other packages in depth, and build my website under a new-created workspace naming my-website, which has a similar project strucuture with webstie but only not contents
   • pros: easier to customize themes, run-time logics, or to develop a plugin
   • cons: harder to keep pace with the main branch, especially when I wanna issue a new PR
2. keep working on the starter branch, which hides all the packages under its node_modules
   • pros: better for focusing only on docs and blogs with a cleaner project structure
   • cons: harder to customize the underlying framework