Implement DITA Features

In this section, we will explore how to implement one of the core DITA principles (content reuse) in a Docusaurus site. We will see how to reuse the content of an entire document and also a section of a document.

To achieve this, we need to use MDX (.mdx) files. MDX is a superset of Markdown that allows you to embed JSX (React components) directly within Markdown content. This powerful feature makes it possible to modularize and reuse documentation content across your site.

However, Docusaurus has a key limitation: it does not allow importing one .mdx or .md file from another when both are located inside the docs folder. In other words, you cannot reuse content between two files if they both reside in the docs directory.

To work around this, we place reusable content such as shared sections or full documents in the src folder. These source files can then be imported into .mdx files within the docs directory.

Process

Let’s create a folder (say reusable) within the src folder. In the reusable docs folder, we will create an MDX file and add the content that needs to be reused. In the actual documentation (within the docs folder), we will use React syntax to import the content. All the docs in which the content is reused from the src folder, must be saved as an MDX file (and not MD file).

Reusing an Entire Page

In this section, let’s explore how we can reuse an entire page. The following steps describe the process.

1. Create a file called ReusableDoc.mdx in the src/reusable folder.

2. Add the reusable content in the following format.

Replace Title with your desired title. Replace Content with the content to be reused.

export default function ReusableDoc() {
  return (
    <>
      <h1>Title</h1>
      <p>Content</p>
    </>
  );
}

3. In any file within the docs folder, you can reuse all the content from the doc created in step 2, by inserting the following code snippet.

import ReusableDoc from '@site/src/content/ReusableDoc.mdx';
<ReusableDoc />

The file within the docs folder in which you use the above code, must be saved with a .mdx extension.

Reusing a section

Let’s assume that you wish to use a paragraph or a section in multiple places. This paragraph exists in the same ReusableDoc file created above.

1. Add the following code snippet to the ReusableDoc file located in the src/reusable folder.

Replace Heading for reusable paragraph with your desired heading. Replace content to be reused with your content.

export const SectionReuse = () => (
  <>
    <h2><Heading for reusable paragraph></h2>
    <p>
      Content to be reused.
    </p>
  </>
);

If you do not wish to include any heading for your section, you can omit the h2 tag. In the following example, I have used the reusable docs folder and created a paragraph as follows.

export const SectionReuse = () => (
  <>
    <h2>Reusable Paragraph</h2>
    
    <p>This is a reusable content which would be used in multiple places.
    </p>
  </>
);

2. In any file within the docs folder, you can reuse this content by inserting the following code snippet.

import { SectionReuse } from '@site/src/content/ReusableDoc.mdx';
<SectionReuse />

You must save this file with a .mdx extension.

Similarly, you can create multiple paragraphs with different function name (SectionReuse was used in the above example) and reuse them as required.