home

Heretto CCMS

Heretto CCMSHeretto Deploy APIHeretto PortalRelease Notes
Heretto CCMSHeretto Deploy APIHeretto PortalRelease Notes

Gretyl's Portal

Heretto Help

Show Contents

Show Page Sections

thumbnailHeretto CCMS

Publish

Heretto Connector for Docusaurus

Heretto CCMS enables you to deliver content from the content library to a Docusaurus-built site hosted on Netlify or to generate a static Docusaurus site that you can preview locally and deploy on your own.

Note: The Heretto Connector for Docusaurus may be disabled on your Heretto CCMS instance. If you want to enable this feature, contact your Customer Success Manager.
Figure 1. Default Docusaurus Static Site
Default Docusaurus site example

Docusaurus Publishing Scenarios Management

You can add, edit, remove, enable, and disable the Docusaurus publishing scenarios.

Tip: You can also locally develop Docusaurus templates and associate them with Docusaurus publishing scenarios.

Create a Docusaurus Scenario

Administrators can create Docusaurus publishing scenarios.

  1. In the Dashboard, click Docusaurus.
  2. Click New scenario.
  3. In the New scenario window, fill in the Scenario name field.
  4. If you want to be able to deploy Docusaurus output to Netlify:
    1. If needed, configure the deployment environment for Docusaurus. See Configure Publishing Microservices for Docusaurus.
    2. From the Environment drop-down list, select a Netlify deployment environment.
    3. Select the Enable deployment to Netlify check box.
  5. Manage the Docusaurus templates:
    1. To add a new template, click Add new template and fill in the Template name and Name or Git URL fields.
      Template name field
      The name that will display in the Template drop-down list in the Publish window.
      Name or Git URL field
      One of the following:
    2. To remove a template, click the associated X button.
  6. Click Create.

Configure Publishing Microservices for Docusaurus

Administrators can define environments for publishing microservices.

  1. In the Dashboard, click Publishing Configuration.
  2. To create a new environment:
    1. In the docusaurus settings, click Add new environment.
    2. In the Create Environment window, fill in the Environment Name field.
    3. Click Create.
    4. On the Publishing Configuration page, fill in the Netlify API Token field (0Auth) of the environment that you created in 2.
      Tip: For more information, see the Netlify Documentation.
  3. To remove an environment, next to the environment, click remove.
  4. To modify an environment, edit the associated fields.
  5. Scroll down and click Save Changes.

Enable or Disable a Docusaurus Scenario

Administrators can show or hide a publishing scenario in the publishing interface.

  1. In the Dashboard, click Docusaurus.
  2. Hover-over a publishing scenario and click .
  3. From the context menu, select an action:
    • To disable a publishing scenario, select Disable.

      Disabled publishing scenarios are not visible in the publishing interface.

    • To enable a disabled publishing scenario, select Enable.

      Enabled publishing scenarios are visible in the publishing interface.

Delete a Docusaurus Scenario

Administrators can delete publishing scenarios that are no longer needed.

  1. In the Dashboard, click Docusaurus.
  2. Hover-over a publishing scenario and click .
  3. From the context menu, select Delete.
  4. If prompted, confirm the deletion.

Publish Content with Docusaurus

You can deliver content from the content library to a Docusaurus-built site hosted on Netlify or to generate a static Docusaurus site that you can preview locally and deploy on your own.

Netlify is an easy to use hosting service. For more information, see https://www.netlify.com/.

To learn how Docusaurus renders DITA maps, refer to Docusaurus Map Reference.
  1. In the content library, click on a map, and in the right pane select Output and click Publish.
  2. From the list on the left, select a Docusaurus publishing scenario.
    The publishing scenarios are configured by your CCMS administrator. For more information, see Docusaurus Publishing Scenarios Management.
  3. Optional: In the Enter Description field, enter a meaningful description.
    Once you publish the document, this description appears in the list of finished publishing jobs.
  4. To include Netlify deployment as part of the publish:
    Note: Depending on the scenario configuration, the following options may not be available.
    1. Select the Deploy to Netlify check box.
    2. From the Available sites drop-down menu, select the Netlify site that you want to deploy the content to.
      Important: If you don't select any item from the drop-down menu, the content will be deployed to the previously deployed site or in the event of lack of sites, a new site will be created.

      You can select the Show sites for other maps check box to show the Netlify sites that the map and other maps have already been deployed to.

  5. Set the publishing parameters.
    The publishing scenario can include the following parameters.
    Template
    Enables you to select output style.
    Ditaval (or args.filter)
    Enables you to select a DITAVAL file for conditional publishing.
    Locales
    Enables you to select a locale when publishing localized content.
    Webhooks
    Enables you to send webhooks on successful publish or any publish.
  6. Click Publish.
    The resource publishes. It may take a moment to complete.
Figure 2. Publish Window
Publish window example

In the Key Assets Section, the following links are provided:

full_project.zip
Useful if you want to develop your own Docusaurus template.
build.zip
Useful if you want to preview the Docusaurus static site locally or deploy the site on your own.
netlify.app
Useful if you deployed the Docusaurus static site to Netlify and you want to preview it.
Warning: If you change the site name on Netlify, the link to the site in the Publish Window will not update. This will lead to sites in affected publish records showcasing an error message rather than your Netlify site.
Change site name screenshot

If you deployed content to Netlify as part of the publish:

  • For a map that was not deployed to Netlify yet, a new site is created.
  • For a map that was already deployed to Netlify, the site is updated.

Locally Preview a Docusaurus Static Site

You can host the Docusaurus output on a local web server to preview it.

  1. Download the build.zip key asset.
  2. Unzip the downloaded archive.
  3. Navigate to the unzipped folder and unzip the build.zip file.
  4. In the terminal, navigate to the unzipped build folder by entering cd publish_filepath
    Where, publish_filepath is the path to the build folder.
    Enter:
    • cd C:\users\your_username\Downloads\publish_name\build (Windows)
    • cd /Users/your_username/Downloads/publish_name/build (macOS)
    Where:
    • your_username is the name of the account that you are currently logged on your workstation
    • publish_name is the name of the folder that contains the published static site
  5. Start a local web server by entering npx serve
       │   Serving!                                       │
   │                                                  │
   │   - Local:                                       │
   │                   http://localhost:5000               │
   │                                                  │
   │   - On Your Network:  http://192.168.56.1:5000   │
   │                                                  │
   │   Copied local address to clipboard!             │
  6. In a web browser, go to the Local address.
    Go to http://localhost:5000
To stop the local web server, in the terminal, press Ctrl > C.

Manually Deploy a Docusaurus Site

You can manually deploy a static site to Netlify or a similar static site hosting provider.

Publish a static site by using a Docusaurus scenario. See Publish Content with Docusaurus.
This procedure assumes that your hosting provider is Netlify.
  1. Download the build.zip key asset.
  2. Unzip the downloaded archive.
  3. In your web browser, go to https://app.netlify.com/.
  4. On Netlify, in the designated area in the Sites tab, drag and drop the build folder from the unzipped archive.
    Netlify Sites tab folder upload screenshot

    Depending on the size of your static site, it can take a few minutes for Netlify to process the files and build the site.

Once the site built, you are able to see it as well as make any administrative changes you need. For more information, see https://docs.netlify.com/.

Docusaurus Map Reference

You can use a regular DITA map to publish content with Docusaurus.

Note: Docusaurus only supports the standard DITA maps. Other DITA map types like bookmaps, learning maps, sitemaps, or specialized maps are not supported.

Map Structure

<map id="ditamap-465" title="Map A">
    <topicref href="t1.dita">
        <topicref href="t2.dita">
            <topicref href="t3.dita"/>
        </topicref>
    </topicref>
    <topichead navtitle="Topic Head A">
        <topicref href="t4.dita"/>
        <topichead navtitle="Topic Head B">
            <topicref href="t5.dita"/>
            <topicref href="t6.dita"/>
        </topichead>
    </topichead>
    <mapref format="ditamap" href="sm1.ditamap"><data href="t7.dita" name="" scope="local" value=""/></mapref>
</map>
sample map structure newUI

Sample Output

Sample output screenshot
  • Each topic that is a direct child of the publication map (see “Topic A”) is added to the left Table of Contents (TOC).
  • Each topic nested under a topic that is a direct child of the publication map is chunked (“Topic C” and “Topic B” are chunked to “Topic A”). In other words, every child of a topic reference element is chunked.
  • Each topic nested directly under a topic that is a direct child of the publication is added to the right TOC.
  • Each topic head element is rendered as an expandable item in the left TOC.
    Important: You can nest a topic head element under a topic head element (“Topic Head B” is nested under “Topic Head A”). You cannot nest a topic head element under a topic reference element.
  • Submaps do not impact the TOC structure (see “Submap A” and “Topic G”).

Last updated: October 3, 2023

Footer Section

Our Support Team is here to help

Submit a support request or check the status of your existing requests. You can also email us.

Contact Support Team

Love this help site?

You can have one, too! Sitting on top of the Heretto CCMS, our team can build a tailored portal that will delight your customers. Meet with our team to learn more.

Connect with us

Explore

Integrations

Video Tutorials

Learning DITA

Company

About Us

Contact Us

heretto.com

Legalities

Legal

Privacy Policy

Terms of Use

© 2023 Heretto Intellectual Property. All rights reserved.

Legal

Privacy Policy

Terms of Use

About Us