Remote Content

The are various ways to include remote content, for content published as part of tutorials of redhat-scholars we will follow three strategies:

  • Include Raw Content

  • Stub and Include

  • Include Content Seperate site a.k.a Multi Site

Strategies

Including Remote Content

Any remote AsciiDoc content could included using the include macro and using the http urls of the remote content.

Say you want to include instructions to clone a source repository and then set the $TUTORIAL_HOME to cloned folder then do :

:tutorial-url: https://github.com/redhat-developer-demos/rhd-tutorial-common.git
:folder: my_folder
include::https://raw.githubusercontent.com/redhat-developer-demos/rhd-tutorial-common/master/download-sources.adoc[]

The included content will included in your includer document as shown:

Before we start setting up the environment, let’s clone the tutorial sources and set the TUTORIAL_HOME environment variable to point to the root directory of the tutorial:

git clone https://github.com/redhat-developer-demos/rhd-tutorial-common.git my_folder
export TUTORIAL_HOME="$(pwd)/my_folder"
cd $TUTORIAL_HOME

Where to use this strategy:

  • Content is located in remote repositories

  • When its enough just to include a content without navigation

  • The included content does not have any links to related component/module content

Stub and Include

The strategy is called "Stub and Include", where publishing site will create stubs for the remote content to be included.

E.g. Assume that you want to include the _tasks.adoc from another content component Tekton Tutorial, then you do the following:

  • In the courseware(component) where you want to include the content, create a stub named stub_tasks.adoc with the following content:

stub_tasks.adoc
= Tasks (1)
\include::_attributes.adoc[] (2)
:chapter-namespace: stub-project (3)
\include::master@tekton-tutorial:ROOT:partial$_tasks.adoc[] (4)
1 The title for the current content
2 The attribute doc to include
3 The page level attributes that is used in _tasks.adoc
4 The include of the external remote content version@component-name:module:partial$<doc_file> via partials.

  • You can then add the navigation to stub.doc in the current component navigation like :

 
* xref:stub_tasks.adoc[Tasks]

That should render remote included content within same UI context of the current site.

You can view the example of this strategy.

  • Always use partials for the included content, to avoid UI context switch

  • All the varibles used in includes partials, need to be overridden in the stub to avoid using the values from includes context

  • Make sure the include component repository is part of the current site playbook content  sources

When to use this strategy:

  • Content is located in remote component repositories

  • Add a navigatable link to included remote component/module content

  • The navigation to included remote content should not leave/replace the current site navigation

Multi Site

Some cases you might need to deliver a workshop covering two tutorials e.g. Demo Tutorial and Tekton Tutorial. In those cases just including remote content in the current component site is sufficient.

Add the navigation to stub.doc in the current component navigation like :

** xref:master@tekton-tutorial:ROOT:tasks.adoc#tekton-task-build-sources[Build Cloud Native Application(Full Site)]

That should render remote included content within same UI context of the current site.

You can view the example of this strategy.

  • Make sure the include component repository is part of the current site playbook content  sources^

When to use this strategy:

  • Content is located in remote component repositories

  • Add a navigatable link to included remote component/module content

  • It is OK to switch other tutorial navigation context