Aim: Create new custom section with icon
Paligo has a built-in feature for adding attractive notes, cautions, and warnings to your content. Each note, caution, and warning has some css styling applied by default. You can see the styles for the help centre layout below, which use a pastel background and a font awesome icon.
You can also create your own sections and set them to have a similar appearance. Note that I am using the term section to mean a piece of text like a note here, rather than the <section> element.
NOTE: The following method of creating an informal topic template is not the recommended way of doing this in structured text. To do it properly, you need to get a customisation implemented by Paligo, so that there is a new admonition with appropriate elements for your custom content. Also, my work-around will only work on HTML5 outputs. PDF would need a customisation.
On one of my Paligo projects, I created a section for permissions and gave it a grey background, sidebar, and padlock symbol. The idea was that before each task, the permissions section would be shown. This way, users can quickly identify whether their user account has the permissions needed to access the features described.
There are several steps you need to follow to create your own custom section:
As you’re going to use the new section in lots of different topics, you should create it as a template.
- In the Templates section, create a new folder and give it a meaningful name. For my project, I called it Permissions.
- In the new folder, create a new informal topic.
- Edit the informal topic.
To style the content of your informal topic, you need to be able to give it a class. You can then assign styles to the class in a CSS file. To give the informal topic a class, you need to set the Sidebar element’s Role attribute.
- Select the Sidebar element.
- Add a Role attribute.
- Set the name of the Role attribute to the name you want the class to have in the CSS file.
- Add any text that you want to appear every time the new section is used.
- Select Save.
So far, you have created an informal topic template. When you want to use the informal topic in a regular topic, you first need to create a new informal topic based on the template. You can then add content to the new informal topic as needed, and embed it into a regular topic as a component.
- Create a new informal topic based on the template. Go to Create Content and choose From Template. Then choose the template you created for your informal topic. Paligo creates a new informal topic that already has the settings and content from your informal topic template in place.
- Edit the new informal topic and add any content that you want to appear in this instance of the informal topic only.
- Edit the topic that you want to contain the informal topic.
- Position the cursor at a position in the topic where an element can be embedded. You may need to add a new para element for this.
- Select Insert > Component and select the informal topic you want to embed. The informal topic is embedded in the topic. It contains the text and role attribute that you defined in the template. It also contains any content that you added when you created the informal topic based on the template (step 2).
- Select Save.
Paligo doesn’t convert role attributes to class names by default. You have to enable this feature in the layout.
- Select Layout. This is in the menu at the top of the screen.
- Select the layout you use for the publication or create a new one if you don’t have a layout.
- In the layout settings, select Classes and Attributes.
- Enable ‘Set output role attribute as class names‘.
- Select Save.
Next, you need to define how you want the new informal topic to look. You don’t do this in Paligo, you do it by creating a CSS file that you will then associate with your publication’s layout. You can use pretty much any CSS editor.
I find it easier to create a publication in Paligo first, so that you have an output with the default settings for the informal topic in place. You can then open it in Chrome and use the Inspect feature to view and edit the CSS and experiment with different styling. (Other browsers are available).
The styles you need to add to your CSS for the new informal topic are:
You will need to replace permissions-box with the name you gave to the Role attribute for your informal topic template. For example, if you gave it the role name spartacus, you would have CSS for .spartacus > p instead of .permissions-box > p and so on. In the code example above, I styled the box to be grey with a slate grey left border and a slate grey icon. The icon code is f040 and this comes from the Font Awesome set. I was only able to get some of the icons to work, which may be because the help centre HTML5 output is still in beta at the time of writing. Or it may be a limitation of only using a free Font Awesome licence. If you know why some icons don’t work, please let me know!
The last step is to add your CSS file to the layout for your publication.
- In Paligo, select Layout and edit the layout you want to use.
- In the General settings, upload your CSS file and then Save.
Finally, add your topic to a publication and publish it using the layout that is linked to your CSS file. In the output HTML5, the CSS styles you have defined are applied to the informal topic. The role attribute of the section is converted into a class name in the HTML5 output (proceeded by sidebar, for example, class=”sidebar permission-box”. In the CSS file, your sidebar.permission-box class styles define how the custom section is presented.
By following the steps I’ve mentioned, you should be able to create your own section with icon. If you run into problems, check that:
- The CSS file is valid (there are lots of free validation services online), has the correct .css file extension, and is linked to your publication’s layout.
- You have selected the correct layout for the publication.
- If the icon does not appear, that may be a problem. I’ve had some issues with certain icons too.
Note that every time you want to use your new section, you will need to create a new informal topic based on the template. You can then edit the informal topic and insert it into a topic as a component. You do not select the new section from the menu or the Custom settings on the create content dialog.
Craig Wright is an experienced technical writer based in Chesterfield, UK. He hates writing about himself in the third person, so I shall stop now.
Always interested in new content writing opportunities. Remote working preferred.