Madcap Flare 11 - HTML5 Output without a Skin? Imposibruu!

If I had a blog dedicated to tech writing, I would definitely post this on it. But since this is my general-purpose-geek-whatever-goes-blog, it comes to reason that "miscelaneous" stuff would come here, right?

In this post I'll take you on a short adventure I've recently had while trying to deeply customize the HTML5 output generated by MadCap Flare 11, after recently upgrading to it from version 7. If you're familiar with Flare, you know that doing Web output can be pretty involved - there are a lot of moving parts, including Master Pages, Skins, Stylesheets and Proxies, to name a few.

Essentially, the goal here is to provide you with a blank canvas where you can customize, almost 100%, the HTML5 output generated by Flare. This can be super useful if you're a) a web designer yourself or b) have a web designer available to do that work for you. And, it becomes almost indispensible if you have a "corporate" style that you want your documentation to be as close to as possible.

There's only 2 things that are really required to make this work as an example. The rest of the "useful" stuff we'll add later:

1. A Master Page. This is where you'll add your design, around the body proxy.
2. The Target needs to be in HTML5 and NOT use a skin. 

Sounds simple does it not? Actually, it is, once you've figured out what's necessary - I've done that work for you, you're welcome! Let's dig deeper.

The Master Page

So the Master Page is just HTML code that's inserted around your body text, on each file that's created in your output. We're going to use this to create our "design". Let's start with something really, really basic just to give you a feeling of how "simple" it can be. Create a Master Page by going to the Project Tab, then going into New -> Add Master Page. Give it a name, like, say, "No-skin". (Note: You might already have a "basic" Master Page. If so... skip on to the next section, as the build-in master pages are pretty much built the right way!)

Go to the "Text Editor" view and paste the code provided: Pastebin link

If you've ever worked with HTML you'll recognize just about everything here, with the only exception of the MadCap:bodyProxy element. This is basically the placeholder for the contents of your topic, aka everything in the tag of that topic.

Alright, now this is a very basic Master Page that contains nothing in terms of navigation, but we can add that in a second. Let's move on to the next step.

An HTML5 Target that doesn't use any skins

So now we get to the interesting part: building the target. Go to Project -> New -> Add Target. Make sure the Output Type is set to HTML5, give it a name (my-user-guide, or whatever) and click Add.

In the properties, the following things need to be change:

• In General, ensure that the Master TOC and Master Stylesheet have been attributed values.
• In Skin, use the drop-down to change "Skin" to "(none)".
• I Advanced, go to Master Page and change it to Resources/MasterPages/No-Skin (or whatever you named it).
• If you want to change other options like conditions and variables, go ahead. 

And now the fun part. Save this target, and hit Build. After the build is done, click on View and open it in your favorite browser. Should look something like this:

Adding navigation and other proxies

So the above preview looks really dull, right? Of course it does, because there's no navigation, no toolbar... Only the header (I added to my master page as above), and the contents of one topic. 

Now what we can do is start adding proxies into the Master Page, to start giving us some useful stuff to work with! In the XML Editor view of the Master Page, you can insert the following proxies:

• The Breadcrumbs proxy (You are here!)
• The Topic Toolbar proxy (which shows links such as highlighting, print and such)
• The Search Bar proxy which adds the search box and button
• The Menu proxy, which is used to display the Table of Contents. When adding the TOC, to start with I suggest unchecking Context sensitive and changing Levels to Show to (all). You can customize it later on. 

Alright... now we're talking! Check this out:

So everything we really need is here - we just need to style it properly! Obviously, this is where the expertise of a web developper normally comes in. But I'm a great gal so I'll provide you with a complete project at the end of this post. In the meantime, here's what it looks like with a bit of HTML tweaking and some CSS styles:

Ok so in this case I'm reproducing more or less the "typical" webhelp tripane design. But it doesn't need to be this way. You could place the TOC on the right in a floating sidebar, you could have the TOC drop-down from the left or right or have it fly around avoiding the user's cursor... whatever, basically. My point here is that the sky's the limit and your web developers will be happy to know that they can tweak this to the point where it will look like what you want, from top to bottom, start to finish. And, by the way, you can add conditions, variables and anything else in the Master Page that you would in a normal topic. So that's awesome too.

Custom Search Results Page

One issue I came up with later in my design is that the Search Results page wasn't using the Master Page, and I wasn't sure how to proceed. Some help from the Madcap forums later, the solution came about: Create a new topic inside the Resources/MasterPages folder of your project (I called it "searchresults.html", the name doesn't matter), and simply add the Search Results Proxy inside of this topic: double-click on it, remove all the contents then go to Insert -> Proxy -> Search Results Proxy. I believe it's a workaround for a bug (as this writing, in Flare 11). But that topic in a custom location is all that's necessary, thankfully.

Need more help?

Post on the Madcap Flare forums, or comment below!