Dynamically publishing a list with the most recent topics

13 Jan 2022

Read time: 4 minute(s)

DITA topics can contain an optional <created> element that specifies the date when they were created by the technical writer.

<topic id="...">
    <title>...</title>
    <prolog>
        <author>...</author>
        <critdates>
            <created date="2022-01-13"/>
        </critdates>

At the time of publishing, we can dynamically generate a topic that contains a list of the most recent topics, while taking the creation date into account for each topic by customizing the WebHelp Responsive output.

DITA WebHelp output can be customized using a publishing template mechanism. Inside a publishing template folder, there is an opt file that can contain links to various XSLT stylesheets that are useful for customizations. For example, we'll add a link to a stylesheet for processing such special keyword label elements:

<publishing-template>
    <name>.....</name>
    ......
        <xslt>
            ....
            <extension file="xslt/updateWhatsNew.xsl" id="com.oxygenxml.webhelp.xsl.createTocXML"/>
            .....
        </xslt>
    </webhelp>
</publishing-template>

The updateWhatsNew.xsl stylesheet will sort the first five most recent topics and create a new DITA topic that contains it:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema" exclude-result-prefixes="xs" version="2.0"
    xmlns:toc="http://www.oxygenxml.com/ns/webhelp/toc">

    <!-- Artifically impose content to the what's new topic. -->
    <xsl:template match="/">
        <xsl:next-match/>
        <xsl:result-document href="{resolve-uri('topics/what_s_new.dita', base-uri())}">
            <xsl:processing-instruction name="workdir-uri"><xsl:value-of select="replace(resolve-uri('topics/what_s_new.dita', base-uri()), 'what_s_new.dita', '')"/></xsl:processing-instruction>
            <xsl:processing-instruction name="path2project-uri">../</xsl:processing-instruction>
            <xsl:processing-instruction name="path2rootmap-uri">../</xsl:processing-instruction>
            <topic xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
                id="topic_v5l_lts_fsb" ditaarch:DITAArchVersion="1.3"
                domains="(topic abbrev-d) a(props deliveryTarget) (topic equation-d) (topic hazard-d) (topic hi-d) (topic indexing-d) (topic markup-d) (topic mathml-d) (topic pr-d) (topic relmgmt-d) (topic sw-d) (topic svg-d) (topic ui-d) (topic ut-d) (topic markup-d xml-d) "
                class="- topic/topic ">
                <title class="- topic/title ">What's New!</title>
                <body class="- topic/body ">
                    <p class="- topic/p ">Most recent blog posts:</p>
                    <section class="- topic/section ">
                        <!-- Find the most recent topics by looking at the creation date and sorting them descending -->
                        <xsl:for-each
                            select="//topicref[@href][not(@format) or @format = 'dita'][doc-available(resolve-uri(@href, base-uri()))][document(resolve-uri(@href, base-uri()))/*/prolog/critdates/created/@date]">
                            <xsl:sort select="document(resolve-uri(@href, base-uri()))/*/prolog/critdates/created/@date" order="descending"/>
                            <!-- Present only the first 5 topics -->
                            <xsl:if test="position() &lt; 6">
                                <xsl:variable name="doc" select="document(resolve-uri(@href, base-uri()))"/>
                                <p class="- topic/p ">
                                    <xref href="{replace(@href, 'topics/', '')}" class="- topic/xref "><xsl:value-of select="$doc/*/title"/></xref>
                                </p>
                            </xsl:if>
                        </xsl:for-each>
                    </section>
                </body>
            </topic>
        </xsl:result-document>
    </xsl:template>
</xsl:stylesheet>

In the DITA Map, we need to add a reference to a stub DITA topic that will be overwritten by the publishing process:

    <topicref href="topics/what_s_new.dita" print="no"/>

The published output will produce a what's new topic as the one here: what_s_new.html.

The WebHelp publishing template used for publishing this blog already has a customization to display a recent list of topics: https://github.com/oxygenxml/blog/tree/master/publishing/webhelpBlogTemplate.