How to insert (pretty) code examples in MadCap Flare
When it comes to your HTML output, it can be tricky to insert code that is highly readable, visually appealing, and up to software developers’ expectations. Fortunately, we have an easy way to make that happen!
They say that form follows function, but we all want our documentation to be eye-catching. If you work in the software industry, you probably know that code examples can sometimes look a little lackluster in MadCap Flare without any syntax highlighting. More importantly, it can be tough to format it the way software developers want it to look. What is a technical writer to do?
I know, I’ll just take pictures of my code!
Snapping screenshots of your perfectly formatted code may be a quick and easy way to get your point across. But what happens when users want to copy your examples and edit them for their own projects? The dazzling beauty of your formatting will quickly fade as the frustrated reader retypes all your code line by line. What’s more, none of the code in your screenshots will turn up in searches, which may mean that fewer people see your work at all.
I pasted my code as text instead, but it’s a complete jumble.
Indeed. You never realize just how valuable line breaks, indents and syntax highlighting are until they’re gone. Deciphering this kind of code makes for a good headache:
But don’t panic! You can always paste your code into <pre><code class="language-xxx"></code></pre> tags, which will at least preserve your indents and display your code in a simple monospace font:
The bad news is that you will either have to settle for plain old black font, or create custom styles for each font colour and apply them by hand. We don’t know about you, but not many people have that kind of time.
Please tell me there’s a better solution for this.
Lucky for you, there is. Thanks to the folks over at Prism (and the makers of other syntax highlighting tools), you can download a lightweight syntax highlighting script that will make your dreams of colourful code come true:
Keen to give it a try? Just follow the steps below.
Download Prism
The first order of business is to download Prism from the website:
- Visit prismjs.com.
- Click the big DOWNLOAD button on the homepage.
- Edit the download settings if you want to customize the colour theme or supported languages.
- At the bottom of the page, click DOWNLOAD JS and DOWNLOAD CSS.
Set up Prism in Flare
Once you have the files you need, it’s time to set up your project to work with Prism:
- In Flare, in the Content Explorer, right-click on the Resources folder and select New > Folder. Name this new folder Scripts.
- Save the .js file that you downloaded in the Scripts folder that you just created.
- Save the .css file that you downloaded in your Stylesheets folder.
- To ensure that your code will be formatted with Prism’s syntax highlighting, you need to import the Prism CSS in your stylesheet. To do so, open Flare, right-click on the stylesheet associated with your target, and open it in the Internal Text Editor.
- Enter
@import url('prism.css');at the top of your stylesheet. This ensures that the code will be formatted with Prism’s syntax highlighting.
- To ensure that the script will run on every page, you will need to call the Prism script in your master page. To do so, right-click on your master page and open it in the Internal Text Editor.
- Enter
<script type="text/javascript" src="../Scripts/prism.js">in the<head>section.
Insert code in your topics
- Open the topic where you want to add a code snippet.
- Using the XML Editor, paste your code into the topic.
- Click the
icon that appears below your pasted code and select Paste Inline Text. This ensures that any special characters in your code (e.g. <,>,&) are converted to HTML entities (e.g.<,>,&). - Switch to the Text Editor and wrap your code in tags (replace “xxx” with the language of your code, such as “html” or “css”).
Last but not least, publish your project and admire your code snippet! You can now add code to your project wherever and whenever it is needed, without losing any of the formatting that you see in your code editor.
