I spent a little bit of time trolling around trying to figure out how to use a pretty print-type add-in in RoboHelp. I had a lot of trouble with this, primarily because RoboHelp would de-register the baggage or totally ignore the second style sheet (and delete references to it from topics!
After a lot of playing around during a recent custom responsive layout build, I finally found a product and setup that works. It does require a bit of finessing, but if you’re savvy, you should be able to get it to work!
I haven’t tested this setup in every version of RoboHelp or in any other scenarios. That said, it should work in other versions. If your setup is different, post your results in the comments and let me know how it worked for you!
This is my current authoring setup:
- RoboHelp 2017, R2
- Windows 10, 64-bit
- svg, two workstations and one build machine
- highlight.js, v.9.12.0, download version, custom package.
- Visit highlight.js.
- Click the Get version 9.12.0 button (new versions will change this button name, please just click the button no matter the number!).
- On the Getting highlight.js screen, scroll down to the Custom package section. Click to select or de-select the code types you need to pretty-print. Be liberal, if you think you might need it in the future, click it. The package isn’t huge. 🙂
- Click Download.
- Locate the downloaded file hightlight.zip and extract the contents.
- Open the extracted highlight file.
- Copy the highlight.pack.js file to your clipboard.
- In your RoboHelp project, create a folder called js in Project Files.
- Right-click your new js file and select Explore….
- In the js folder in Windows explorer, paste the previously copied highlight.pack.js file.
- Back in RoboHelp, right-click the js folder, select Import Baggage, then click File.
- Double-click the highlight.pack.js file.
- Return to the highlight.js web site.
- Browse through the different languages and styles (click the links under the code block) until you find a style that you like, making note of the style name.
- Return to the opened highlight folder and double-click the styles folder.
- Locate the .css file that corresponds to the name of the style that you want to use and open it in Notepad or Notepad++ (or your own preferred text editor).
- Copy the entire contents of the file to your clipboard.
- Back in RoboHelp again, locate your project style sheet (generally default.css, but yours may be named differently). Check out the file, if necessary, and open it in your text editor (right-click>Explore, double-click or double-click if your file associations are set in RoboHelp. DO NOT edit it with RoboHelp’s stylesheet editor).
- Go to the end of your default.css and paste the contents of the highlight.js stylesheet in your style sheet.
- Save your changes.
Whew! Now you have highlight.js installed, how do you actually use it in topics?
You will need two blocks of code, inserted in the html of your topics, to make a code sample pretty:
This first block of code you will paste in your topic head, just before the </head> tag :
IMPORTANT: Make sure that the path to the package, ../js/highlight.pack.js, matches the path to the default.css file in respect to the path. Your topic may be several layers deep relative to the css and js files, the path should reflect that. For example, if the topic’s path to the stylesheet is ../../../default.css, then the path to the js file should be ../../../js/highlight.pack.js. In other words, make sure that the number of ../ sequences before the js/highlight.pack.js is the same number of ../ sequences before the default.css.
The second block is pasted in the html in the position that you want to insert your code sample:
Paste the code after the <code> tag and before the </code> tag!
Here’s what your code will look like, these two code blocks are highlighted in yellow:
Templates (.htt files)
You can add the first code block to a topic template, but it only works if the template is used on topic creation. If you add the code block to the .htt file, it will only work on new files created from that template. You will still have to place the script in the html heading manually for topics that have already been created.
Code sample prep
Before you paste your code sample inside of the second set of tags, you need to do a little bit of prep work so that it actually works properly when you paste it in. I find that Notepad++ is the best tool for doing this. It’s free, and the tasks listed use steps from that program.
- Open Notepad++ and paste your code sample in a new file.
- On your keyboard type CTRL + F.
- Switch to the Replace tab.
- In the Find what: field, type >
- In the Replace with: field, type >
- Click Replace All in All Opened Documents.
- In the Find what: field, type <
- In the Replace with: field, type <
- Click Replace All in All Opened Documents.
- On the Edit menu, select Blank Operations, then click TAB to Space.
- Copy the code sample and paste it in your RoboHelp topic between the <pre><code> and </code></pre> tags.
The screenshot above shows what your pasted code looks like after inserting it.
There are a few things you need to know about when working with topics.
- Once you paste the second code block in, do not switch back to Design view for the topic before you place your code sample in. RoboHelp doesn’t like the <code> tag inside of the <pre> tag and will delete it if you do not have content inside of the tags.
- Add pre to your .css file if you want to further style the code block by adding margins, changing fonts, etc. Watch out, though, because RoboHelp doesn’t really like this, either. Always keep a backup of your css file, as RoboHelp will delete this pre class if you edit the css file using the RoboHelp stylesheet editor.
- Add a class to your css file, I use .long, to add a max-height or other specific styling to code blocks when the code sample is very long. I have some pages with multiple code samples that I use class=”long” on to limit the blocks to 200px in height.
- Always preview your topic to make sure the highlight is working. It will not display in a formatted manner inside of your RoboHelp editor, it will look like a div. If the preview doesn’t display properly, look at the path to the highlight.pack.js file in the topic heading, and check to make sure that you did your code sample prep work before pasting it in the page.
This is what your code sample will look like, or what mine does based on my selected style (blurs added to protect privacy):
Did I miss anything? Have you been able to get a different prettyprint package to work with RoboHelp? Please let me know in the comments!