Summary
Docaroo allows importing content at build time to your documents. External content is important because it allows you to create resusable parts of content and import these parts in multiple places in your documents. It is possible to import content from external public and private Github repositories but you must be sure that the content you want to import is available at the time when you build your site, as the imported content is added at build time.
It is also possible to import content at run time, but be aware this type of content may be not indexed for search (when using Algolia, capturing the client rendered content depends on the behaviour of the crawler and on the response time of the site; when using native search, it is not indexed at all). This content will be refelcted in the page ToC, you can tag (with cutom tags) or classify (custom categories) based. on this content and you can also add comments to your docs based on this content, but this content will not be returned by site search features (regardless if you use native searcing or Algolia search). We recommend to use this type of content for short pieces of content that are not very relevant to the core subject of the documentation (such as some news or announcements).
This type of content can be imported from any source that returns markdown and follows the same logic of selecting the content between start and end markers. This type of content can be imported only from public sources as we currently do not support custom authentication on client side. It is also important to be aware of the API limitations of the source and to not abuse of the usage of run time imported content since this content is loaded each time when the page containing it is loaded (for example, Github has some limits related to raw content reading API). Currently we do not support run time content caching yet.
Import site content
Import content from another file from your site, between start and end markers. Markers can be set by you (in which case it must be in the from of HTML comments to not affect the rendering of the source file), or can be any placeholders (existing text) of the source file. The path to the source file should be given as relative path from the root documents directory.
Always check if the markers are present in the source file!!!
{%
ExternalSiteContent {
"markdown": true,
"file_path":"partials/external-content-demo/ec1.md",
"ignore_wp_shortcodes": true,
"start_marker": "<!-- START MARKER 1 -->",
"include_start_marker": false,
"end_marker": "<!-- END MARKER 1 -->",
"include_end_marker": false,
"needAuth": false
}
%}
IMPORTED CONTENT
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sagittis dolor nec porttitor feugiat. Fusce interdum, lacus eget tincidunt porta, mi nibh auctor velit, non dapibus dolor velit et leo.Mauris semper nisi in elementum finibus.
END IMPORTED CONTENT
If you want to import the full source file, use the reserved fullFile marker.
{%
ExternalSiteContent {
"markdown": true,
"file_path":"partials/external-content-demo/ec2.md",
"ignore_wp_shortcodes": true,
"start_marker": "fullFile",
"include_start_marker": false,
"end_marker": "fullFile",
"include_end_marker": false,
"needAuth": false
}
%}
IMPORTED CONTENT
Maecenas consequat elit at sollicitudin euismod. Proin scelerisque urna ut ullamcorper bibendum. Proin tristique, neque a accumsan consequat, sapien leo ultricies elit, eget congue neque massa sit amet sapien. Cras finibus elit metus, semper faucibus urna viverra sit amet. Aenean ornare pellentesque nulla, vitae interdum tellus pulvinar sed. Aenean vulputate id est nec semper. Aenean feugiat, justo ut lacinia feugiat, leo libero tincidunt nibh, ultrices auctor quam dui eget diam. Morbi porta nulla in iaculis hendrerit. Aenean eu convallis nibh. Integer sed interdum lorem. Maecenas tristique, turpis non malesuada facilisis, magna purus mollis justo, ultricies fringilla sapien quam at nisl.
END IMPORTED CONTENT
Import multiple site content
You can import multiple parts from a source file from you documentation. Each part should be found bewteen a start and end markers. Parts can overlap.
{%
ExternalSiteContentMM {
"needAuth": false,
"markdown": true,
"file_path":"intro.md",
"ignore_wp_shortcodes": true,
"markers": [
{
"start_marker": "Welcome",
"include_start_marker": true,
"end_marker": "organization.",
"include_end_marker": true
},
{
"start_marker": "Use",
"include_start_marker": true,
"end_marker": "Each",
"include_end_marker": false
}
]
}
%}
IMPORTED CONTENT
Welcome to the Documentation Site Builder Guide — your comprehensive resource for learning how to create, build, and maintain high-quality documentation sites for any kind of project, product, or organization.Use the sidebar to navigate to the first section and begin your journey.
END IMPORTED CONTENT
Import external repo content
You can import into your documents content from external Github repositories. These repositories can be public ("needAuth": false) or private ("needAuth": true). Any number of public repositories can be used to import content. For private repositories, the number of repositories that can be used to import content to your documents depends on the access key that is configured. The access key and user (organisation) should be confiured in .env for development environment (JEKYLL_ACCESS_TOKEN and JEKYLL_GIT_USER) and as Github action secret (same names) for production environment.
The private repositories must belong to a single Github user or organisation
Currently we support only GitHub repositories
{%
ExternalRepoContent {
"markdown": true,
"owner":"PMCDevOnlineServices",
"repo":"Ihs-docs",
"branch":"main",
"file_path":"Support-Center/eng/use-support-center.md",
"ignore_wp_shortcodes": true,
"start_marker": "# Innohub Support Center",
"include_start_marker": true,
"end_marker": "services." ,
"include_end_marker": true,
"needAuth": true
}
%}
IMPORTED CONTENT
Innohub Support Center
Innohub Support Center is the single point of contact for notifying us about the issues that you experience when using our services.
END IMPORTED CONTENT
Import multiple external repo content
Exactly as for the content from other files from your documentation, you can import multiple parts of content from external Github repositories
{%
ExternalRepoContentMM {
"needAuth": true,
"markdown": true,
"owner":"PMCDevOnlineServices",
"repo":"Ihs-docs",
"branch":"main",
"file_path":"Register-to-innohub/eng/register-to-innohub.md",
"ignore_wp_shortcodes": true,
"markers": [
{
"start_marker": "# Registration to innohub",
"include_start_marker": true,
"end_marker": "Be aware that the registration will not give you",
"include_end_marker": false
},
{
"start_marker": "by providing your email address and a password.",
"include_start_marker": false,
"end_marker": "Be aware that, if you are already logged in",
"include_end_marker": false
}
]
}
%}
IMPORTED CONTENT
Registration to innohub
Registration to innohub will grant you with access to the protected content and to innohub services. In order for this to happen, we only need your email, we don’t require any other personal information. We will use your email only for the login process and not for other purposes. However, before registration we strongly encourage you to read our privacy policy. Later on, if you enjoy innohub and you would like to access additional services, we may ask you to provide the information that we need in order to allow you to benefit of our services.
How to register
Registration is very simple. From the main menu, select myInnohub and you will easily find the Register option. This will direct you to the registration page where you can input the email address and password. You will receive an email for confirmation. Follow the link provided by the confirmation email and that’s all.
END IMPORTED CONTENT
Import code from external repo
Importing code from external repositories is exactly as importing any other content (as earlier explained). The only addition is that you need to wrap the import in markdown code block ticks.
<code block ticks>
{%
ExternalRepoContent {
"markdown": true,
"owner":"florinhoinarescu",
"repo":"IHS-Master",
"branch":"master",
"file_path":"app/ihs-main-app/src/loader/app-loader.js",
"ignore_wp_shortcodes": true,
"start_marker": "fullFile",
"include_start_marker": false,
"end_marker": "fullFile" ,
"include_end_marker": false,
"needAuth": true
}
%}
<code block ticks>
IMPORTED CONTENT
import MyReducers from '../helpers/MyReducers';
import { ReactComponentLoader } from '../helpers/utilities';
import MultipleLoader from '../helpers/MultipleLoader';
const _listener = (e) => {
let who = e.detail.who;
if (who === process.env.REACT_APP_APP_NAME) {
const IHSBEStore = e.detail.content;
const IHSUtilities = e.detail.utilities;
if (IHSBEStore) {
IHSUtilities.broadcastMessage(1, process.env.REACT_APP_APP_NAME); //got the store and connected to it
// INJECT OWN ASYNC REDUCERS
// own reducers can be nested or not-nested based on the nested parameter of MyReducer class (6th parameter)
// nesting will be made automatically in ihs-be-store and will impact the state structure only
// actions will be passed to connected components in the same way as for not-nested reducers
// persistence cannot be individually controlled in the case of nested reducers
// the persistence of the root reducer will be applied for all sub-reducers (this the 7th parameter of MyReducers class)
new MyReducers(
true,
IHSBEStore,
IHSUtilities.reducerInformation,
IHSBEStore.injectAsyncReducer,
IHSUtilities.broadcastMessage,
process.env.REACT_APP_NESTED_REDUCERS,
process.env.REACT_APP_NESTED_ROOT_REDUCER_PERSISTENCE
);
const components = new MultipleLoader('components').output;
Object.keys(components).forEach((component) => { ReactComponentLoader(components, IHSBEStore, IHSUtilities); });
document.removeEventListener(process.env.REACT_APP_LISTEN_TO_GET_STORE, _listener);
}
else
IHSUtilities.broadcastMessage(3, process.env.REACT_APP_APP_NAME); //cannot connect to the store
}
}
export default _listener;
END IMPORTED CONTENT
Import content at run time
Import content at run time like shown below. Use with care and check if there are potential limitations of the source APIs for reading files.
{% include elements/run-time-content.html
source="https://raw.githubusercontent.com/pmc-community/business-booster/main/LICENSE"
startMarker="fullFile"
endMarker="The above"
caller=page.url
header="**This is a custom `header` for the run time imported content**\n"
%}
RUN-TIME IMPORTED CONTENT
END RUN-TIME IMPORTED CONTENT
On this page