This is not a new feature, but it's a setup we've never documented before: using your own syntax highlighter for code blocks, rather than KnowledgeOwl's built-in syntax highlighter.
We've written up full documentation using Prism syntax highlighter as an example: Use your own syntax highlighter for code blocks.
We're also starting to use Prism across our documentation!
I'm excited about this cosmetic upgrade for our code blocks. It will take time to get everything updated with the right format, but if you'd like to check out our implementation, one of the best showcases is the Create an article table of contents (TOC) page.
We hope that these changes make it easier to view and copy code from our knowledge base into your own.
From one documentarian to another, here are my general thoughts on using Prism, since I'm fairly new to this:
Pros:
- Prism comes with a few different themes out of the box, which made it really fast to get set up.
- It was pretty fast to update the CSS file to use some of our branded colors. I basically did the setup and created a test article with different code types in it, then Inspected to find the classes being used, and updated the CSS file to use our colors. Thankfully, we had something in our color palette that nicely aligned with nearly everything the theme we chose was using.
- For the functionality itself, the Prism site lets you select which languages and which plugins you want, to keep the script as lightweight as possible. I appreciated avoiding the bloat of languages and plugins we didn't need. And some of the plugins are awesome!
- One of those plugins: we're using the copy button (where have you been all my life, Code copy button? I assumed we'd have to do a custom script for this), which automatically adds a "copy" option to code blocks that are being highlighted, almost as soon as you mouse over them. The days of having to manually highlight and copy our code blocks are dwindling as I update the rest of our documentation.
- We're also using the line numbers plugin, which will add line numbering to highlighted code blocks. Initially I thought we'd manually have to add this to each preformatted text block, but after some testing, I was able to get the line numbers to add automatically to all blocks, which simplifies a lot of the manual editing of articles. My solution to that is at the bottom of the doc.
- The line numbers plugin also lets you specify a data-start value so you can specify what row the sample starts at. Really useful if you're giving a big code block and then offering variations on specific rows (as we do in the referenced article).
Cons:
- Prism expects a specific format for the syntax highlighting to be applied (you have to add a class for the language to your code block, and the code block must be inside a preformatted text section). While we generally do use the pre + code combo, it does require manually editing each of our pages to include the appropriate class. On the plus side, anything that lacks the appropriate class still displays, just unhighlighted, so it's not like it's unusable. Just less pretty, until it gets updated.
- I'm a little uncertain how well the setup we documented would work in situations where secure file library is being used and one of our contextual help widgets is also being used. As long as your widget is authenticated, I don't *think* you'd run into major issues, but that setup might benefit from pulling the Prism JS files from CDN and/or hosting the CSS/JS files somewhere outside of KnowledgeOwl, so you could bypass the authentication process.
