Embed Code from an External Source

You can set your help content to use the latest code samples from a repository, such as GitHub or BitBucket. Once set up, your HTML5 help will be able to update code samples automatically, without being republished.

Note

The code samples need to be in an "https" URL.

Note

For embedding Swagger/Open API code, see Embed Swagger Content for HTML5 Help Centers.

To set up your HTML5 help to use "live" code snippets from a repository, use dynamic code snippets.

  1. Select Layout and then edit the HTML5 layout you are going to use for publishing. Alternatively, you can create a new HTML5 layout and edit that.

  2. Edit the HTML5 layout and select the Classes and attributes category. Enable the Output role attribute as class names setting and save the layout.

  3. Create or edit a topic that you want to contain code from an external source.

  4. Select the position where you want the code to appear and then:

    1. Press Alt and Enter (Windows) or Command and Enter (Mac) to access the Element list.

    2. Add a code block element, either programlisting or screen.

  5. Select the programlisting or screen element in the topic.

    Tip

    You can add a programlisting element with these attributes added by the shortcut Alt,. Then you just need to add the URL value.

  6. In the Element attributes section, add these attributes and values:

    • A role attribute with the value embedcode

    • An xlink:href attribute with the URL to the code snippet in your repository.

  7. Optional: If you want or need fallback code for other output formats, add the code snippet in the programlisting or screen element as well.

When you publish, your code will be fetched from the repository and will be automatically updated if that code changes.

Note

If you also publish to other outputs such as PDF, the embedded code will still be fetched dynamically at publish time. But if you change the code samples in your repository, you will need to republish the PDF output to have Paligo fetch the latest changes.