Quick Start Guide

Your Content Portal Environments

The Heretto Deploy Portal includes multiple environments for development and testing to facilitate your Content Portal development.

Heretto CCMS provides the tools you'll need to have a single source of truth from where you can manage all of your portal environments' configurations and styling. The Heretto team handles hosting and base code updates.

You can configure and customize your Heretto Deploy Portal using your web browser and your portal environments. We recommend having Heretto CCMS open in one window and a portal environment open in another. You can make configuration and stylings changes in the CCMS for the respective environments, then see the change immediately reflected in the portal.

Your Heretto Deploy Portal comes with three environments:

CUSTOMER-DEVELOPMENT

This is where you can make styling and configuration modifications, testing against a sample content set

STAGING

Promote your styling and configuration changes to staging and perform testing against production-ready content.

PRODUCTION

This is the live environment where your visitors can access your content.

You can maintain different config.json files for different environments, which are tagged as environment specific in <data> elements in your sitemap. For more details on adding config.json files to your sitemap, refer to Customize Your Content Portal.

To customize and test your configuration changes, we recommend using multiple configurations files, along with a CSS file and a JavaScript file, if necessary. For example, you can use one for configuration, one for styling, and one for any JS you want to include. All three will be hosted in the Heretto CCMS and referenced in the sitemap using <data> elements.

We recommend using different config.json files, one for each portal environment, to manage your custom configurations of your Heretto Deploy Portal environments. Most often, there are dev, qa, and prod versions of the configuration files. Each one controls a different portal environment, and each specific configuration file works in conjunction with the base configuration file.

Having multiple configuration files enables you to safely test changes in multiple different environments and save those changes separately from one another. For more information on using multiple configuration files, refer to Configuration Layers and Overrides.

Example of multiple configuration files in a sitemap

Important Files

You can modify your Heretto Deploy Portal by adding and editing the configuration and style files in your Heretto CCMS. Each configuration and style file has a specific purpose and is responsible for different parts of the Heretto Deploy Portal.

Configuration File

We defined multiple settings that you can use to align the Heretto Deploy Portal to your needs by editing the config.json file. The configuration file can be edited directly in the Source Editor in Heretto CCMS. It enables you to edit elements like:

  • title

  • logo

  • the way programming code is interpreted and presented online

  • content placeholders displayed upon triggering different actions

  • footer contents.

JavaScript Object Notation (JSON) formatting rules apply. You can validate your new code with third-party JSON validators. Following the patterns and code examples mentioned in our documentation is enough to modify the config.json file, which means that expert-level knowledge about JSON is not required.

For more information on preparing and uploading the config.json file, see Customize the Content Portal Settings.

Style File

You can make your Heretto Deploy Portal match your brand's visual identity by applying your own CSS styling. You can maintain the code directly in Heretto CCMS and edit it in the Source Editor.

Note: If you are not familiar with Cascading Style Sheets (CSS), you can refer to third-party tutorials like https://www.w3schools.com/css/.

The CSS file is used for styling elements like:

  • fonts

  • links

  • backgrounds

  • padding and margins

  • borders

  • sizes.

It is also used for changing the way different DITA elements are displayed. For example, you can change the way different types of DITA <note> elements are presented.

Tip: CSS classes of rendered DITA elements remain the same both in Heretto Deploy and Heretto PDF Generator. Therefore, it is possible to import a common external style sheet in both cases to preserve a consistent look of DITA elements regardless of the output.

For more information on preparing and uploading the .css file, see Customize the Content Portal Style.

Script File

You can modify the way your Heretto Deploy Portal behaves and introduce custom features by applying additional JavaScript code. Custom scripts can be then saved in a scripts.js file.

Introduced enhancements may include modifications like:

  • cookies consent

  • newsletter subscription and other pop-ups

  • external plugins for sharing feedback by customers.

Typically if a given modification goes beyond styling and settings available in the config.js file, it can be introduced with a custom script. You can either prepare your scripts in-house or use third-party scripts.

You can edit the code directly in Heretto CCMS by opening the the Source Editor.

For more information on preparing and uploading .js file, see Customize the Content Portal Behavior.

Customize Your Content Portal

You can modify the Heretto Deploy Portal look, feel, and behavior by uploading and using your own CSS and JSON files.

Prepare your sitemap for Heretto Deploy Portal customizations. See Prepare a Sitemap for Content Portal Customizations. Upload configuration, style, and script files into Heretto CCMS as needed.
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Heretto Deploy Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Heretto Deploy Portal instances are instantaneous.

If you want to edit your existing Heretto Deploy Portal customizations, see Edit the Existing Content Portal Customizations.

Upload Files to the Content Library

You can upload images, configuration files, and other allowed file types to the content library.

  • If you want to upload a large number of files, compress these files to a ZIP archive.
    Tip: Uploading files compressed to a single ZIP archive is quicker than uploading multiple files without compressing them first.

    By default, when you upload a ZIP archive to the content library, Heretto CCMS unzips the archive retaining its folder structure. If needed, you can also upload a ZIP archive to the content library without unzipping it.

    Uploaded files must be under 100MB in size.

  1. In the content library, navigate to the folder where you want to upload your files and click the Upload icon.
  2. Indicate the files that you want to upload:
    • Click to choose files and select the files.
    • Drag and drop the files from your folder into the Drag and drop files here area.
  3. If you selected any files that already exist in the content library folder and you don't want to overwrite them, clear the corresponding Overwrite files with the same names check box.
  4. If you selected any ZIP files that you do not want to be automatically unzipped, clear the corresponding Unzip check box.
  5. Click Upload Files.

Prepare a Sitemap for Content Portal Customizations

You prepare a sitemap for Heretto Deploy Portal customizations by adding a <sitemeta> element to the sitemap. You can find more information on sitemaps in Content Portal Layout and Navigation.

You have a sitemap created in Heretto CCMS and ready to be modified.

Tip:

You may want to have a development sitemap that has very simple structures that you use for testing content structures. Once you have the structures and configurations ready, we recommend then building your production-level sitemap.

There is a portal_configuration folder created within the __configuration folder in the content library that stores your config.json and {file_name}.css files for the portal configuration and styling.

  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. In the left pane, ensure that all map elements are shown:
    1. Click the cog icon.
    2. Under Show Elements, select All.
    All elements option
  3. Right-click the TITLE element and select Insert element after > sitemeta.
    Inserting sitemeta element

Edit the Existing Content Portal Customizations

You can edit the Heretto Deploy Portal configuration files directly in Heretto CCMS.

Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Heretto Deploy Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Heretto Deploy Portal instances are instantaneous.

  1. In your content library, navigate to the following folder __configuration/portal_configuration.
  2. Right-click the config.json, custom.css file, or script.js file and select Edit Source.
  3. Make changes to the file.
  4. Click Save.
Verify the configuration changes by opening your Heretto Deploy Portal in a web browser.
Tip: If you still cannot see your edits, try clearing your web browser cache.

If you use Mozilla Firefox, see How to clear the Firefox cache.

If you use Google Chrome™, see Clear cache & cookies.

Configuration Layers and Overrides

You can manage the configuration of multiple Heretto Deploy Portal environments from a single sitemap.

Maintaining Multiple Configuration Files

Maintaining multiple config.json files in a single sitemap enables you to easily manage your development, staging, and production Heretto Deploy Portal configurations.

The config.json files are included in your sitemap as environment specific <data> elements. Here is an example of a sitemap with three configuration files:

<data href="config.json" name="config-base" type="config"/>
<data href="config-stg.json" name="config-stg" rev="stg" type="config"/>
<data href="config-prod.json" name="config-prod" rev="prod" type="config"/>

The config.json specifies the base configuration and styling of your Heretto Deploy Portal.

The config-prod.json and config-stg.json files specify additional configurations for your production and staging environments. Heretto Deploy Portal combines the config.json and the config-stg.json values together to create the staging portal and combines the config.json and the config-prod.json together to create the production portal.

Important:

The @rev attribute value must be specified in the <data> element so the configuration files get correctly applied to the respective environments.

In other words, the base configuration file, config.json, and the development, staging, or production file work in conjunction with one another to create the total configuration for an environment.

For example, the config.json and config-dev.json together make the up the full configuration for the development environment. This configuration setup provides a nimble and powerful way to create environment-specific configurations to test and ultimately promote and deploy to production.

Layers and Overrides

Importantly, the configuration files may contain JSON objects and arrays. Objects in two or more configuration files are layered, or merged, into a single configuration object.

Arrays in two or more files, however, are overwritten when the files are combined into a full portal configuration, and the priority is given to the environment-specific configuration file. For example, in the following example we have a JSON array in the base config.json file:

"search": {
        "facets": [
            "Content_Type"
        ]
    },

If the config-stg.json file also includes an array for search facets, such as

"search": {
        "facets": [
            "Document_Category"
        ]
    },

the value from the config-stg.json will overwrite the value in the config.json and the staging portal environment will show the search facets corresponding to Document_Category.

Layering configuration files this way provides you a flexible way to test multiple configurations and managing all of them in a single sitemap.

Customize the Content Portal Settings

You can add a custom logo, footer, title, and more by overwriting the default Heretto Deploy Portal settings.

Prepare your sitemap for Heretto Deploy Portal customizations. See Prepare a Sitemap for Content Portal Customizations.
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Heretto Deploy Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Heretto Deploy Portal instances are instantaneous.

Prepare the configuration file.
  1. In the __configuration folder, create a folder called portal_configuration.
  2. Upload the config.json, scripts.js, or CSS file into the __configuration/portal_configuration folder in the content library.
    Important: Do not upload empty files into Heretto CCMS.
  3. Right-click on config.json file and click the Edit Source button to open the file in the Source Editor.
    For more information, see Content Portal Configuration Reference.
Add the configuration file to your sitemap.
  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. Drag and drop the config.json file onto the SITEMETA element.
    The config.json file is added as a DATA element.
    sitemeta element
  3. In the left pane, hover over config.json and click the edit properties icon.
    Figure 1. Edit Properties Icon
    Edit properties icon in the map editor
  4. In the pane that appears, in the name field, enter config
  5. If needed, clear the scope field by clicking the corresponding trash icon.
  • Verify the configuration changes by opening your Heretto Deploy Portal in a web browser.
    Tip: If you still cannot see your edits, try clearing your web browser cache.

    If you use Mozilla Firefox, see How to clear the Firefox cache.

    If you use Google Chrome™, see Clear cache & cookies.

Add Social Media Targets

Heretto CCMS lets you create visibility for your social media accounts and easily extend your reach there.

Configuring Social Media Buttons

The config.json files give you the ability to add social sharing links to your Content Portal so visitors can share pages to their social accounts.

The example below illustrates how to add your own social media links and icons to the site footer by using footer and links in the configuration. The same applies if you want to add social media links to your site’s header by using the header and links configuration.

The links list includes:

  1. Company website

  2. LinkedIn

  3. Facebook

  4. Twitter

  5. YouTube

  6. Reddit

"footer": {
        "links": [
            {
                "target": "_blank",
                "href": "https://www.MY_COMPANY_NAME.com/",
                "style": { flex: 1},
                "text": "www.MY_COMPANY_NAME.com"
            },
            {
                "className": "social-icons",
                "href": "https://www.linkedin.com/company/MY_COMPANY_NAME",
                "text": "i"
            },
            {
                "className": "social-icons",
                "href": "https://www.facebook.com/MY_COMPANY_NAME/",
                "text": "f"
            },
            {
                "className": "social-icons",
                "href": "https://twitter.com/MY_COMPANY_NAME",
                "text": "t"
            },
            {
                "className": "social-icons",
                "href": "https://www.youtube.com/channel/MY_COMPANY_NAME",
                "text": "y"
            }
        ]
    },
    "header":{
        "links": [
            //...same as above 
        ]
    } 

The configuration above results in share-links and icons such as:

Figure 2. Share Links

Customize the Content Portal Style

Overwriting the default Heretto Deploy Portal style enables you to customize its look and feel.

Tip:

The following procedure assumes that you will be updating and maintaining your CSS customizations directly in Heretto CCMS.

If you want to maintain your CSS code on a server external to Heretto CCMS, you can add the following code to the config.json file to call and apply the CSS.

"stylesheets": ["your-server-url/custom.css"]
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Heretto Deploy Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Heretto Deploy Portal instances are instantaneous.

Keep the following guidelines in mind when styling your Heretto Deploy Portal:

  • Avoid using negative values for margin and padding properties.
  • Avoid using percent values. Try using flex or flex-basis properties.
  • If you use percent values, the value should a base 8 root percent.

    For example, you can use: 100%, 50%, 25%, 6.25%, 3.125%.

  • Use flex for general layout properties.
  • Use grid for specific use cases like lists and items that need to be fixed to a certain number.
Prepare the configuration file.
  1. Upload the config.json, scripts.js, or CSS file into the __configuration/portal_configuration folder in the content library.
    Important: Do not upload empty files into Heretto CCMS.
  2. Add custom CSS for styling your Heretto Deploy Portal.
    While developing the custom.css file, you'll need to get CSS selectors. For more information, see Get CSS Selectors for Portal Styling.
Add the configuration file to your sitemap.
  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. Drag and drop the custom.css file onto the SITEMETA element.
    The custom.css file is added as a DATA element.
    sitemeta element
  3. In the left pane, hover over custom.css and click the edit properties icon.
  4. In the pane that appears, in the name field, enter stylesheets
  5. If needed, clear the scope field by clicking the corresponding trash icon.
  • Verify the configuration changes by opening your Heretto Deploy Portal in a web browser.
    Tip: If you still cannot see your edits, try clearing your web browser cache.

    If you use Mozilla Firefox, see How to clear the Firefox cache.

    If you use Google Chrome™, see Clear cache & cookies.

Get CSS Selectors for Portal Styling

The DITA elements are rendered as HTML elements with classes that you can use to define CSS selectors.

In Google Chrome™ or Mozilla Firefox, access the Heretto Deploy Portal instance that you want to style.
  • To inspect a particular element, right-click the rendered DITA element and do one of the following:
    • For Google Chrome™, select Inspect.
    • For Mozilla Firefox, select Inspect Element.
    Figure 3. Rendered Note Element.
    The following example (from Google Chrome™ and Mozilla Firefox respectively) shows that:
    • The note DITA element is rendered as a div HTML element with the note and note_note classes
    • You can use the .note CSS selector to style all note DITA elements

    CSS element with classes example

    Inspect tool example
  • To quickly inspect different elements, do one of the following:
    • For macOS, press Cmd > Shift > C and hover over different elements.
    • For Windows, press Ctrl > Shift > C and hover over different elements.
    Figure 4. Live Inspection in Firefox
    Live inspection

Customize the Content Portal Behavior

To extend the default Heretto Deploy Portal behavior or add custom features, you can implement your own JavaScript code.

Prepare your sitemap for Heretto Deploy Portal customizations. See Prepare a Sitemap for Content Portal Customizations.
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Heretto Deploy Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Heretto Deploy Portal instances are instantaneous.

Prepare the configuration file.
  1. Upload the config.json, scripts.js, or CSS file into the __configuration/portal_configuration folder in the content library.
    Important: Do not upload empty files into Heretto CCMS.
  2. To open the file, right-click on scripts.js file and click the Edit Source button to open the file in the Source Editor.
Add the configuration file to your sitemap.
  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. Drag and drop the script.js file onto the <sitemeta> element.
    The script.js file is added as a <data> element.
    sitemeta element
  3. In the left pane, hover over script.js and click the gear icon.
  4. In the pane that appears, in the name field, enter scripts.
  5. If needed, clear the scope field by clicking the corresponding trash icon.
  • Verify the configuration changes by opening your Heretto Deploy Portal in a web browser.
    Tip: If you still cannot see your edits, try clearing your web browser cache.

    If you use Mozilla Firefox, see How to clear the Firefox cache.

    If you use Google Chrome™, see Clear cache & cookies.

Content Portal Layout and Navigation

Sitemaps and their elements define and enforce content structures, layout, and navigation for your Heretto Deploy Portal.

Basic Site Section

Basic site sections contain content in a single version of your documentation.

Basic site sections are useful if you publish simple content or if you want to publish multiple maps on the same navigational level.

Basic Site Section with a Map

The following example shows the site output results of a sitemap with a basic site section that references a single DITA map. You can recreate the structure by opening the sitemap connected with your Heretto Deploy Portal and appending it with the elements provided in the example. To see how to edit elements listed in the topicmeta element, go to Create a DITAVal.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <!-- Tile title -->
            <navtitle>Basic Site Section</navtitle>
            <!-- Tile short description -->
            <shortdesc>Short Description</shortdesc>
            <!-- Tile icon -->
            <data href="media/portal_icon_blue.png" name="thumbnail"/>
        </topicmeta>
        <!-- Referenced DITA content -->
        <mapref href="content/map_a.ditamap"/>
    </sitesection>
</sitemap>
basic site section with a map

The result is a site section and its child topics that are listed one by one in the left pane menu. The link to the site section also appears in the top menu.

basic site section with a map - online output example

Basic Site Section with Nested Topics

This example shows the site output results of a basic site section that references a structure of nested DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <navtitle>Basic Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_a.dita">
            <topicref href="content/task_a.dita"/>
            <topicref href="content/reference_a.dita"/>
        </topicref>
        <topicref href="content/concept_b.dita">
            <topicref href="content/task_b.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topicref>
    </sitesection>
</sitemap>
basic side section with nested topics

The result is a site section and child topics that are listed one by one in the left pane menu and their hierarchy is properly reflected. The link to the site section also appears in the top menu.

basic site section with nested topics - online output example

Basic Site Section with Nested Topics and Chunking

This example shows the site output results of a basic site section that references a structure of nested DITA topics. The children topics are chunked to the parent topics. For more information on using the chunk attribute, refer to Chunk Attribute.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <navtitle>Basic Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_a.dita" chunk="to-content">
            <topicref href="content/task_a.dita"/>
            <topicref href="content/reference_a.dita"/>
        </topicref>
        <topicref href="content/concept_b.dita" chunk="to-content">
            <topicref href="content/task_b.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topicref>
    </sitesection>
</sitemap>
basic site section with nested topics and chunking

To apply an attribute-value pair to a parent topic, hover over the topic and click the gear icon to edit properties of the topicref element. In the properties window, you can set the chunk attribute to to-content.

The result is a site section and top-level topics that are listed one by one in the left pane. Contents of the child topics are displayed under their parents' URLs. Child topics are not listed in the navigational menu.

basic site section with nested topics and chunking - online output example

Site Section with Subsections

Site sections can contain up to five levels of nested subsections.

Tip: Site sections with subsections are useful if you publish complex content that may require additional levels of navigation.

Site Section with Subsections

The following example shows the site output results of a sitemap with a site section that contains two subsections. “Subsection A” references a DITA map and “Subsection B” references three DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection with subsections -->
    <sitesection>
        <topicmeta>
            <navtitle>Site Section with Subsections</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_yellow.png" name="thumbnail"/>
        </topicmeta>
        <!-- Subsection #1 -->
        <sitesection outputclass="view-tiles">
            <topicmeta>
                <navtitle>Subsection A</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_yellow.png" name="thumbnail"/>
            </topicmeta>
            <mapref href="content/map_b.ditamap"/>
        </sitesection>
        <!-- Subsection #2 -->
        <sitesection outputclass="view-tiles"> 
            <topicmeta>
                <navtitle>Subsection B</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_yellow.png" name="thumbnail"/>
            </topicmeta>
            <topicref href="content/concept_a.dita"/>
            <topicref href="content/concept_b.dita"/>
            <topicref href="content/concept_c.dita"/>
        </sitesection>
    </sitesection>
</sitemap>
site section with subsections
The result of this structure is a site section that is displayed in the left pane menu. When you click on the sitesection, you can see two clickable tiles that represent its subsections.
Note: To see how to edit contents displayed in a tile, go to Create a DITAVal.
site section with subsections - online output example

Site Section with Content and Subsections

This example shows a sitemap with a site section that references a DITA topic and contains two subsections. The first site section references a DITA topic. “Subsection A” references a DITA map and “Subsection B” references a DITA map and a DITA topic.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A basic sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <navtitle>Basic Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_a.dita"/>
        <!-- Sitesection tile #1 -->
        <sitesection>
            <topicmeta>
                <navtitle>Subsection A</navtitle>
            </topicmeta>
            <mapref href="content/map_a.ditamap"/>
        </sitesection>
        <!-- Sitesection tile #2 -->
        <sitesection>
            <topicmeta>
                <navtitle>Subsection B</navtitle>
            </topicmeta>
            <mapref href="content/map_b.ditamap"/>
        </sitesection>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_b.dita"/>
    </sitesection>
</sitemap>
site section with content and subsections
The result is a site section that is displayed in the left pane menu together with its child items: topics and site sections. While in case of topics you can see their content, subsections are represented with clickable tiles.
Note: To see how to edit contents displayed in a tile, go to Create a DITAVal.
site section with content and subsections - online output example

Site Section with Topicheads

Site sections (<sitesection> elements) can contain <topichead> elements.

Tip: <topichead> elements are useful for semi-complex content that may require some organization in the main table of contents.

They provide a non-linking title or heading.

Site Section with Content and Topicheads

This example shows the site output results of a sitemap with a <sitesection> element that contains a topic reference and two <topichead> elements. Each <topichead> element contains two DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <sitesection>
        <topicmeta>
            <navtitle>Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA Content -->
        <topicref href="content/concept_a.dita"/>
        <!-- Topichead #1 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead A</navtitle>
            </topicmeta>
            <topicref href="content/task_a.dita"/>
            <topicref href="content/task_b.dita"/>
        </topichead>
        <!-- Topichead #2 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead B</navtitle>
            </topicmeta>
            <topicref href="content/reference_a.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topichead>
    </sitesection>
</sitemap>
site section with topicheads
output of the site section with topicheads structure

The result is a site section that is displayed in the left pane menu with a hierarchy that reflects the sitemap structure. A link to the site section is also displayed in the top menu.

Note: Topicheads behave similarly to subsections - they group child topics under a common label. However, they are not accompanied with a tile. They only serve as an additional division within the navigation. When you click a topichead, you automatically open its first child topic.

Site Section with Topicheads Only

This example shows the site output results of a sitemap with a site section that contains two <topichead> elements. Each <topichead> element contains two DITA topics.

Note: In this case, the <sitesection> element behaves like a <topichead> element.

In other words, in the output, when you click the <sitesection> element, you are moved to the first element with content (“Task A”).

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <sitesection>
        <topicmeta>
            <navtitle>Site Section</navtitle>
        </topicmeta>
        <!-- Topichead #1 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead A</navtitle>
            </topicmeta>
            <topicref href="content/task_a.dita"/>
            <topicref href="content/task_b.dita"/>
        </topichead>
        <!-- Topichead #2 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead B</navtitle>
            </topicmeta>
            <topicref href="content/reference_a.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topichead>
    </sitesection>
</sitemap>
site section structure with topicheads only
output of the sitesection with topicheads only

Site Section with Versions

Versioned site sections can include multiple versions of the same content.

Tip: Site sections with versions are useful if you want to publish different releases of the same content.

You can reference resources from different Heretto CCMS branches. For more information about versioning in Heretto CCMS, see Create a DITAVal.

Basic Site Section with Versions

The following example shows the site output results of a sitemap with a <sitesection> that contains two version elements that reference two different versions of a map.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection with versioned content -->
    <sitesection outputclass="view-toc">
        <topicmeta>
            <navtitle>Versioned Site Section</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_navy.png" name="thumbnail"/>
        </topicmeta>
        <!-- Version #1 container -->
        <version>
            <!-- Version details -->
            <topicmeta>
                <!-- Version information that will be visible in the version drop-down menu -->
                <navtitle>v1.0</navtitle>
            </topicmeta>
            <!-- Referenced DITA content -->
            <mapref href="content/map_c_v1_0.ditamap"/>
        </version>
        <!-- Version #2 container -->
        <version>
            <topicmeta>
                <navtitle>v2.0</navtitle>
            </topicmeta>
            <mapref href="content/map_c_v2_0.ditamap"/>
        </version>
    </sitesection>
</sitemap>
basic site section with versions

The result is that articles within your versioned map will be accompanied with a dropdown that enables readers to choose between different versions.

Note:

To have the version dropdown show on desktop devices, be sure to add outputclass="view-toc" on the <sitesection> element that contains your versioned content.

Readers will be able to see a version number in the breadcrumbs section on the top of the screen.

output of a basic site section with versions

When you click the site section in the navigation menu, you will not be redirected to the first topic in a map as usual. Instead, you will be presented with a set of tiles. Each tile represents the top-level element in the versioned map. Tiles are accompanied with a dropdown for choosing between different versions.

output of a basic site sections with versions
Note:

The “v” phrase is added automatically before the version number. Therefore, you do not need to add it in the navtitle element of your versions.

Tip: You can version content on different sitemap levels. For more information, see Site Section with Subsections.

To learn how to add versioned maps to the sitemap, refer to Create a DITAVal.

Sitemap Elements Reference

Sample Sitemap Structure

The following example shows a sitemap that contains a:

  • Site section with a map
  • Site section with subsections
  • Site section with topicheads
  • Versioned site section
sitemap structure example

Sitemap Elements

<!-- Model sitemap -->
<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A basic sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <!-- Tile title -->
            <navtitle>Basic Site Section</navtitle>
            <!-- Tile short description -->
            <shortdesc>Short Description</shortdesc>
            <!-- Tile icon -->
            <data href="media/portal_icon_blue.png" name="thumbnail"/>
        </topicmeta>
        <!-- Referenced DITA content -->
        <mapref href="content/map_a.ditamap"/>
    </sitesection>
    <!-- A sitesection with subsections -->
    <sitesection>
        <topicmeta>
            <navtitle>Site Section with Subsections</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_yellow.png" name="thumbnail"/>
        </topicmeta>
        <!-- Subsection #1 -->
        <sitesection outputclass="view-tiles">
            <topicmeta>
                <navtitle>Subsection A</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_green.png" name="thumbnail"/>
            </topicmeta>
            <mapref href="content/map_b.ditamap"/>
        </sitesection>
        <!-- Subsection #2 -->
        <sitesection outputclass="view-tiles">
            <topicmeta>
                <navtitle>Subsection B</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_green.png" name="thumbnail"/>
            </topicmeta>
            <topicref href="content/concept_a.dita"/>
            <topicref href="content/concept_b.dita"/>
            <topicref href="content/concept_c.dita"/>
        </sitesection>
    </sitesection>
<!-- A sitesection with topicheads -->
    <sitesection>
            <topicmeta>
                <navtitle>Site Section</navtitle>
            </topicmeta>
            <!-- Topichead #1 -->
            <topichead>
                <topicmeta>
                    <navtitle>Topichead A</navtitle>
                </topicmeta>
                <topicref href="content/task_a.dita"/>
                <topicref href="content/task_b.dita"/>
            </topichead>
            <!-- Topichead #2 -->
            <topichead>
                <topicmeta>
                    <navtitle>Topichead B</navtitle>
                </topicmeta>
                <topicref href="content/reference_a.dita"/>
                <topicref href="content/reference_b.dita"/>
            </topichead>
    </sitesection>
    <!-- A sitesection with versioned content -->
    <sitesection>
        <topicmeta>
            <navtitle>Versioned Site Section</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_navy.png" name="thumbnail"/>
        </topicmeta>
        <!-- Version #1 container -->
        <version>
            <!-- Version details -->
            <topicmeta>
                <!-- Version information that will be visible in the version drop-down menu -->
                <navtitle>v1.0</navtitle>
            </topicmeta>
            <!-- Referenced DITA content -->
            <mapref href="content/map_c_v1_0.ditamap"/>
        </version>
        <!-- Version #2 container -->
        <version>
            <topicmeta>
                <navtitle>v2.0</navtitle>
            </topicmeta>
            <mapref href="content/map_c_v2_0.ditamap"/>
        </version>
    </sitesection>
</sitemap>
<sitemap> [required]
The root sitemap element.

Can contain the following elements:

  • <title>
  • <sitesection>
<title> [required]
The title of the sitemap.
<sitesection> [required]
By default a <sitesection> element is:
  • Rendered as a navigational tile
  • Present in the main table of contents

A container element for the following elements:

  • <topicmeta>
  • <version>
  • <mapref>
  • <topicref>
  • <topichead>
<topichead> [optional]
By default a <topichead> element is:
  • Not rendered as a navigational tile
  • Present only in the main table of contents

A container element for the following elements:

  • <mapref>
  • <topicref>
<topicmeta> [required]
A container element for the following elements:
  • <navtitle>
  • <shortdesc>
  • <data>
<navtitle> [required]
A site section, subsection, or topichead title.
<shortdesc> [optional]
A short description for site section or subsection rendered in a navigation tile.
Figure 5. Navigation Tiles.

The following example shows two navigation tiles: “Tile A” and “Tile B”.

navigation tiles example
<data> [optional]
An element that references an icon associated with a site section or subsection navigation tile.
<version> [optional]
An element that specifies the version of your content. Each version appears as a separate entry in the version drop-down list.

Can contain the following elements:

  • <topicmeta>
  • <mapref>
  • <topicref>
<mapref> or <topicref> [required]
An element that refers to either a DITA map or a DITA topic that contains the content that you want to publish to the site.
  • You can reference both regular DITA maps and sitemaps.
  • The referenced maps can contain <codeblock> elements.
  • You can nest <topicref> elements

Sitemap Attributes Reference

To modify the site layout, you can apply specific @outputclass attributes in the associated sitemap.

<sitesection> attributes and <topichead> attributes

Note: <sitesection> elements are specialized <topichead> elements.
@outputclass="view-tiles"

Default for <sitesection> elements.

  • Rendered as a navigation tile
  • Present in the main Table of Contents (TOC)
@outputclass="hidden"

Default for <topichead> elements.

  • Not rendered as a navigation tile
  • Present in the main TOC
@outputclass="view-toc"

Default for <sitesection> elements with multiple versions of content. If you add this to the <sitesection> element, the version dropdown selector will render in the portal.

Tip: The following element pairs render in the same way:
  • <sitesection outputclass="hidden"> and <topichead>
  • <sitesection> and <topichead outputclass="tile">

<topicref> attributes

@toc="no"
Hide a topic and its children from the main (left) TOC.
@chunk="to-content"
Chunk children topics to the parent topic. The parent topic displays as a single entry in the main (left) TOC.
@outputclass="full-content"

Default and exclusive for <topicref> elements.

  • Rendered in the central content area

Going Live

Once your development work is finished, it's time to take your Heretto Deploy Portal live.

Domain setup

To set up your domain, contact your Customer Success Manager to discuss the details and timelines. They will require the following information to set up your domain:

  1. The desired URL for your Heretto Deploy Portal.

  2. Confirmation that you have added the CNAME DNS record for the domain you want to use.
    Note: While setting up the DNS record, you need to refer to the default URL of your Heretto Deploy Portal provided by the your CSM. As you are the owner of the target domain, you can easily set this up on your end.

After receiving this information, the Heretto team can link your Heretto Deploy Portal instance to the desired domain and provide your website with a proper security certificate.

Overview

Heretto feature is an integral part of the Heretto Enterprise subscription. It enables you to easily publish from Heretto CCMS to your Heretto Deploy Portal. can be configured by anyone holding the Administrator role in Heretto CCMS.

Types of

There are two types of deployments: Active Sync and Manual Deploy.

Active Sync

Active Sync automatically publishes content updates to the Heretto Deploy Portal. Any change introduced in a topic or map will be immediately visible on your Heretto Deploy Portal environment. This deployment type is particularly useful if you have a staging instance and want to preview content that is still work-in-progress.

Manual Deploy

Manual Deploy requires the deployment to be triggered by a Heretto CCMS Administrator. That means your updates will not be reflected in the Heretto Deploy Portal until a deployment is triggered manually. Manual Deploy enables you to control when content updates are visible in the Heretto Deploy Portal instance. It's especially useful when you want to publish approved updates for a specific release to a production portal instance.

Known Limitations

  • You cannot deploy from a release. You can, however, branch a release and deploy from that branch.

  • Deployments do not warn about validation issues in your content. It does warn you about issues in the publish process.

  • There is no history of past publishes/deployments.

Configure

can be configured by Administrators in the Heretto CCMS.

If you want to create a deployment for a map on a specific branch, switch to that branch.

  1. In the Administration interface, go to .
  2. Click New Deployment.
  3. In the Create Deployment window, provide the following details:
    Create Deployment Window
    1. Provide the name of the deployment.
      Note: We recommend including the name of the branch and portal instance in the deployment name. For example, when your deployment is to publish content from the Verification branch to the staging portal instance, your deployment name could be Verification branch & Staging portal. This will ensure that anyone can understand how each deployment is configured.
    2. Decide which deployment type you want to set up. By default, deployments are set to Manual Deploy. If you want to configure an Active Sync deployment, select the Active Sync option.
    3. Click Add file and navigate to the map that you want to deploy.
      Remember:

      To deploy a map from a specific branch, switch to that branch before starting this step

  4. Click Save.
  5. Copy the ID Heretto generated for your deployment and pass it to your Customer Success Manager, along with the following information:
    • Share URL to the deployment map

    • The name of the branch with the deployment map

    • The Heretto Deploy Portal instance that the deployment map should be connected to

Once the Heretto team completes the configuration on their side, the configuration of the deployment is complete.

Publish Content with Heretto Deploy

You deliver content from your content library to a Heretto Deploy Portal instance by modifying an existing sitemap or creating a new sitemap.

Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Heretto Deploy Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Heretto Deploy Portal instances are instantaneous.

For more information about branching, see Branches.

For more information about the recommended sitemap structure, see Content Portal Layout and Navigation.

For more information on how to create and manage maps, see Create a DITAVal.

  • To update content on an existing Heretto Deploy Portal instance:
    1. Locate the sitemap associated with the Heretto Deploy Portal instance that you want to update.
      For more information, contact your Heretto CCMS administrator.
    2. To filter out specific content from the publication, see Filter Portal Content.
    3. Update the sitemap contents.
      Tip: You can merge content to quickly update a sitemap.
  • To prepare content for a new Heretto Deploy Portal instance:
    1. In the content library, create a sitemap.
    2. To filter out specific content from the publication, see Filter Portal Content.
    3. Associate the sitemap with a new Heretto Deploy Portal instance.
      Reach out to your Customer Success Manager.

Filter Portal Content

You can filter content on your Heretto Deploy Portal by adding a DITAVAL to the associated sitemap.

Tip: You can filter out your internal or in-progress content from your public Heretto Deploy Portal instance for every portal visitor.
  • Ensure that the content that you delivered or want to deliver to the Heretto Deploy Portal is profiled.

    For more information, see Profile Topic Elements and Profile Map Elements.

  • Locate the sitemap associated with your Heretto Deploy Portal.

    For more information, contact your Heretto CCMS administrator.

  1. Create a new DITAVAL or locate the existing DITAVAL that you want to filter the content on your portal with.
    For more information on how to create DITAVAL files, see Create a DITAVal.
  2. Associate the DITAVAL with the sitemap by doing the following:
    1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
    2. In the content library right-click the sitemap that you want to modify and select Dock.
    3. Navigate to the DITAVAL file.
    4. While holding the Shift keyboard key, drag and drop the DITAVAL file to the end of the sitemap.
      Inserting a DITAVAL file
    5. From the dialog, select Data and click Insert.
    6. In the left pane, right-click the DITAVAL and select Edit element attributes.
    7. In the Edit Properties window, in the name field, enter content-api-default-audience
    8. If needed, clear the scope field by clicking the corresponding trash icon.
    9. Click Save.

Profile Topic Elements

Use the Content Editor to conditionalize elements in a topic for conditional publishing.

The default conditional processing attributes are: audience, rev, platform, product, props, and otherprops.
  1. In the content library double-click a topic or a map.
  2. Place your cursor in the element you want to set a conditional processing attribute values on.
    Note: It is a best practice to profile grammatically independent elements, not just individual words or phrases. This is especially important when localizing the content, since at least a complete sentence is required to provide sufficient context for accurate translation memory and machine translation matching. This is true even if some text is duplicated across alternative elements for different conditions. When localizing content, it's always best to think of it grammatically first, then structurally.
  3. Click Attributes to open the Attributes tab.
  4. Navigate to the conditional processing attribute that you want to define, for example audience.
  5. Enter the values for each conditional processing attribute that defines the condition in which the element will be shown.
  6. Press the Enter keyboard key to apply attribute values.
Depending on the action defined for a specific value at publish time, content is either flagged, excluded, or included. If no action is specified for a specific value, the default is to include the content (unless your publishing profile sets the default to exclude).

Profile Map Elements

Use the Content Editor to set conditional processing attribute values and profile an entire topic (topicref element) or a submap (mapref element) for conditional publishing.

The default conditional processing attributes are: audience, rev, platform, product, props, and otherprops.
Note: When you apply a conditional processing attribute to a parent topic (topicref element), the same attribute applies to all children of that topic.
  1. In the content library, double-click a map.
  2. In the left pane, hover over the element you want to set the conditional processing attributes for and click the wrench icon.
  3. Enter the values for each conditional processing attribute that defines the condition in which the element will be displayed.
    If the topic is only intended for administrators, in the audience field enter administrator
    Tip: To add multiple values for conditional processing attributes, insert a space between each value.

Create a DITAVal

Create a DITAVAL containing include or exclude rules to filter content at publish or during editing.

  1. In the content library, navigate to a folder and click Create New.
  2. Select DITAVal to open the Create new window.
  3. Enter a name for the file.
  4. Optional: Create the file in a folder different from the current folder by clicking Change and selecting a new location.
  5. Optional: Assign the file to collections by clicking Collections and selecting collections from the list.
  6. Optional: Assign metadata to the file by filling in the Metadata fields.
  7. Click Create & Edit.
  8. Edit or remove the default property, or click Add Prop to add a new action.
You can use this DITAVAL to publish or filter your content as your edit or preview files in your content library. For more information, see Create a DITAVal or Filter Content with a DITAVAL.