Fm Publishing: Formatting lists in HTML5

When producing HTML-based formats like HTML5, FrameMaker previously had an option to convert numbered and bulleted lists into appropriate <ol> ordered lists and <ul> unordered list representations, complete with <li> list item elements for each item in the list.

Apparently, that conversion wasn’t 100% solid, and the latest release now maps list items to formatted <p> elements, just like everything else.

And even if you choose the Convert to List (using CSS autonumbering) option, you basically get the same HTML as if you choose Ignore for the Autonumber setting.

I also hear that legacy projects will retain the conversion to <ol> and <ul> elements, which is good news for those that have previously gotten successful output with these settings. This legacy behavior might explain the fact that the CSS autonumbering option remains in the current release.

I would expect that the functionality of lists will be fixed soon in an upcoming patch or release of FrameMaker, but hopefully this “fix” will get you by until then.

The trouble with the new settings

The biggest problem for non-CSS/HTML experts is that the default settings make it difficult to achieve satisfactory formatting. In other words, by default, you get something that looks like this

Instead of something that looks like this

In this post I’ve outlined the steps needed to recreate my work, but for students of my Authoring Unstructured Content and my Formatting Unstructured Content courses, I’ve added a lesson to each of those courses that includes a 15-minute video showing the steps and provided downloads of the relevant CSS modification files to speed up the process.

The step-by-step in FrameMaker

So what we need is a CSS fix to let paragraphs display in the same manner as nested list items. You will need to both modify your CSS for the project, and map the targeted paragraph styles to the new CSS entries.

I’ve worked through the solutions for both ordered lists (“numbered”) lists, and unordered (“bulleted”) lists and here’s what I came up with:

Converting Ordered (Numbered) Lists to HTML5 in FrameMaker 2020

My quick-fix for numbered lists (and nested numbered lists) is to create CSS styles called p.Numbered-FirstLevel and p.Numbered-SecondLevel. You’ll find the actual CSS code at the end of this post.

Modifying the CSS for your project in an external text editor

The easiest way to do this is to:

• use the Manage CSS option in Style Mapping to export your CSS
• open the CSS in a text editor
• paste in my CSS code
• modify the properties as needed
• save the CSS file
• use the Manage CSS option in Style Mapping to import your modified CSS

Mapping your numbered list styles

Once you have the updated CSS imported, use the Style Mapping dialog to map your FrameMaker styles to the new Numbered-FirstLevel and Numbered-SecondLevel CSS entries. Make sure to select the Convert to Text option in the Autonumber section.

Converting Unordered (Bulleted) Lists to HTML5 in FrameMaker 2020

You could also choose to manage unordered lists as I did above with the ordered lists using the autonumber already defined in your FrameMaker paragraph style. While adequate, there’s a cleaner option for bulleted lists using standard HTML list styles, like disc, circle, square, etc.

If you haven’t already added the p.Bulleted-FirstLevel and the p.Bulleted-SecondLevel CSS entries to your project’s CSS, see the Modifying the CSS for your project in an external text editor section above.

Mapping your bulleted list styles

Once you have the updated CSS imported, use the Style Mapping dialog to map your FrameMaker bullet list styles to the new Bulleted-FirstLevel and Bulleted-SecondLevel CSS entries. Make sure to select either the Ignore or the Convert to List (using CSS autonumbering) option in the Autonumber section.

Republish and review

At this point, you should have logical nested lists in your output. However, since your settings may differ from FrameMaker’s default settings, you may still need to modify the various properties specified in the CSS with either the internal FrameMaker Publish Settings CSS editor, or via an external text editor as described above.

I’ve included the CSS code used in my examples below, but CSS can be truly maddening! If you’re getting close, but can’t quite finish it off, consider booking a quick session with me to get the settings straightened out.

Sample CSS entries for numbered and bulleted lists

/*  Map paragraph styles with numbers and bullets to Numbered-FirstLevel, Numbered-SecondLevel, Bulleted-FirstLevel, and Bulleted-SecondLevel as needed.  */
/*  Set styles mapped to Numbered-FirstLevel to use the "Autonumber: Convert to Text option"         */
p.Numbered-FirstLevel {
    display: list-item; 
    list-style-type: none;
    list-style-position: inside;
    margin-left:34pt;
    margin-right:0.000pt;
    text-align:left;
    text-indent:-16pt;
       margin-top:8.000pt;
       margin-bottom:0.000pt;
       font-size:11.0pt;
}

/*  Set styles mapped to Numbered-SecondLevel to use the "Autonumber: Convert to Text option"       */
p.Numbered-SecondLevel {
    display: list-item; 
    list-style-type: none;
    list-style-position: inside;
    margin-left:52pt;
    margin-right:0.000pt;
    text-align:left;
    text-indent:-16pt;
       margin-top:8.000pt;
       margin-bottom:0.000pt;
       font-size:11.0pt;
}

/*  Set bullet style by changing the "list-style-type" value
    See https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type  */
p.Bulleted-FirstLevel {
    display: list-item; 
    list-style-type: disc;
    list-style-position: inside;
    margin-left:34pt;
    margin-right:0.000pt;
    text-align:left;
    text-indent:-16pt;
       margin-top:8.000pt;
       margin-bottom:0.000pt;
       font-size:11.0pt;
}

/*  Set bullet style by changing the "list-style-type" value
    See https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type  */
p.Bulleted-SecondLevel {
    display: list-item; 
    list-style-type: circle;
    list-style-position: inside;
    margin-left:52pt;
    margin-right:0.000pt;
    text-align:left;
    text-indent:-16pt;
       margin-top:8.000pt;
       margin-bottom:0.000pt;
       font-size:11.0pt;
}