Working with external files

External files are those that appear—in content or as a download link—in the generated (HTML) content, but which are not in the Heretto repository.

Warning: As of April 2022, there is a bug in Heretto and the Download option is not fully functional. Users can right-click on the link and download the file, but clicking the DOWNLOAD does not work. This procedure is subject to change with the new portal.

Link to external files on a Web server to make those files available for download. This method inserts a link labeled DOWNLOAD, so be sure to provide text before the link that explains to the reader what will happen when the link is clicked.

  1. Insert the cursor where you want the download link.
  2. Enter the text DOWNLOAD, in all-caps, and then select that text.
  3. Click Link and select Insert Xref.
  4. In the Scope field of the Properties pane, select external.
  5. in the Output Class field, enter download-link.

    Add 'download-link' to the Output class of the link

Embedding external text files

Any text file can be embedded in the page and presentes on the page with the browser's text viewer, including HTML, JSON, XML, and more. Just rename the file to have a .txt filename extension.

For structured text files, consider running the file through a formatting tool first, such as:
  • HTML — http://www.freeformatter.com/html-formatter.html
  • XML — http://www.freeformatter.com/xml-formatter.html
  • JSON — https://jsonformatter.curiousconcept.com/

To embed a text file:

  1. If the source file you want to embed is not a .txt file, change the file extension to .txt.
  2. Add the .txt file to the /files folder of the documentation web server (through Cyberduck).
  3. In your .dita file, add an object element to reference the file you want to embed. For the object:
    • Set the URL to the text file.
    • Set the Type attribute to: text/plain.
    Note: In Heretto, the object is always presented as if it is a "video" element. See below for examples.

The following example shows a generated HTML page:

Example HTML page

The file for the embedded HTML above is in the /files/email-templates folder of the web server:

The files/email-templates folder in the documentation web server

In the .dita file, the reference is an object element with the Type attribute set to text/plain:

Type attribute in a dita file

Actual example of an embedded text file:

The default height is 300px. You can override it if needed with the Height attribute.