Raw code library items can load their content from an external XML file when the documentation is generated. This makes it possible to maintain the raw content outside the HelpNDoc project, reuse the same content in multiple projects, or update generated output without editing the library item itself.

An external raw code file can define different content for each output family:

  • HTML content for HTML-based documentation formats, including CHM, HTML, ePub, Kindle, and Qt Help
  • Markdown content for Markdown documentation
  • Text content for other documentation formats, including Word and PDF

XML file structure

The external file must be a valid XML document using the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<RawCodeContent>
  <HTML><![CDATA[
<p>Sample external <strong>HTML</strong> raw code.</p>
<p>This content is exported as-is to HTML-based documentation formats.</p>
  ]]></HTML>
  <Markdown><![CDATA[
Sample external **Markdown** raw code.
```mermaid
flowchart TD
  A[Start] --> B[Generate documentation]
  B --> C[Export Markdown content as-is]
  ]]></Markdown>
  <Text><![CDATA[
Sample external textual raw code.
This content is exported as-is to documentation formats that do not use HTML or Markdown, such as Word and PDF.
  ]]></Text

</RawCodeContent>


Root element

The root element must be: <RawCodeContent>
It contains the format-specific content blocks used by HelpNDoc during generation.

Content elements

HTML

The <HTML> element contains the raw HTML content to export to HTML-based documentation formats.
This content can include HTML markup, CSS, JavaScript, widgets, iframes, or other custom code supported by the target output format.

Example:

<HTML><![CDATA[
<div class="custom-note">
  <strong>Important:</strong> This note is inserted as raw HTML.
</div>
]]></HTML>

The HTML content is exported as-is to CHM, HTML, ePub, Kindle, and Qt Help outputs.

Markdown

The <Markdown> element contains the raw Markdown content to export when generating Markdown documentation.
This content can include Markdown formatting, tables, code blocks, Mermaid diagrams, or any Markdown syntax supported by the target Markdown processor.

Example:

<Markdown><![CDATA[
## Build process

```mermaid
flowchart LR
  A[Write content] --> B[Generate Markdown]
  B --> C[Publish]
```
]]></Markdown>


The Markdown content is exported as-is to Markdown output.

Text

The <Text> element contains the plain text content to export to other documentation formats.
This content is useful for Word and PDF outputs, where HTML or Markdown code should not be inserted directly.

Example:

<Text><![CDATA[
This information is inserted as plain text in Word and PDF documentation.
]]></Text>


The text content is exported as-is to formats such as Word and PDF.

Using CDATA sections

It is recommended to wrap each content block in a CDATA section:

<![CDATA[
Your raw content here
]]>


CDATA sections allow the content to include characters that would otherwise need to be escaped in XML, such as <, >, &, Markdown code fences, HTML tags, CSS rules, or JavaScript code.

Optional content blocks

The <HTML>, <Markdown>, and <Text> elements can be left empty if no content is needed for a specific output family. However, including all three elements is recommended so that the external file clearly defines the content to use for each supported format.

Example with an empty Markdown block:

<?xml version="1.0" encoding="UTF-8"?>
<RawCodeContent>
  <HTML><![CDATA[
<p>This is exported to HTML-based formats.</p>
  ]]></HTML>

  <Markdown></Markdown>

  <Text><![CDATA[
This is exported to Word and PDF.
  ]]></Text>
</RawCodeContent>

Complete example

<?xml version="1.0" encoding="UTF-8"?>
<RawCodeContent>
  <HTML><![CDATA[
<div class="warning-box">
  <strong>Warning:</strong> This custom HTML block is inserted directly into HTML-based documentation.
</div>

<script>
  console.log("Custom HelpNDoc raw code");
</script>
  ]]></HTML>

  <Markdown><![CDATA[
> **Warning:** This Markdown block is inserted directly into Markdown documentation.

```mermaid
flowchart TD
  A[Raw code item] --> B{Output format}
  B --> C[HTML-based output]
  B --> D[Markdown output]
  B --> E[Text-based output]
```
  ]]></Markdown>

  <Text><![CDATA[
Warning: This plain text block is inserted directly into text-based documentation formats such as Word and PDF.
  ]]></Text>
</RawCodeContent>

Notes and recommendations

The content of each block is inserted without conversion. Make sure that the HTML, Markdown, or text you provide is valid for the documentation format where it will be used.

When inserting HTML, CSS, or JavaScript, test the generated documentation in each target viewer or reader, as support can vary between CHM viewers, web browsers, ePub readers, Kindle readers, and Qt Help viewers.

When inserting Markdown, make sure that any advanced syntax, such as Mermaid diagrams, is supported by the tool or platform that will render the generated Markdown output.