Improve examples, add defer, async, and pre- loading KaTeX #1580
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1580 +/- ##
=======================================
Coverage 84.49% 84.49%
=======================================
Files 79 79
Lines 4619 4619
Branches 807 807
=======================================
Hits 3903 3903
Misses 619 619
Partials 97 97Continue to review full report at Codecov.
|
docs/api.md
Outdated
| // '<span class="katex">...</span>' | ||
| } catch (e) { | ||
| if (e instanceof katex.ParseError) { | ||
| // KaTeX can't parse the expression |
There was a problem hiding this comment.
I wonder if it's worth including an example of how to render the error, e.g.
html = "KaTeX error: " + e.message.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
docs/api.md
Outdated
| } else { | ||
| throw e; | ||
| } | ||
| } |
There was a problem hiding this comment.
I'd personally rather have this more complex example in the "Handling Errors" section. We could either return this example as it was, or e.g. encourage the use of {throwOnError: false}, which should cover the most common use case -- and then refer to Handling Errors for alternatives. What do you think?
README.md
Outdated
| } else { | ||
| throw e; | ||
| } | ||
| } |
There was a problem hiding this comment.
I think we should keep these examples simple in the README, and refer to the API doc for more. I'd use the {throwOnError: false} option in both the examples above. This also quickly demos the ability to pass in a settings object.
docs/autorender.md
Outdated
| ``` | ||
| > If you do not use `defer` attribute, `renderMathInElement` should be called | ||
| right before the closing body tag(`</body>`) or when (or after) `DOMContentLoaded` | ||
| event is fired on the `document`. |
There was a problem hiding this comment.
Should be "If you do not use the defer attribute..."
Also I think it might be nice to include an example of attaching to DOMContentLoaded. onload is cool, but it doesn't seem like a great way to write a complex settings object.
docs/autorender.md
Outdated
| ``` | ||
|
|
||
| Then, call the exposed `renderMathInElement` function in a script tag | ||
| before the close body tag: | ||
| > The loading of scripts are [deferred using `defer` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes) |
There was a problem hiding this comment.
Maybe start with "In the example above," Also add "the" in "deferred using the defer attribute".
|
@edemaine Please feel free to edit the pull request directly as you deem fit. |
|
OK, I took a stab at revising. For some reason, I'm unable to push to this branch. Could you pull from https://github.com/edemaine/KaTeX/tree/examples? Or help me debug this error message: (I'm trying I just noticed |
|
@edemaine Thank you for reviewing and revising! As a non-native English speaker, I sometimes find it difficult to find the right wording 😄 I've added a few minor changes. |
|
Happy to help! It's great to see the documentation improving so much. |
|
Love all of the documentation! Thank you. |
katex.renderexamples with try...catch: fixes Update docs to include try/catch in examples #275deferandonload: see Recommend deferring loading KaTeX and using onload to run auto-render #1578