From 293af2936de7c864c68c84f1be991899e15e58a0 Mon Sep 17 00:00:00 2001 From: ylemkimon Date: Mon, 20 Aug 2018 00:25:11 +0900 Subject: [PATCH] Release v0.10.0-rc (#1634) * Release v0.10.0-rc Bump master to v0.10.0-pre * Update CHANGELOG.md * Update SRI hashes * Update SRI hashes --- CHANGELOG.md | 116 ++ README.md | 8 +- contrib/copy-tex/README.md | 4 +- contrib/mathtex-script-type/README.md | 8 +- docs/autorender.md | 12 +- docs/browser.md | 14 +- package.json | 2 +- website/pages/index.html | 12 +- .../versioned_docs/version-0.10.0-rc/api.md | 44 + .../version-0.10.0-rc/autorender.md | 96 ++ .../version-0.10.0-rc/browser.md | 67 + .../versioned_docs/version-0.10.0-rc/cli.md | 61 + .../versioned_docs/version-0.10.0-rc/error.md | 36 + .../versioned_docs/version-0.10.0-rc/font.md | 49 + .../version-0.10.0-rc/issues.md | 20 + .../versioned_docs/version-0.10.0-rc/libs.md | 37 + .../versioned_docs/version-0.10.0-rc/node.md | 41 + .../version-0.10.0-rc/options.md | 40 + .../version-0.10.0-rc/security.md | 21 + .../version-0.10.0-rc/support_table.md | 1191 +++++++++++++++++ .../version-0.10.0-rc/supported.md | 641 +++++++++ .../version-0.10.0-rc-sidebars.json | 25 + website/versions.json | 3 + 23 files changed, 2518 insertions(+), 30 deletions(-) create mode 100644 website/versioned_docs/version-0.10.0-rc/api.md create mode 100644 website/versioned_docs/version-0.10.0-rc/autorender.md create mode 100644 website/versioned_docs/version-0.10.0-rc/browser.md create mode 100644 website/versioned_docs/version-0.10.0-rc/cli.md create mode 100644 website/versioned_docs/version-0.10.0-rc/error.md create mode 100644 website/versioned_docs/version-0.10.0-rc/font.md create mode 100644 website/versioned_docs/version-0.10.0-rc/issues.md create mode 100644 website/versioned_docs/version-0.10.0-rc/libs.md create mode 100644 website/versioned_docs/version-0.10.0-rc/node.md create mode 100644 website/versioned_docs/version-0.10.0-rc/options.md create mode 100644 website/versioned_docs/version-0.10.0-rc/security.md create mode 100644 website/versioned_docs/version-0.10.0-rc/support_table.md create mode 100644 website/versioned_docs/version-0.10.0-rc/supported.md create mode 100644 website/versioned_sidebars/version-0.10.0-rc-sidebars.json create mode 100644 website/versions.json diff --git a/CHANGELOG.md b/CHANGELOG.md index b2ea2d45..f1740d15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,122 @@ # Change Log All notable changes to this project will be documented in this file. This CHANGELOG roughly follows the guidelines from [www.keepachangelog.com](https://keepachangelog.com/en/1.0.0/). +## [v0.10.0] - RC +### Added +- Unicode: °, delimiters, 1D400-1D7FF, \ll, \lll, ≘≙≚≛≝≞≟, Unicode Mathematical Alphanumeric Symbols, ⟂ ¬ ⊨ ‼ ∌ ≲ ⩽ ⪅ ≶ ⋚ ⪋, corner (#1203, #1207, #1260, #1273, #1274, #1232, #1377, #1389, #1459) +- \yen support on text mode (#1208) +- \( (#1213) +- Add defineSymbol to the main katex object (#1263) +- Capital Greek letters (#1283, #1285) +- Add version to katex object (#1279, #1475) +- \copyright, \textregistered, \textcircled (#1073) +- Tilde \textasciitilde (#1286) +- Line breaks for inline formulas (#1287) +- \hline (#1306) +- Top-level \newline and \\ in inline math (#1298) +- Strict mode, unicode text in math mode (#1117, #1278) +- Strict setting for \newline display-mode behavior (#1314) +- Allow all Unicode symbols in nonstrict mode (#1217) +- \tag, \tag*, and \gdef (#1309) +- \def, \gdef, and \global\def (#1348, #1425) +- Change default maxExpand limit to 1000 (#1383) +- \cfrac (#1392) +- \arraystretch as a macro definition (#1381) +- Add ability to create a dashed vertical line in arrays, using ':' (#1395) +- \widecheck (#1406) +- \hdashline (#1407) +- \newcommand, \renewcommand, \providecommand (#1382) +- Add a utility function (setFontMetrics) to extend builtin fontMetrics (#1269) +- \oiint and \oiiint (#1430) +- Remove `match-at` dependency, use RegExp for lexer (#1447) +- \brace and \brack (#1453) +- Allow only allowed protocols in \href (#1440) +- \genfrac and \above (#1455, #1458) +- \char character escaping and nicer MathML via \html@mathml (#1454) +- \@binrel (#1487) +- \pmb (#1418) +- KaTeX website & documentation (#1484, #1515, #1518, #1514, #1526, #1516, #1519, #1527, #1564, #1566, #1584) +- Improve supported functions documentation (#1511, #1517, #1532, #1533, #1576, #1556, #1580, #1602) +- Alpha sorted function support page (#1536) +- MediaWiki (texvc) (#1558) +- Add ignore option for class names in auto-render (#1555) +- ScrollSpy for table of contents in the documentation (#1557, #1567, #1568) +- Build ECMAScript modules (#1479, #1622) +- Enable environment variable USE_TTF to disable bundling TTF fonts (#1600) +- List of KaTeX users (#1569, #1579) + +### Changed +- Port to @flow: delimiter, spacingData, unicodeSymbols, buildHTML, buildMathML, parseNode, defineFunction (#1177, #1195, #1206, #1239, #1247, #1276, #1312, #1324, #1361, #1373, #1393, #1386, #1387, #1408, #1478, #1486, #1534, #1541, #1542, #1551, #1552, #1554, #1559, #1606, #1609, #1612, #1637) +- Online screenshot diff/generation using CircleCI (#1187) +- Add display/displayMode toggle on test page (#1193) +- Change CDN links (#1243) +- Changelog for KaTeX (#1322) +- Move test helpers into common modules (#1318) +- Move function handlers to functions/ (#1323, #1325, #1328, #1329, #1331, #1327, #1334, #1339, #1349, #1359, #1332, #1335) +- Add regenerate option to the screenshotter (#1220) +- Upgrade to webpack 4 (#1337, #1435) +- Automatic submodule updating via husky tool (#1391) +- Refactor test helpers (#1336) +- Change build directory to `dist` and cleanup NPM scripts (#1500, #1610) +- Switch from nomnom to commander (#1496) +- Add test job to CircleCI (#1235) +- Switch npm to Yarn (#1522, #1528) +- Improve release script & enable versioning documentation (#1521, #1603) +- Enable stylelint-config-standard, lint CSS files (#1575) +- Rename Screenshotter -> screenshotter (#1573) + +### Fixed +- Fix nested math mode in non-default text mode (#1111) +- Fix contenteditable mode (#1179) +- Work around negative space bug in Chrome (#1194) +- Fix \nobreakspace (#1200) +- Fix instant mode switching for $, \(, \text (#1213) +- Add metrics for \S and \P (#1224) +- Fix anchor.toMarkup (#1246) +- Specify height for SVG elements (#1252) +- Include Bold-Italic fonts for \boldsymbol (#1257) +- Fix space width in \texttt (#1261) +- Fix \underset (#1277) +- Remove special \verb space handling now that space is in Typewriter-Regular (#1258) +- Switch makeGlue from .mord .rule to .mspace (#1295) +- Fix ~ in \verb (#1286) +- Stop throwing ParseError when throwOnError is false (#1169, #1302, #1308) +- Fix extensible arrow sup vertical alignment (#1256) +- Adjust \underset alignment and spacing (#1290) +- Revert frac-lines and \rule to borders (min-height) (#1249, #1417, #1594) +- Fix vertical alignment of \underbrace (#1304) +- Use one strut instead of two (#1307) +- Fix MacroExpander space handling (#1314) +- Cleanup MathML , , (#1338) +- Fix lap vertical alignment. (#1162) +- Fix nested \tfrac (#1370) +- Fix \coloneq etc (#1372) +- Fix wide character spacing (#1371) +- Fix auto-render \\[…] bug (#1375) +- Rewrite spacing commands as macros (#1156) +- Enable output modules to be used in browser or Node (#1401) +- Add vertical kern to \vdots (#1402) +- Implement \neq and \notin via macros like LaTeX's (#1400, #1499) +- Improve \cancel (#1398) +- Fix ligatures vs. \tt (#1379) +- Implement \colon as amsmath does (#1410) +- Automatic mrel/mbin spacing for \boldsymbol (#1388) +- Phantom text (#1449) +- Fix arrowheads for mhchem <--> (#1451) +- Set `documentFragment.style` to empty object (#1471) +- Remove tree cloning before building HTML (#1470) +- Fix \operatorname to support general math functions (#1461) +- Use \not character without left side-bearing correction (#1267) +- Remove codes that require expensive polyfill (#1469, #1563, #1591, #1597) +- Fix \not vertical alignment (#1497) +- Comments without terminating newlines, \href fixes, \url support (#1529) +- Fix \textdaggerdbl (#1539) +- Fix \neq (#1548, #1574) +- Fix wide characters (#1549) +- Fix \fbox (#1550) +- Fix \Large roots (#1485) +- index.html: replace font, make responsive, improve demo (#1547, #1577, #1615, #1601) + ## [v0.9.0] - 2018-02-18 ### Added diff --git a/README.md b/README.md index 8ef166bd..a7520b5a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![codecov](https://codecov.io/gh/Khan/KaTeX/branch/master/graph/badge.svg)](https://codecov.io/gh/Khan/KaTeX) [![Join the chat at https://gitter.im/Khan/KaTeX](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Khan/KaTeX?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Greenkeeper badge](https://badges.greenkeeper.io/Khan/KaTeX.svg)](https://greenkeeper.io/) [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/katex/badge?style=rounded)](https://www.jsdelivr.com/package/npm/katex) -![](https://img.badgesize.io/Khan/KaTeX/v0.10.0-beta/dist/katex.min.js?compression=gzip) +![](https://img.badgesize.io/Khan/KaTeX/v0.10.0-rc/dist/katex.min.js?compression=gzip) KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web. @@ -28,13 +28,13 @@ Try out KaTeX [on the demo page](https://khan.github.io/KaTeX/#demo)! - + - + - ... diff --git a/contrib/copy-tex/README.md b/contrib/copy-tex/README.md index 686d5b7e..bbf62ed5 100644 --- a/contrib/copy-tex/README.md +++ b/contrib/copy-tex/README.md @@ -21,8 +21,8 @@ provided by this extension). Without this CSS, partially selected equations will just get the usual HTML copy/paste behavior. ```html - - + + ``` See [index.html](index.html) for an example. diff --git a/contrib/mathtex-script-type/README.md b/contrib/mathtex-script-type/README.md index 12449ee4..608e8787 100644 --- a/contrib/mathtex-script-type/README.md +++ b/contrib/mathtex-script-type/README.md @@ -12,7 +12,7 @@ Load the extension by adding the following line to your HTML file. This extension should be loaded *after* all `script type=math/tex` blocks that you want to render. ```html - + ``` Note that if the URL above contains `...` in-place of a version string, then this script has not yet been deployed to the CDN. @@ -25,12 +25,12 @@ After we're done writing `math/tex` scripts, we load this extension. ```html - - + + - + ``` diff --git a/docs/autorender.md b/docs/autorender.md index 5c1c22fc..aaf50ae0 100644 --- a/docs/autorender.md +++ b/docs/autorender.md @@ -12,9 +12,9 @@ This extension isn't part of KaTeX proper, so the script needs to be included using a CDN: ```html - - - + ``` @@ -31,9 +31,9 @@ want to use a `defer` or `onload` attribute. For example: ```html - - - + + + + + ``` KaTeX also provides minified versions: ```html - - + + ``` > The loading of scripts are [deferred using `defer` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes) @@ -40,11 +40,11 @@ ECMAScript module is also available: ```html - - + + ``` > Use [`nomodule` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes) diff --git a/package.json b/package.json index 8c38e659..5673a317 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "katex", - "version": "0.11.0-pre", + "version": "0.10.0-pre", "description": "Fast math typesetting for the web.", "main": "dist/katex", "module": "dist/katex.mjs", diff --git a/website/pages/index.html b/website/pages/index.html index 801f5d57..9440e5f2 100644 --- a/website/pages/index.html +++ b/website/pages/index.html @@ -16,17 +16,17 @@ - - - - + + + + - + - + diff --git a/website/versioned_docs/version-0.10.0-rc/api.md b/website/versioned_docs/version-0.10.0-rc/api.md new file mode 100644 index 00000000..e3e793bd --- /dev/null +++ b/website/versioned_docs/version-0.10.0-rc/api.md @@ -0,0 +1,44 @@ +--- +id: version-0.10.0-rc-api +title: API +original_id: api +--- +## In-browser rendering +Call `katex.render` with a TeX expression and a DOM element to render into: + +```js +katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, { + throwOnError: false +}); +``` + +To avoid escaping the backslash (double backslash), you can use +[`String.raw`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw) +(but beware that `${`, `\u` and `\x` may still need escaping): +```js +katex.render(String.raw`c = \pm\sqrt{a^2 + b^2}`, element, { + throwOnError: false +}); +``` + +## Server-side rendering or rendering to a string +To generate HTML on the server or to generate an HTML string of the rendered math, you can use `katex.renderToString`: + +```js +var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}", { + throwOnError: false +}); +// '...' +``` + +## Handling errors + +The examples above use the `throwOnError: false` option, which renders invalid +inputs as the TeX source code in red (by default), with the error message as +hover text. Without this option, invalid LaTeX will cause a +`katex.ParseError` exception to be thrown. See [handling errors](error.md). + +## Configuring KaTeX + +The last argument to `katex.render` and `katex.renderToString` can contain +[a variety of rendering options](options.md). diff --git a/website/versioned_docs/version-0.10.0-rc/autorender.md b/website/versioned_docs/version-0.10.0-rc/autorender.md new file mode 100644 index 00000000..5c02ef17 --- /dev/null +++ b/website/versioned_docs/version-0.10.0-rc/autorender.md @@ -0,0 +1,96 @@ +--- +id: version-0.10.0-rc-autorender +title: Auto-render Extension +original_id: autorender +--- +This is an extension to automatically render all of the math inside of text. It +searches all of the text nodes within a given element for the given delimiters, +ignoring certain tags like `
`, and renders the math in place.
+
+## Usage
+This extension isn't part of KaTeX proper, so the script needs to be included
+(via a `
+
+```
+
+> Above, the [`defer` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes)
+indicates that the script doesn't need to execute until the page has loaded,
+speeding up page rendering; and the `onload` attribute calls
+`renderMathInElement` once the auto-render script loads.
+
+Alternatively, you can call the `renderMathInElement` when (or after) the
+[`DOMContentLoaded` event](https://developer.mozilla.org/ko/docs/Web/Reference/Events/DOMContentLoaded)
+fires on the document or in another deferred script.
+This approach is useful for specifying or computing options, or if you don't
+want to use a `defer` or `onload` attribute.
+For example:
+
+```html
+
+
+
+
+```
+
+## API
+This extension exposes a single function, `window.renderMathInElement`, with
+the following API:
+
+```js
+function renderMathInElement(elem, options)
+```
+
+`elem` is an HTML DOM element. The function will recursively search for text
+nodes inside this element and render the math in them.
+
+`options` is an optional object argument that can have the same keys as [the
+object passed to `katex.render`](https://github.com/Khan/KaTeX/#rendering-options),
+in addition to two auto-render-specific keys:
+
+- `delimiters`: This is a list of delimiters to look for math. Each delimiter
+  has three properties:
+
+    - `left`: A string which starts the math expression (i.e. the left delimiter).
+    - `right`: A string which ends the math expression (i.e. the right delimiter).
+    - `display`: A boolean of whether the math in the expression should be
+      rendered in display mode or not.
+
+  The default value is:
+
+  ```js
+  [
+    {left: "$$", right: "$$", display: true},
+    {left: "\\(", right: "\\)", display: false},
+    {left: "\\[", right: "\\]", display: true}
+  ]
+  ```
+
+- `ignoredTags`: This is a list of DOM node types to ignore when recursing
+  through. The default value is
+  `["script", "noscript", "style", "textarea", "pre", "code"]`.
+
+- `ignoredClasses`: This is a list of DOM node class names to ignore when
+  recursing through. By default, this value is not set.
+
+- `errorCallback`: A callback method returning a message and an error stack
+  in case of an critical error during rendering. The default uses `console.error`.
+
+The `displayMode` property of the options object is ignored, and is
+instead taken from the `display` key of the corresponding entry in the
+`delimiters` key.
+
+The same `options.macros` object (which defaults to an empty object `{}`)
+is passed into several calls to `katex.render`, so that consecutive equations
+can build up shared macros by `\gdef`.
diff --git a/website/versioned_docs/version-0.10.0-rc/browser.md b/website/versioned_docs/version-0.10.0-rc/browser.md
new file mode 100644
index 00000000..53e7bce8
--- /dev/null
+++ b/website/versioned_docs/version-0.10.0-rc/browser.md
@@ -0,0 +1,67 @@
+---
+id: version-0.10.0-rc-browser
+title: Browser
+original_id: browser
+---
+> KaTeX supports all major browsers, including Chrome, Safari, Firefox, Opera, Edge, and IE 9–11.
+
+## CDN (Content Delivery Network)
+Use CDN to deliver KaTeX to your project:
+
+```html
+
+
+```
+
+KaTeX also provides minified versions:
+
+```html
+
+
+```
+
+> The loading of scripts are [deferred using `defer` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes)
+to speed up page rendering. The `katex` object will be available after
+[`DOMContentLoaded` event is fired on the `document`](https://developer.mozilla.org/ko/docs/Web/Reference/Events/DOMContentLoaded).
+If you do not use `defer`, `katex` object will be available after corresponding
+`script` tag.
+
+> If KaTeX is not used immediately or not critical, it is possible to load KaTeX
+asynchronously. Add [`async` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes)
+to `script` and use [`rel="preload"` and `onload` attribute](https://github.com/filamentgroup/loadCSS)
+on `link`.
+
+> You can prefetch KaTeX fonts to prevent FOUT or FOIT. Use [Web Font Loader](https://github.com/typekit/webfontloader)
+or add [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content)
+to `head`. (Note that only few browsers [support `rel="preload"`](https://caniuse.com/#feat=link-rel-preload)
+and they all support WOFF2 so preloading WOFF2 fonts is enough.) You can use
+Chrome DevTools Network panel or similar to find out which fonts are used.
+
+ECMAScript module is also available:
+
+```html
+
+
+
+```
+
+> Use [`nomodule` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes)
+to provide a fallback for older browsers that do not support ES modules.
+
+## Download & Host Things Yourself
+Download a [KaTeX release](https://github.com/Khan/KaTeX/releases),
+copy `katex.js`, `katex.css`
+(or `katex.min.js` and `katex.min.css` to use minified versions),
+and the `fonts` directory, and include like above.
+
+You can also build from source. See [Building from Source](node.md#building-from-source)
+for more details.
+
+## Bundler
+Use [Node.js package managers](node.md) to install KaTeX and require it in your
+project. Then bundle using bundlers like [webpack](https://webpack.js.org/) or
+[rollup.js](https://rollupjs.org/). Note that you have to bundle the stylesheet
+(`katex.css`) or include it manually.
diff --git a/website/versioned_docs/version-0.10.0-rc/cli.md b/website/versioned_docs/version-0.10.0-rc/cli.md
new file mode 100644
index 00000000..43206bec
--- /dev/null
+++ b/website/versioned_docs/version-0.10.0-rc/cli.md
@@ -0,0 +1,61 @@
+---
+id: version-0.10.0-rc-cli
+title: CLI
+original_id: cli
+---
+
+KaTeX installed [using Node.js package managers](node.md) comes with a
+built-in command-line interface (CLI) which can be used to render TeX to HTML.
+By default, CLI will take the input from standard input.
+
+```bash
+npx katex
+```
+
+> Above uses the `npx` command to run the locally installed executable
+after `npm install katex`.  You can also execute with the relative path:
+`./node_modules/.bin/katex`
+
+> To use the CLI from local Git clone, you need to build the project first.
+See [Building from Source](node.md#building-from-source) for more details.
+
+## Options
+
+### `-V, --version`
+output the version number
+
+### `-d, --display-mode`
+Render math in display mode, which puts the math in display style (so \int and \sum are large, for example), and centers the math on the page on its own line.
+
+### `-t, --no-throw-on-error`
+Render errors (in the color given by --error-color) instead of throwing a ParseError exception when encountering an error.
+
+### `-c, --error-color `
+A color string given in the format 'rgb' or 'rrggbb' (no #). This option determines the color of errors rendered by the -t option. (default: #cc0000)
+
+### `-b, --color-is-text-color`
+Makes \color behave like LaTeX's 2-argument \textcolor, instead of LaTeX's one-argument \color mode change.
+
+### `-S, --strict`
+Turn on strict / LaTeX faithfulness mode, which throws an error if the input uses features that are not supported by LaTeX
+
+### `-s, --max-size `
+If non-zero, all user-specified sizes, e.g. in \rule{500em}{500em}, will be capped to maxSize ems. Otherwise, elements and spaces can be arbitrarily large (default: 0)
+
+### `-e, --max-expand `
+Limit the number of macro expansions to the specified number, to prevent e.g. infinite macro loops.  If set to Infinity, the macro expander will try to fully expand as in LaTeX.
+
+### `-m, --macro `
+Define custom macro of the form '\foo:expansion' (use multiple -m arguments for multiple macros). (default: )
+
+### `-f, --macro-file `
+Read macro definitions, one per line, from the given file.
+
+### `-i, --input `
+Read LaTeX input from the given file.
+
+### `-o, --output `
+Write html output to the given file.
+
+### `-h, --help`
+Output usage information
diff --git a/website/versioned_docs/version-0.10.0-rc/error.md b/website/versioned_docs/version-0.10.0-rc/error.md
new file mode 100644
index 00000000..9ac9f907
--- /dev/null
+++ b/website/versioned_docs/version-0.10.0-rc/error.md
@@ -0,0 +1,36 @@
+---
+id: version-0.10.0-rc-error
+title: Handling Errors
+original_id: error
+---
+If KaTeX encounters an error (invalid or unsupported LaTeX) and `throwOnError`
+hasn't been set to `false`, then `katex.render` and `katex.renderToString`
+will throw an exception of type `katex.ParseError`.
+The message in this error includes some of the LaTeX source code,
+so needs to be escaped if you want to render it to HTML.  For example:
+
+```js
+try {
+    var html = katex.renderToString(texString);
+    // '...'
+} catch (e) {
+    if (e instanceof katex.ParseError) {
+        // KaTeX can't parse the expression
+        html = ("Error in LaTeX '" + texString + "': " + e.message)
+            .replace(/&/g, "&").replace(//g, ">");
+    } else {
+        throw e;  // other error
+    }
+}
+```
+
+In particular, you should convert `&`, `<`, `>` characters to
+`&`, `<`, `>` before including either LaTeX source code or
+exception messages in your HTML/DOM.
+(This can also be done using `_.escape`.)
+Failure to escape in this way makes a `