Skip to main content
Version: 7.9.x

Docusaurus

Docusaurus is a performant static site generator and can be used to create common content-driven websites extremely quickly.

In the dev portal, Docusaurus is used to create the documentation writing just markdown files.

Integration into micro-lc

As Docusaurus hide its root component, we first need an adapter that expose the micro-lc's required lifecycle methods: its purpose is to correctly include Docusaurus inside micro-lc.

Docusaurus adapter

The adapter come as micro-lc plugin, whose configuration structure can be found in the dedicated section.

Adapter configuration

In addition to the standard qiankun plugin configuration you must include the following props:

  • docusaurusUrl: the complete url where docusaurus will be exposed, it is generally composed by the host and the exposed endpoint.

Here follows a full configuration example:

{
"id": "docusaurus-adapter",
"label": "Docusaurus",
"icon": "fas fa-book",
"order": 1,
"integrationMode": "qiankun",
"pluginRoute": "/documentation/",
"pluginUrl": "https://plugin-url.com",
"props": {
"docusaurusUrl": "https://docusaurus-url.com/docusaurus-template/"
}
}
caution

To have a correct routing, the Docusaurus' baseUrl and the pluginRoute must have the same value.

Adapter deploy

To deploy the adapter, you can use the plugin Microlc Docusaurus Adapter available on the marketplace and follow these instructions:

  1. Go to the Microservices section;
  2. Create a new microservice using the Microlc Docusaurus Adapter, available in the Dev Portal category of the marketplace; Docusaurus Adapter
  3. Configure the microservice with a custom name and description;
  4. Complete the creation to deploy an instance of the adapter.

Adapter endpoint configuration

  1. Create a new endpoint;
  2. Define the Base path where you want to expose the adapter (e.g. /docusaurus-adapter);
  3. As type, use Microservice;
  4. Select the microservice name used for the adapter;
  5. Complete the creation.

After that, the situation should be similar to the following:

Adapter configured

Docusaurus website

The docusaurus website instance does not require any configuration and can be deployed separately.

Docusaurus deploy

To deploy docusaurus, you can use the plugin Microlc Docusaurus Template available on the marketplace and follow these instructions:

  1. Go to the Microservices section;
  2. Create a new microservice using the Microlc Docusaurus Template in the Dev Portal category of the marketplace; Docusaurus Template
  3. Configure the microservice with a custom name and description;
  4. Complete the creation to deploy an instance of the adapter.
note

By default, it is configured to use /documentation/ as base url: to change it, edit the value exported in the baseUrl.js, placed on the root of the project repository.

Docusaurus endpoint configuration

  1. Create a new endpoint;
  2. Define the Base path where you want to expose Docusaurus (e.g. /docusaurus-template).
    NOTE: it must be different from the pluginRoute that will be defined in the adapter;
  3. As type, use Microservice;
  4. Select the microservice name used for Docusaurus;
  5. Complete the creation.

Docusaurus assets configuration

  1. Create a new endpoint;
  2. Define the Base path, that must adhere the format: /{docusaurusAdapterPluginRouteValue}/assets.
    e.g. if you set /documentation/ in the adapter configuration, the Base path must be defined as /documentation/assets;
  3. As type, use Microservice;
  4. Select the microservice name used for Docusaurus;
  5. Complete the creation;
  6. Assign to Rewrite Base Path the value /assets.

After that, the situation should be similar to the following:

Adapter configured

Result

After a deployment, your new Dev Portal should be exposed at the / path of your host (e.g. https://your-host-com/), and should be similar to the following:

Docusaurus Example