use ember-showdown-shiki

[mansona]

This makes use of the changes in https://github.com/ember-learn/ember-jsonapi-docs/pull/137 and https://github.com/ember-learn/ember-api-docs-data/pull/25 to make sure that we're using markdown/showdown for our descriptions everywhere now.

This has allowed us to use https://github.com/IgnaceMaes/ember-showdown-shiki which (finally) gives us the same functionality for syntax highlighting across guides and API docs 🎉

[netlify[bot]]

✅ Deploy Preview for ember-api-docs ready!

Name	Link
🔨 Latest commit	cf5daf8f2f109564d5d7f2e9ec43c64abc8600f9
🔍 Latest deploy log	https://app.netlify.com/sites/ember-api-docs/deploys/66880a832bd0db00089facda
😎 Deploy Preview	https://deploy-preview-902--ember-api-docs.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 configuration.

[IgnaceMaes]

suggestion: configure the languages to load in config/environment.js. This way we only load the required language grammars.

See e.g. https://github.com/ember-learn/cli-guides/pull/316/files#diff-9764cd8b6365b92786ac2e7eecab5e31a51193664db8931af01778ab9d0fa76c

    // ...
    'ember-showdown-shiki': {
      theme: 'github-dark',
      languages: [
        'bash',
        'css',
        'http',
        'javascript',
        'json',
        'json5',
        'ruby',
        'scss',
        'yaml',
        'typescript',
        'glimmer-js',
        'glimmer-ts',
        'handlebars',
      ],
    },

[IgnaceMaes]

Did some spot checks, and it looks all good to me 🙌

[mansona]

suggestion: configure the languages to load in config/environment.js. This way we only load the required language grammars.

what is the alternative? does it load all of them?

[IgnaceMaes]

what is the alternative? does it load all of them?

That's the default behaviour, yes.

[mansona]

in that case I wouldn't consider this a blocker, we can fix it as an optimisation later. I wouldn't be comfortable limiting the languages on the api-docs unless we had some sort of lint checking that the input Markdowns are only using the right languages, does that make sense?

[IgnaceMaes]

The language grammars are loaded eagerly, so loading all of them does have a performance impact.

I think it should be safe taking over the ones we set for the other guide apps. And if a language is missing, it would just be not highlighted (but not crash).

The alternative is looking into making loading the grammars lazy in ember-showdown-shiki. Not sure how feasible that is 🤔

[mansona]

So a few things here:

I'm not exactly sure it doesn't crash if the language doesn't exist. I had to do a process in https://github.com/ember-learn/ember-jsonapi-docs/pull/137 that stripped the language no-highlight from the code blocks because the app would crash. I don't remember if this was on the branch before or after I switched from ember-showdown-prism to ember-showdown-shiki so my data could be out of date. If you wanted to verify that it's ok to highlight with a missing language (including in prember) then I'm happy to limit it like you say 👍

As for dynamic loading of languages, I'm 100% against this. We need it to be predictable and I don't want to open up an issue of executing random JS modules from a remote location in a fastboot environment. I would rather the language be missing (and not crash) than loading it dynamically 👍