Yard server rendering JS assets as markup

[japgolly]

Yo. Ok check this out.

Dir tree

<root>
  +-- doc
     +-- img
     +-- js

.yardopts file looks like this:

--files doc/*.md
--asset doc/js:js
--asset doc/img:img

Now generating the html doc a la yard doc works fine. file:///home/golly/my_project/output/doc/file.TODO.html <-- Markdown from doc/TODO.md appears fine. file:///home/golly/my_project/output/doc/img/pin-red.png <-- Image works fine. file:///home/golly/my_project/output/doc/js/example.js <-- JS works fine.

Start the server however, and results are a little different. http://localhost:8808/docs/file/doc/TODO.md <-- Markdown from doc/TODO.md appears fine. http://localhost:8808/docs/file/doc/img/done.png <-- Image works fine. http://localhost:8808/docs/file/doc/js/todo.js <-- JS is corrupt. It has been treated as a Ruby source file and rendered through the doc template.

[lsegal]

Yes, this is a known issue. The problem isn't that the JS is corrupt, the problem is that manually linking to a js script as a relative file in the server arch will pass through /docs/file/, which is a special route for marked up files. The only way to make this work consistently across file/server would be to have a special markup for inserting scripts, where we can control the generated path, but that probably won't happen as it's fairly messy to inject JS like this. You should really be using template customization to do this kind of thing.

[japgolly]

Oh ok right. Hmm template customisation sounds like quite heavy so I'm gonna probe for alternatives.

1. Why (or how) is it that Images work through the /docs/file/ route without being parsed as markup? If there's a default somewhere to treat *.png files as binary then maybe adding *.js to that list is all that's needed.
2. Is there a way (and would it make sense) to modify the routing or rendering to disable markup on certain files? I'm thinking that if there were a regex available that I could use to say "opt-out of the markup step for any files with a .js extention", then that could be a good solution. I don't a big-picture view here but it seems quick, easy, & low-risk.

[lsegal]

Why (or how) is it that Images work through the /docs/file/ route without being parsed as markup?

Binary files (image files specifically) are treated specially, but this can only be done for binary files, not text files. It's possible that a user actually wants to list the contents of a js file, and that would preclude them from doing so (with jarring results). You could actually hack YARD this way by naming your js file with a .png or .jpg suffix and it will link it as if it were a binary file, but I wouldn't recommend this, and it would likely confuse your browser (since the content-type would be image data).

Is there a way (and would it make sense) to modify the routing or rendering to disable markup on certain files?

Yes, but YARD shouldn't do this out of the box. If it were supported, it would be done through API calls / plugins. Again, embedding JavaScript into your doc output is really in the realm of template customization, and that's how it should be exposed. We open ourselves up to usability and security issues if we let people easily embed and host arbitrary JS on yard doc sites. The use case for embedding JS is really not common enough to warrant a special exception when there is already an acceptable path for this.

[japgolly]

Thanks heaps for the explanation. You have very good points from perspectives I hadn't considered. Ok, I'll go off and think about that. Do you want me to close this issue?

[lsegal]

Closed. Thanks for understanding the concerns!