Reusing content

Reusing content is an essential practice for improving the maintainability of documentation and enhancing the reading experience for users. By designing reusable components, you can ensure consistency, reduce redundancy, and streamline updates across multiple topics.

Currently, Olares documentation supports content reuse through the following methods:

• Markdown file inclusion: Natively supported by VitePress.
• Tabs: A custom Vue component for organizing and displaying content interactively.

Markdown file inclusion

Markdown file inclusion allows you to reuse content from other topics or create dedicated .md files that store reusable components. This method is ideal for recurring content such as instructions, warnings, or other reusable blocks of text.

Guidelines for Markdown file inclusion

• Dedicated .md files: Store reusable content in dedicated .md files if it is used across multiple topics.
• Context-agnostic content: Ensure the reusable content is generic enough to be used in different contexts without requiring modifications.
• Unsearchable metadata: Set metadata on reusable content files to exclude them from search by adding search: false to the frontmatter of the page.
• Granularity: Focus on reusing blocks of text that are meaningful and substantial. For short, simple content, such as a single sentence or basic instructions, it's often better to include the content directly in the topic. This avoids unnecessary complexity while keeping the documentation simple and easy to maintain.

Example

If you have a reusable warning, you can store it in a file called warning.md:

warning.md:

:::warning
Proceed with caution. Unauthorized changes may cause system instability.
:::

:::warning
This is a development server. Do not use it in a production deployment.
:::

You can reuse the warning by including it in other topics like this:

Procedure.md:

Click **Continue** to complete the action.
@include warning.md{1-3}  #Reuse the first warning (line 1 to line 3)

This is equivalent to the following:

Click **Continue** to complete the action.
:::warning
Proceed with caution. Unauthorized changes may cause system instability.
:::

This ensures that any updates to warning.md are automatically reflected in all topics where it is included.

Tabs

Tabs are a custom Vue component used to display content interactively, especially when presenting alternative options, configurations, or platform-specific instructions. They are particularly useful for improving readability and reducing scrolling.

When to use tabs

• To present different options in a compact format, such as instructions for multiple operating systems (e.g., Windows, macOS, Linux).
• To display alternative workflows or configurations without overwhelming the user with excessive text.
• To create a more engaging and user-friendly reading experience.

How to use tabs

See the Markdown Reference Guide for detailed usage instructions, examples, and best practices.

Example:

<tabs>
<template label="Windows">
Follow these steps to install the software on Windows.
</template>
<template label="macOS">
Follow these steps to install the software on macOS.
</template>
<template label="Linux">
Follow these steps to install the software on Linux.
</template>
</tabs>

This will render as a set of interactive tabs, allowing users to switch between instructions for different platforms.