KaTeX website & documentation #1484

ylemkimon · 2018-07-15T19:20:01Z

Uses docusaurus, which is a markdown-based static documentation site generation tool. Run yarn start to start test server and yarn build to build the site.

Test site: https://ylemkimon.github.io/KaTeX/ (You can access the documentation by clicking Installation or Documentation, Note: this is not an official documentation of KaTeX is inserted to distinguish from official documentation)

Related: #1330
Fixes #1483

codecov · 2018-07-15T19:24:06Z

Codecov Report

Merging #1484 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff           @@
##           master   #1484   +/-   ##
======================================
  Coverage    84.1%   84.1%           
======================================
  Files          79      79           
  Lines        4561    4561           
  Branches      804     804           
======================================
  Hits         3836    3836           
  Misses        630     630           
  Partials       95      95

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 83e8eac...0a03484. Read the comment docs.

ronkok · 2018-07-15T19:57:22Z

Super cool!

I'll make a pull request to this branch that cleans up errors in the function support page.

[skip ci]

ylemkimon · 2018-07-16T06:21:33Z

@ronkok Please feel free to commit directly to the branch 😄

kevinbarabash · 2018-07-18T01:40:20Z

@ylemkimon this is awesome! I checked out the test site and it looks super cool. I'm also very happy that our docs are going to be in master. This should make it easier to update. Eventually it would be nice move the REPL to a it's own tab so that it can have more space.

kevinbarabash · 2018-07-18T01:42:47Z

@ylemkimon it isn't necessary to complete everything in the checklist before we merge this. I would prefer to merge this sooner and iterate on it. It'll keep the PR size down and once it's merged other people can help out. 🙂

kevinbarabash · 2018-07-18T01:49:40Z

docs/supported.md

+---
+This is a list of TeX functions supported by KaTeX. It is sorted into logical groups.
+
+There is another version of this page, [with working examples](https://khan.github.io/KaTeX/function-support.html).


I would probably just link to this page for now and then move this page to into the repo and style it appropriately. Apparently docusaurus has a way to wrap HTML pages so that they look like they're part of the site. https://docusaurus.io/docs/en/custom-pages

Or as Markdown is superset of HTML, I think we can just copy its contents for now.

Give me a couple of days before you take any drastic action.. I'll see what I can do with the docosaurus page. Either way, it will be good to have only one page to maintain.

@ylemkimon I'd like the function support page to have some tables styled differently than the GFM markdown tables now shown. For example, many of the tables should have no <thead> row. I like your idea of copying at least some of the current function support page into this documentation.

If I add some classes to website/static/static/index.css, can I then use those class names to style elements in the supported.md file?

Answering my own question: docusaurus docs addresses this.

@ronkok website/static/static/index.css is for the main page(index.html), and for the styles needed in documentations, you can put them in the website/static/css/custom.css or another .css file in website/static/css.

Can we leave a redirect link at https://khan.github.io/KaTeX/function-support.html that will forward to the new documentation? That existing page is fairly high in the search engine results for "katex".

kevinbarabash · 2018-07-18T01:53:14Z

website/siteConfig.js

+  ],
+
+  // If you have users set above, you add it here:
+  users,


So this gets passed to the Users component defined in users.js?

@kevinbarabash Yes, any property can be exported through siteConfig and used in other components.

Cool! It seems like docusaurus is quite flexible.

kevinbarabash · 2018-07-18T01:53:58Z

website/pages/en/users.js

+const CompLibrary = require('../../core/CompLibrary.js');
+const Container = CompLibrary.Container;
+
+const siteConfig = require(process.cwd() + '/siteConfig.js');


Why not a relative path?

@kevinbarabash These files are copied to node_modules/docusaurus at the build.

Interesting. Can you add a comment about this.

kevinbarabash · 2018-07-18T01:55:06Z

website/pages/en/users.js

+    });
+
+    return (
+      <div className="mainContainer">


KA uses aphrodite for CSS in JS styling. That's something we may want to adopt in the future.

kevinbarabash · 2018-07-18T01:56:34Z

website/package.json

@@ -0,0 +1,14 @@
+{


Yay, we're a monorepo now.

kevinbarabash · 2018-07-18T01:57:02Z

website/remarkableKatex.js

+ * Katex package.
+ */
+module.exports = function(md, options) {
+    var katex = require("../");


kevinbarabash · 2018-07-18T01:58:00Z

website/remarkableKatex.js

+
+/**
+ * Plugin for Remarkable Markdown processor which transforms $..$ and $$..$$ sequences into math HTML using the
+ * Katex package.


Is there no npm package for this?

@kevinbarabash There is remarkable-katex. But we don't have control over the version of KaTeX it uses.

Good point.

kevinbarabash · 2018-07-18T02:02:13Z

website/siteConfig.js

+  }],
+
+  scripts: ['https://buttons.github.io/buttons.js'],
+  stylesheets: ['https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css'],


Why do we use the local katex.js in some places bu the CSS on a CDN?

@kevinbarabash katex.js is used at the build time, specifically when parsing the markdown, whereas CSS is included in the build result. But now I think, there may be discrepancies between the last release version and the master branch. We probably should copy the CSS from local KaTeX build.

kevinbarabash · 2018-07-18T02:02:35Z

website/static/css/custom.css

+    height: 80%;
+}
+
+@media only screen and (min-device-width: 360px) and (max-device-width: 736px) {


Do we need these?

@kevinbarabash This file was provided by docusaurus as a boilerplate. I think we can remove them, if we don't have any custom styles to apply.

I guess we can leave then and fill them in if/when we make the site responsive.

kevinbarabash · 2018-07-22T01:33:53Z

The travis-ci build completed successfully. I've restarted it manually and hopefully that will fix things here.

kevinbarabash · 2018-07-22T01:45:31Z

This is new... I haven't see circleci timeout. I guess it's not as reliable as I thought it was. On the plus though though re-running the tests will still take less time than travis-ci.

kevinbarabash · 2018-07-22T01:46:10Z

In this case, I'm not going to bother since the circleci checks are mandatory... yet.

ylemkimon · 2018-07-22T03:17:46Z

@kevinbarabash There were couple of instances of CircleCI Chrome build failing, that I'd to rerun manually. As the problems are limited to Chrome builds, I think it's not a CircleCI issue, but a Selenium issue and upgrading its version might fix the problems.

edemaine · 2018-07-23T20:12:39Z

How is this going to (auto?) build? Is the idea to yarn build and push the result to the gh-pages branch? Within CI?

Regarding the checklist: once this gets merged, we could move the un-checked-off items into an issue. Overall, very exciting!

ylemkimon · 2018-07-24T04:11:29Z

@edemaine Yes. Also, docusaurus provides publish-gh-pages command, which automatically builds and deploys the website to gh-pages on CI environment.

ronkok · 2018-07-24T22:49:04Z

@ylemkimon I have not been able to build a local version of the documentation. And yet I have made a substantial revision to the function support page. I don't know exactly how it all will look, but I'm pretty sure that I've eliminated most of the rendering errors.

If you get a change to rebuild this branch, I'll take another look. I expect that another draft will be necessary. In a couple of places I used HTML tables instead of markdown tables and I don't know yet how they will turn out.

ylemkimon · 2018-07-25T07:27:05Z

@ronkok You can test the website by:

cd website
yarn install # or npm install
yarn start # or npm start

ronkok · 2018-07-25T16:59:49Z

Well yes, I already ran the commands that you suggest. Long range debugging is tedious, I know, but if you wish to try, the error message I get is:

yarn run v1.7.0
warning package.json: No license field
$ docusaurus-start
C:\Users\ronko\GitHub\KaTeX_website\website\node_modules\docusaurus\lib\start-server.js:83
        throw ex;
        ^

Error: Cannot find module '../'
    at Function.Module._resolveFilename (module.js:547:15)
    at Function.Module._load (module.js:474:25)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at module.exports (C:\Users\ronko\GitHub\KaTeX_website\website\remarkableKatex.js:29:17)
    at Remarkable.use (C:\Users\ronko\GitHub\KaTeX_website\website\node_modules\remarkable\lib\index.js:122:3)
    at siteConfig.markdownPlugins (C:\Users\ronko\GitHub\KaTeX_website\website\siteConfig.js:66:8)
    at Remarkable.use (C:\Users\ronko\GitHub\KaTeX_website\website\node_modules\remarkable\lib\index.js:122:3)
    at C:/Users/ronko/GitHub/KaTeX_website/website/node_modules/docusaurus/lib/core/renderMarkdown.js:69:12
    at Array.forEach (<anonymous>)
error Command failed with exit code 1.

ylemkimon · 2018-07-25T17:23:11Z

@ronkok It needs built KaTeX(dist/katex.js). As #1500 is merged, if you pull latest merge commit(29e24c7), you can build KaTeX by npm run build at the root.

ronkok · 2018-07-25T21:39:35Z

I now have a an markdown version of the function support page ready. I'll upload it later when I have better network access. In the new version there is both good and bad.

Good part: As a pre-rendered static file, it runs wicked fast.

Bad part: The auto-renderer has issues where it does not properly interpret characters between $…$ delimiters:

Pipe characters, "|", are read as table cell delimiters. The $…$ should take precedence, but that doesn't happen. So I am unable to show "|" in the delimiter table. And I can't write {c|c} as an argument to the {array} environment.
Nested $…$ are not parsed properly. I would like to include \raisebox{0.25em}{$b$}, but that doesn't work.

I've tried a couple different escape character tactics but have had no success. I've tried putting content into HTML tables instead of GFM pipe tables, but inside those HTML tables neither the $…$ delimiters nor the backtick delimiters have any effect.

If anyone knows a way to get escape characters that work, let me know.

ronkok · 2018-07-26T16:56:38Z

I've made a general edit to the function support page. There are still a few markdown quirks that I haven't been able to overcome, such as excess padding in the environment table. Even with those quirks, it's a pretty good effort. And I love the rendering speed.

kevinbarabash · 2018-07-27T02:05:22Z

Is the plan to deploy to gh-pages whenever we merge a PR?

kevinbarabash · 2018-07-27T02:09:36Z

I see, it looks like publish-gh-pages is manual command. I think that makes sense.

kevinbarabash · 2018-07-27T02:12:50Z

@ronkok what about \[ and \]?

edemaine · 2018-07-27T02:18:16Z

By the way, now that KaTeX is its own organization, I believe we could also publish a website from a separate repo. Not sure whether there are particular advantages either way.

ronkok · 2018-07-27T02:20:16Z

what about \[ and \]?

I'm not sure what you have in mind. If you are thinking that perhaps we could use \[ and \] as math delimiters instead of $$, there are reasons not to do that. In markdown, \[ is an escape for [. That is necessary because of markdown's syntax for links, i.e. [text](path). So every markdown math implementation that I have seen uses $ and $$ exclusively as their math delimiters.

kevinbarabash · 2018-07-27T02:25:56Z

@ronkok it sounds like the issue is our auto-render extension. I assume other Markdown engines are parsing things along $ or $$ boundaries and passing the TeX strings to whatever's rendering LaTeX for them. Do they get tripped up by the nested $ example above? Maybe we should try to write a KaTeX plugin for docusaurus. Does the auto-render extension handle this case outside of docusaurus?

kevinbarabash · 2018-07-27T02:27:23Z

@edemaine one of the downsides of hosting the docs in a separate repo is that it makes testing the docs against changes more difficult. I was also hoping that we might someday might have our test page live in the docs as well.

ronkok · 2018-07-27T02:38:22Z

The auto-render code is in the website/remarkableKatex.js file. It's commented to say that it is modeled after Remarkable code for locating code strings between backticks. That wasn't such a good model, because I can't write a "|" between backticks inside a table either. The Remarkable parser fixes on that "|" character and treats it as a cell separator even if it is between backticks.

And you are right about nesting, too. The parser cannot deal with nested $ delimiters.

I've found a couple sneaky workarounds for the "|" characters inside tables, using \textbar. And I've omitted the working examples that use nested $ characters. It didn't turn out too bad. If I could resolve some CSS issues of too much table cell padding in certain places, I'd be happy with what I've got.

ronkok · 2018-07-27T02:41:37Z

.. except for the {c|c} argument for {array}. I had to omit that "|", too, and I would like to have it back.

ronkok · 2018-07-27T02:46:32Z

Does the auto-render extension handle this case outside of docusaurus?

Yes, the normal KaTeX auto-render extension is good at handling nested $ delimiters. Maybe we need to implement some lessons learned into the remarkableKatex.js file.

kevinbarabash · 2018-07-27T03:10:08Z

Maybe we need to implement some lessons learned into the remarkableKatex.js file.

👍 sounds like a plan.

ronkok · 2018-07-27T03:15:44Z

Let's not not let this nested $ delay the implementation of the proposed documentation. We can follow up later with improvements to remarkableKatex.js.

kevinbarabash

LGTM I'm excited about this new direction for our documentation.

Fixes zulip#10091. `https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX` has been moved from the wiki to the docs at https://khan.github.io/KaTeX/docs/supported.html in KaTeX/KaTeX#1484.

Fixes #10091. `https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX` has been moved from the wiki to the docs at https://khan.github.io/KaTeX/docs/supported.html in KaTeX/KaTeX#1484.

Fixes zulip#10091. `https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX` has been moved from the wiki to the docs at https://khan.github.io/KaTeX/docs/supported.html in KaTeX/KaTeX#1484.

website/docs: initial commit

2c4826f

ylemkimon added 7 commits July 16, 2018 08:04

Change secondaryColor

83b92d1

Fix index.css not being copied and included on global stylesheet

35bdfeb

Fix stylesheet link

4ef4bac

[skip ci]

Change documentation link to API(Usage)

1b80492

[skip ci]

Add Libraries in usage

782bf59

[skip ci]

Remove documentation from README.md and add link to the site

456cd9e

[skip ci]

Use KaTeX in the parent directory to build Markdown

6a17b76

[skip ci]

kevinbarabash reviewed Jul 18, 2018

View reviewed changes

ylemkimon mentioned this pull request Jul 18, 2018

use yarn instead of npm #1490

Closed

kevinbarabash mentioned this pull request Jul 22, 2018

Add test job to CircleCI #1235

Merged

Merge branch 'master' into website

5868021

ylemkimon mentioned this pull request Jul 23, 2018

Change build directory to dist and cleanup NPM scripts #1500

Merged

Revise function support page. Avoid error msgs.

5c329cd

Merge branch 'master' into website

29e24c7

General edit to function support page

e772e9c

Merge branch 'master' into website

0a03484

kevinbarabash approved these changes Jul 27, 2018

View reviewed changes

kevinbarabash merged commit 8a38035 into KaTeX:master Jul 27, 2018

edemaine mentioned this pull request Jul 27, 2018

[Meta] KaTeX Website & Documentation #1505

Closed

20 tasks

ylemkimon deleted the website branch July 27, 2018 23:57

shubham-padia mentioned this pull request Jul 28, 2018

tests: Build failing due to dead link. zulip/zulip#10091

Closed

shubham-padia mentioned this pull request Jul 28, 2018

help: Replace dead link to function support wiki in KaTex. zulip/zulip#10093

Merged

ylemkimon mentioned this pull request Aug 18, 2018

Release v0.10.0-rc #1634

Merged

1 task

snyk-bot mentioned this pull request Feb 23, 2020

[Snyk] Upgrade katex from 0.9.0 to 0.11.1 saurabharch/Rocket.Chat#1

Open

KaTeX website & documentation #1484

KaTeX website & documentation #1484

Conversation

ylemkimon commented Jul 15, 2018 • edited

codecov bot commented Jul 15, 2018 • edited

Codecov Report

ronkok commented Jul 15, 2018

ylemkimon commented Jul 16, 2018

kevinbarabash commented Jul 18, 2018

kevinbarabash commented Jul 18, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ronkok Jul 20, 2018 • edited

Choose a reason for hiding this comment

ronkok Jul 20, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kevinbarabash commented Jul 22, 2018

kevinbarabash commented Jul 22, 2018

kevinbarabash commented Jul 22, 2018

ylemkimon commented Jul 22, 2018 • edited

edemaine commented Jul 23, 2018

ylemkimon commented Jul 24, 2018

ronkok commented Jul 24, 2018

ylemkimon commented Jul 25, 2018 • edited

ronkok commented Jul 25, 2018

ylemkimon commented Jul 25, 2018 • edited

ronkok commented Jul 25, 2018 • edited

ronkok commented Jul 26, 2018

kevinbarabash commented Jul 27, 2018

kevinbarabash commented Jul 27, 2018

kevinbarabash commented Jul 27, 2018

edemaine commented Jul 27, 2018

ronkok commented Jul 27, 2018

kevinbarabash commented Jul 27, 2018

kevinbarabash commented Jul 27, 2018

ronkok commented Jul 27, 2018 • edited

ronkok commented Jul 27, 2018

ronkok commented Jul 27, 2018

kevinbarabash commented Jul 27, 2018

ronkok commented Jul 27, 2018

kevinbarabash left a comment

Choose a reason for hiding this comment

ylemkimon commented Jul 15, 2018 •

edited

codecov bot commented Jul 15, 2018 •

edited

ronkok Jul 20, 2018 •

edited

ronkok Jul 20, 2018 •

edited

ylemkimon commented Jul 22, 2018 •

edited

ylemkimon commented Jul 25, 2018 •

edited

ylemkimon commented Jul 25, 2018 •

edited

ronkok commented Jul 25, 2018 •

edited

ronkok commented Jul 27, 2018 •

edited