Katex: Trouble with fonts in local build due to symlink

[ronkok]

I am testing some work in a local node server version of KaTeX, from localhost 7936 as described in the Contributing to KaTeX page. I have a couple of problems:

(1) Several fonts are not available. The console warnings read Failed to load resource: the server responded with a status of 404 (Not Found).

(2) I cannot re-create the stacked sans-serif work from PR #1009. Instead, I get:

@kevinbarabash, When I reported the first problem earlier, you suggested that I run git submodule update --init --recursive. I've done that and gotten no relief. Also, yesterday I completely deleted my ronkok/KaTeX repository and created a new one from scratch. It seems to me that if I do that, then follow the instructions in the Contributing to KaTeX page, the node server version of KaTeX should then work without any further git submodule commands.

I would appreciate any suggestions.

[edemaine]

@ronkok I have a theory: the static/fonts -> ../submodules/katex-fonts/fonts symlink isn't working on Windows. Can you confirm that you're on Windows? Can you check what static/fonts looks like?

[kevinbarabash]

If that's the case, we can change the katex-fonts submodule to live at fonts.

[ronkok]

Yes, I am on Windows.

static/fonts is a file with no extension that contains the text ../submodules/katex-fonts/fonts

One would think that ought to work. It certainly points to a folder that contains all the needed font files. But sad experience says that it does not work.

[ylemkimon]

On Windows, Git symlink does not work. You have to manually create a symlink by mklink /J static\fonts X:\absoule\path\to\submodules\katex-fonts\fonts. (EDIT: The target should be absolute path)

[ronkok]

@ylemkimon, thank you for the information. A web search also brought up the discussion at: https://stackoverflow.com/questions/5917249/git-symlinks-in-windows#16754068

It all looks quite complex. I like the suggestion from @kevinbarabash. Something that does not involve a symlink.

[kevinbarabash]

Cool. I'll add a katex-fonts folder at the root level which will contain the katex-fonts repo as a submodule. I'll need to changes all the places where we reference static/fonts to reference katex-fonts/fonts and we should be okay.

[ronkok]

@kevinbarabash, thanks. There's no rush. At least a week will go by before I can spend much time on KaTeX.

[edemaine]

@kevinbarabash Sounds like a good plan. The symlink was convenient for not changing old paths, but shouldn't be necessary, so let's avoid them.

[ylemkimon]

How about moving fonts.less to the submodule(KaTeX/katex-fonts)? I think it makes sense since fonts.less is importing font files and it should be version-controlled with them. Also it can be auto-generated using buildFonts.sh.

[ronkok]

I hope that works. I've just merged the latest commits from master into my local repository, Having done that, I have now lost all ability to do a local build. Instead, I get 60 error messages telling me that a font file cannot be found. Until the symlink issue is resolved, I am out of action.

[kevinbarabash]

@ronkok sorry to hear that. I'll work on fixing this this evening.

[ronkok]

@kevinbarabash We're making progress on a Windows local build. I'm no longer getting 60 fatal errors. But I am getting one. It is:

Uncaught Error: Module build failed: 

@import "../submodules/katex-fonts/fonts.less";
^
Can't resolve '../submodules/katex-fonts/fonts.less' in 'XXX\GitHub\KaTeX\static'
      in XXX\GitHub\KaTeX\static\katex.less (line 1, column 0)
    at Object.stylesInDom (katex.js:18398)

When I look in the local subdirectory ../submodules/katex-fonts/ I find that fonts.less is indeed missing. Somehow it was omitted when I merged upstream/master into my local repository. I could just manually copy that file from the KaTeX master to my local repository, but I expect you may have other ideas about the proper course of action.

[edemaine]

@ronkok You will have to run git submodule update --init --recursive and possibly before that git submodule sync.

[edemaine]

Is there not a standard hook for doing this automatically?... Would be convenient, but I also haven't seen it elsewhere, so perhaps it's harder than I think.

[ronkok]

Success! Thank you, @edemaine. It worked after I ran git submodule update --init --recursive. The sync was not necessary.

Is it worthwhile to add this bit of wisdom to the Contributing to KaTeX page? At present, the page says that "Most of the time you won't have to worry about [submodules]."

[kevinbarabash]

Most of the time you won't have to worry about [submodules]

I guess that's a bit disingenuous if I keep making changes to KaTeX\katex-fonts. :

[leontepe]

Just came across this because I had the same error on Windows. Shouldn't this be stated in the Building from Source part of the docs as well?
Also, on Windows, I'm getting errors with the cp command in the build script. Changed it to xcopy and it worked, although I'm not sure whether this is the best solution or whether it works on other OS. Still I think this should be mentioned in some way in the guide, I think.

[kevinbarabash]

Yeah, the "building" docs are limited to KaTeX itself and don't include the fonts submodule.

[kevinbarabash]

@leontepe if there are Windows specific workarounds that you've found feel free to submit a PR to add a section with them to that page.