Skip to content

Add RunKit embeds to Node documentation [WIP]

This addresses https://github.com/nodejs/node/issues/21723.

This is functionally complete and only has a few cosmetic changes to be made hopefully, namely, choosing the the node examples to turn on in this initial run, and separately choosing the right syntax highlighting theme. I figured it was worth starting the discussion now as it touched a few minor other things, namely:

  1. This change changes nodejs.org to syntax highlight examples at compile time instead of at runtime in the browser.

    Previous to this change, the syntax highlighting on nodejs.org was done at runtime using two scripts that were included in the repo in their minified form, sh_javascript.min.js and sh_main.min.js (which I believe remained untouched since they were originally committed 5 years ago). This made the the RunKit process a bit trickier than necessary, as we would have to first wait for the highlighting to finish before swapping in the RunKit embed. This had a number of other downsides though:

    1. Anyone with JavaScript turned off, or on a slow connection, would see the documentation without syntax highlighting.
    2. Only JavaScript was syntax highlighted.
    3. It is hard to modify syntax highlighting at all due to the minified nature of the scripts.
    4. There was unnecessary load and work done on the user's browser.

    With this change, we're using the standard highlight.js library, which makes it easy to change theme, and additionally means the many many C++ examples on nodejs.org are now syntax highlighted as well (hurray!). Beyond that, the examples will be highlighted instantly of course and it's kind of cool that with the RunKit change most people will actually be loading less JavaScript.

  2. As part of the change above, I've taken the standard hopscotch theme.

    I have no particular strong feelings either way about this. Hopscotch seemed to fit well and I was going to translate the existing theme, but it seemed to only highlight keywords as green. I am happy to just do that as well, but hopscotch is very subtle too and, especially for the C++ examples for example, enhances readability. Again, I'm happy to directly translate the existing CSS, or alternatively, if anyone wants to just suggest any of the many many existing highlight.js themes I'm happy to switch to that.

OK, with that out of the way, the meat of the change:

This introduces the ability to add "runkit" to code blocks, turning them into runnable examples. For example:


    ```javascript runkit
    console.log("This example is runnable!")
    ```

The nice thing about this is that the examples continue to syntax highlight correctly in Github as Github just ignores everything after the initial language tag. As explained in the above bug, we're hoping to make this a major part of the full API redesign, but want to do some initial tests (scaling, etc.) on the current site. Currently this commit only includes a crypto example we know to work well, but we're hopefully going to be turning on around 5 - 10 total examples, which we'll be updating this PR with in the next couple of days.

A quick note on the way we've added RunKit: since there is only one template file used for every page, I've created a super tiny script that checks whether any example is runnable on load, and only then adds the runkit script tag. Again, since we're removing much more JavaScript than this already with the syntax highlighting change described above, this should improve load time overall. When we make the full API redesign, the ideal would be to include a defer-ed runkit script tag on pages that use it, and leave it out completely on those that don't.

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines

Merge request reports

Loading