Katex: [Meta] KaTeX Website & Documentation

[ylemkimon]

This is a meta-issue to track website and documentation related tasks.

• [ ] Improve and organize Options(options.md) documentation: #1599
• [ ] Enable use of "|" character inside a KaTeX expression inside a markdown table
• [ ] KaTeX internals documentation: #1096
• [x] Setup CircleCI to build and deploy website: #1588
• [x] ~Better macro documentation: #1176~
• [x] ~Sandbox/Demo/REPL: #1244~
• [x] ~Skip tests if only documentations are changed: #1166~
• [x] ~Who is using KaTeX list: #305: #1569~
• [x] ~More examples: #275, #661, #1064~
• [x] ~Fix function support page overflow on smaller screens: #1556~
• [x] ~Add redirects from original documents: #1576~
• [x] ~Use built CSS: #1584~
• [x] ~Improve remarkableKatex to enable nested $ delimiters: #1576~
• [x] ~Include other contrib documentation, maybe extensions/plugins page?: #1566~
• [x] ~Dedupe documentations, most documentations are copied from README.mds, source codes, and the wiki. Either remove original docs or copy(auto-generate) at the build: #1566~
• [x] ~Mobile-friendly(responsive) main(index) page: #1547~
• [x] ~Modify release script to build and deploy website: #1521~
• [x] ~Supported function list/support matrix(maybe auto-generated): #1536~
• [x] ~Setup netlfiy to build and deploy website: #1510~
• [x] ~Function support page: fix excess padding in environment table~

[ronkok]

@ylemkimon The CSS for the new function support page comes from https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css, but the JavaScript and fonts are coming from the local build.

In a possibly related matter, it is not rendering \not = properly. Is that because the fonts and CSS are out of sync?

[edemaine]

Now that #1484 is merged, it seems that someone needs to actually push the updated docs to the gh-pages branch. (I believe only @kevinbarabash can do so without a PR.) Right now, a lot of our documentation is missing from the public web.

[ronkok]

If I understand how this works, then the new function support page gets its katex.js from a dist folder at the root. Is that how we want the docs to work? Or do we want them to get KaTeX from the same CDN as everybody else?

[edemaine]

@ronkok It's definitely how we want it to work in development. When we publish to gh-pages (which I guess we do every release, not every commit, so that we document the release not the master branch?), we could imagine changing to use the CDN... but probably fine as is too. Is there an easy way to see old versions of gh-pages, and thus documentation for older versions?

[ronkok]

It's definitely how we want it to work in development.

Agreed.

Now let's address the function support page that is on the public web. I'm unclear on how that is supposed to work but my experience is that the katex.js and katex.css are not in sync. The CSS comes from the CDN. The JavaScript seems to come from the dist folder in the local build. Must https://khan.github.io/KaTeX/ contain a dist folder in order for the public build to occur and work properly? Or is the build done locally and then the built page is copied to https://khan.github.io/KaTeX/?

If it comes from a local build and the build is from the current master, then the docs show a version of KaTeX that isn't yet released. That seems unwise. Sometimes we catch and fix bugs in master before they are released.

Is there an easy way to see old versions of gh-pages?

I'm not aware of any way that I would characterize as "easy". I believe this is one of the items on the punch list above.

[kevinbarabash]

https://khan.github.io/KaTeX/ seems to work fine. I haven't run the publish-gh-pages yet. I can do that, but I thought it'd make sense to wait for the next release.

[kevinbarabash]

The gh-pages branches hasn't been updated since June 15th.

[kevinbarabash]

In terms of publishing multiple versions of the docs we could look at using netlify although that's not ideal since I the URL to old versions might look a little weird. We could also publish docs to a separate repo where all versions of the docs would live in separate folders.

[ronkok]

https://khan.github.io/KaTeX/ seems to work fine.

Yes, but the KaTeX README page had a great deal of material deleted. That material is now on the new docs. Those new docs do not appear anywhere on the public web and won't until a publish-gh-pages occurs. So @edemaine is correct. Quite a bit of our documentation is, at this moment, hidden.

[kevinbarabash]

So I ran npm run build in the root KaTeX folder first to generate dist b/c the website depends on it via the require("../") in remarkableKaTeX.js and then I ran npm run publish-gh-pages from the website folder but ran into an issue when it asked me for my password to https://[email protected]. @ylemkimon any ideas of what's going on?

[kevinbarabash]

I solved the issue by running export USE_SSH=true first.

[kevinbarabash]

The new documentation is live. Sorry for the delay.

[edemaine]

Thanks @kevinbarabash! Two questions given the process it took: Should npm run build be part of npm run publish-gh-pages script? Should we add documentation about the USE_SSH script?

[kevinbarabash]

I think we should actually have website/package.json depend on a specific published version of KaTeX. The workflow would be: publish KaTeX, update the dependency in website/package.json, publish the website.

I think we can include USE_SSH=true; in the publish-gh-pages command.

[edemaine]

Another simple measure for multi-version documentation: We could consider publishing compiled documentation under npm publish and the release ZIPs on Github.

I do like the version dropdowns of e.g. http://getbootstrap.com/, but it might be overkill for us, where we generally always want people to upgrade.

[kevinbarabash]

@edemaine I created https://github.com/Khan/KaTeX/issues/1509 to track having multiple versions of the docs.

[ylemkimon]

I wonder we should have a domain, e.g., katex.io.

[ylemkimon]

I'll close this issue, as most of tasks are done. I've opened issues for remaining tasks that don't have separate issue.