This is an extension of the Diplodoc platform, which allows using the Page Constructor component from Gravity UI in your documentation. Page Constructor is a library for rendering web pages or their parts based on YAML data. This extension enables creating rich, interactive page layouts with various block types directly in your markdown files.
The extension contains some parts:
Attach the plugin to the transformer:
import pageConstructorExtension from '@diplodoc/page-constructor-extension';
import transform from '@diplodoc/transform';
const {result} = await transform(
`
::: page-constructor
blocks:
- type: 'header-block'
title: 'My Header'
description: 'This is a description'
:::
`,
{
plugins: [pageConstructorExtension.transform({bundle: false})],
},
);Don't forget to add the runtime to make page constructor interactive:
// Import the runtime in your application
import '@diplodoc/page-constructor-extension/runtime';
import '@diplodoc/page-constructor-extension/runtime/style';
// Or include it in your HTML
<script src='_assets/page-constructor.js'></script>
<link rel='stylesheet' href='_assets/page-constructor.css' />You can use the page constructor in your markdown files using the page-constructor directive:
::: page-constructor
blocks:
- type: 'header-block'
title: 'My Header'
description: 'This is a description'
:::Note: The blocks: property is required. Direct list format without the blocks: prefix is not supported.
Plugin for @diplodoc/transform package.
Options:
-
runtime- name of runtime script and style which will be exposed in resultsscriptandstylesections.
Can be a string (both script and style will use the same name) or an object with separatescriptandstyleproperties.
Default:{ script: '_assets/page-constructor.js', style: '_assets/page-constructor.css' } -
bundle- boolean flag to enable/disable copying of bundled runtime to target directory.
Where target directory is<transformer output option>/<plugin runtime option>
Default:true -
assetLinkResolver- function to resolve asset links (images, videos, etc.) in the page constructor content.
Signature:(link: string) => string
Default:undefined -
contentLinkResolver- function to resolve content links (markdown files, HTML files, etc.) in the page constructor content.
Signature:(link: string) => string
Default:undefined
The Page Constructor requires runtime scripts to make content interactive on your page. There are two main approaches to adding these scripts:
Best for:
- Static HTML pages
- Server-rendered applications
- When you want to separate the runtime from your main application code
<html>
<head>
<!-- Assets generated by the MarkdownIt transform plugin -->
<script src="_assets/page-constructor.js"></script>
<link rel="stylesheet" href="_assets/page-constructor.css" />
</head>
<body>
${result.html}
</body>
</html>Best for:
- Single-page applications
- When using a module bundler (webpack, rollup, etc.)
- When you want to control versioning of the runtime
import '@diplodoc/page-constructor-extension/runtime';
import '@diplodoc/page-constructor-extension/runtime/style';The runtime automatically detects whether to hydrate or render content based on the content's structure:
- Server-rendered content (with pre-rendered HTML) will be hydrated
- Browser-rendered content (empty placeholder) will be fully rendered
This allows you to use a single runtime that intelligently determines the appropriate rendering method, simplifying integration in mixed environments where both server and browser rendering are used.
Important note about sanitization:
When using server-side rendering (SSR), all HTML passes through the default sanitizer of the transform. However, when rendering on the client side, Page Constructor content is not sanitized automatically. If you need this functionality in client-side rendering scenarios, you need to handle content sanitization yourself to prevent potential security issues.
There are two ways to initialize the Page Constructor runtime:
Best for:
- React applications
- When you need more control over initialization timing
- When you want to integrate with React's component lifecycle
import {PageConstructorRuntime} from '@diplodoc/page-constructor-extension/react';
function App() {
return (
<>
{/* Your content */}
<PageConstructorRuntime />
</>
);
}Best for:
- Static HTML pages
- Non-React applications
- Simple integration scenarios
// Import the runtime - it will automatically detect the rendering type
import '@diplodoc/page-constructor-extension/runtime';In addition to the PageConstructorRuntime component described in the Initialization Methods section, the extension provides React hooks for more control over the rendering process:
import {
usePageConstructorController,
usePageConstructor,
} from '@diplodoc/page-constructor-extension/react';
function MyComponent() {
// Get the controller
const controller = usePageConstructorController();
// Get the render function
const renderPageConstructors = usePageConstructor();
// Render page constructors when needed
useEffect(() => {
if (controller) {
renderPageConstructors();
}
}, [controller, renderPageConstructors]);
return <div>My Component</div>;
}These hooks are useful when you need to:
- Control when page constructors are rendered
- Integrate with other React components or libraries
- Implement custom rendering logic
- Respond to specific events or state changes
The assetLinkResolver and contentLinkResolver options allow you to customize how links are resolved in the page constructor content. These functions are called for each link in the content and should return the resolved link.
assetLinkResolver: Called for links to assets (images, videos, etc.)contentLinkResolver: Called for links to content (markdown files, HTML files, etc.)
Example:
pageConstructorPlugin({
// Other options...
assetLinkResolver: (link) => {
// Add a prefix to asset links
return link.startsWith('http') ? link : `/assets/${link}`;
},
contentLinkResolver: (link) => {
// Convert .md links to .html
return link.endsWith('.md') ? link.replace('.md', '.html') : link;
},
});See the example directory for a complete example of how to use this extension.