Articles

How to embed CodePen and JSFiddle in MadCap Flare

So you’re already comfortable working with code examples in your documentation. Maybe you’ve even read our article about inserting code snippets in Flare with Prism.js. But now that you have a taste of the possibilities that can take your code from boring to beautiful, are you itching for new ways to step up your game as a software tech writer?

Classic code snippets are a great solution for displaying a few lines of simple code, but are decidedly less useful when you need to show HTML, CSS, and JavaScript all together. Lines of code can add up quickly, and your user can easily find themselves scrolling into oblivion if you resort to using code snippet after code snippet.

There’s an elegant way to showcase multiple code languages in Flare?

You bet! You can pop your code into CodePen or JSFiddle and neatly package it up into an embeddable interactive widget. If you haven’t yet used either of these tools (or the others like them), they are online development playgrounds that allow you to view your HTML, CSS and JS code simultaneously along with the end result:

Not only are these neat tools to use for your own coding online, but embedding your Pens and Fiddles directly into Flare can really amp up your documentation. Whether your users are new to coding or are programming masters, this dynamic style of presentation can really boost their understanding (and it looks pretty snazzy, too).

I’m sold! But should I use CodePen, or JSFiddle?

When it comes down to nuts and bolts, both tools are very similar. If you don’t yet have experience with either one, your best bet is to try both of them out and see which UI you prefer. One major difference is that CodePen runs your code automatically, whereas JSFiddle requires you to press a button. The rest mostly comes down to aesthetics and personal preference.

If you feel adventurous, you can try your hand at other similar tools — CodePen and JSFiddle are some of the more popular options, but other choices exist.

Let’s get started. How do I embed my code from CodePen?

Just follow these steps:

1. Visit codepen.io.
2. Log in to your existing CodePen account, or create a new one by clicking Sign Up.
   
3. In the CREATE section of the sidebar, click Pen to create a new Pen.
   
4. In the page that opens, enter your HTML, CSS and/or JS code. Your code will run automatically, and you will be able to see the result in real time.
   
5. Once you are done monkeying with your code, click Save.
6. To get the code you need to embed your Pen, click Embed in the bottom right corner.
   
7. Edit the settings, if desired.
   

   Tip: If you have a Pro account with CodePen, you can check Make code editable to allow others to play around with your code and see the results. This not only increases the cool factor of your documentation, but also makes developers very happy!

8. In the Copy & Paste Code section, make sure the HTML tab is selected.
   
9. Copy the code.
10. In MadCap Flare, open the topic where you want to embed your Pen and view it in the Text Editor.
    
11. Paste the code, and don’t panic when Flare warns you that the line containing the <script> tag contains an unexpected token. This happens because the async attribute must take a value to be considered valid XHTML.
    
12. To fix the warning, replace <script async src= with <script async="async" src=.
    
13. Save your changes, publish your project, and admire your embedded Pen!
    

How do I embed my code from JSFiddle?

We’ll walk you through it step by step:

1. Visit jsfiddle.net.

   Tip: If you sign into an existing JSFiddle profile or create one, you will be able to save your finished Fiddle to your account and delete it in the future. That said, it won’t be necessary for our purposes, as long as you are okay with making your Fiddle public.

2. In the page that opens, enter your HTML, CSS and/or JS code.
   
3. To try running your code, click Run.
   
4. Once you have finished crafting your code, click Save. In the bubble that pops up, read the warnings and click Save fiddle.
   
5. Refresh the page.
6. Click Embed to display the code for embedding your Fiddle.
   
7. Edit the settings, if desired.
   
8. In the Embed snippet section, click Prefer iframe? (this format cooperates better with MadCap Flare).
   
9. Copy the code.
   
10. In MadCap Flare, open the topic where you want to embed your Fiddle and view it in the Text Editor.
    
11. Paste the code, and don’t stress when Flare complains that the line containing the <iframe> tag contains an unexpected token.
    
12. Delete both the allowfullscreen and allowpaymentrequest attributes. To make a long story short, Flare doesn’t play well with these attributes and they aren’t necessary for your Fiddle to work. In addition to getting rid of the pesky warning, this will tidy up your code.
    
13. Save your changes, publish your project, and admire your embedded Fiddle!