Security News
The Changelog Podcast: Practical Steps to Stay Safe on npm
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.
By Sarah Gooding -  Oct 31, 2025
🚀 DAY 5 OF LAUNCH WEEK: Introducing Socket Firewall Enterprise.Learn more →
@diplodoc/page-constructor-extension
Advanced tools
@diplodoc/page-constructor-extension
Page constructor plugin for Diplodoc transformer and builder
Diplodoc page-constructor extension
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:
Quickstart
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/styles';
// Or include it in your HTML
<script src='_assets/page-constructor.js'></script>
<link rel='stylesheet' href='_assets/page-constructor.css' />
// Or load it conditionally only when needed
import {PAGE_CONSTRUCTOR_RUNTIME} from '@diplodoc/page-constructor-extension/plugin';
// Check if page constructor is used in the content
if (result.meta?.script?.includes(PAGE_CONSTRUCTOR_RUNTIME)) {
// Load runtime asynchronously
Promise.all([
import('@diplodoc/page-constructor-extension/runtime'),
import('@diplodoc/page-constructor-extension/runtime/styles')
]);
}
Syntax
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.
MarkdownIt transform plugin
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
Prepared runtime
The Page Constructor requires runtime scripts to make content interactive on your page. There are two main approaches to adding these scripts:
1. Using Generated Assets
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>
2. Including in Your Bundle
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';
Rendering Detection
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.
Initialization Methods
There are three ways to initialize the Page Constructor runtime:
1. React Component
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 />
</>
);
}
2. Direct Runtime Import
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';
Additional parameters:
theme(optional) - Sets the theme for Page Constructor components. Available values:'light' | 'dark'preMountHook(optional) - Callback function that is called before mounting the component. Receives the container element as parameter.
3. Conditional Runtime Loading
Best for:
- Performance optimization
- When you want to load the runtime only if it's needed
- Large applications where page constructor might not be used on every page
import {useState, useEffect} from 'react';
import {
transform as pageConstructorPlugin,
PAGE_CONSTRUCTOR_RUNTIME,
} from '@diplodoc/page-constructor-extension/plugin';
import {PageConstructorRuntime} from '@diplodoc/page-constructor-extension/react';
function App() {
const {result} = transform(content, {
plugins: [pageConstructorPlugin()],
});
const [runtimeLoaded, setRuntimeLoaded] = useState(false);
// Asynchronously load runtime only if needed
useEffect(() => {
if (result.meta?.script?.includes(PAGE_CONSTRUCTOR_RUNTIME)) {
// Load runtime asynchronously
Promise.all([
import('@diplodoc/page-constructor-extension/runtime'),
import('@diplodoc/page-constructor-extension/runtime/styles'),
]).then(() => {
setRuntimeLoaded(true);
});
}
}, [result.meta?.script]);
return (
<>
<div dangerouslySetInnerHTML={{__html: result.html}} />
{runtimeLoaded && <PageConstructorRuntime />}
</>
);
}
Transform styles and runtime
The @diplodoc/page-constructor-extension package does not bundle the @diplodoc/transform CSS and JS at runtime, so you need to import them manually:
@import '~@diplodoc/transform/dist/css/yfm.css';
import '@diplodoc/transform/dist/js/yfm';
React hooks
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
Link Resolvers
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;
},
});
Example
See the example directory for a complete example of how to use this extension.
Keywords
FAQs
Page constructor plugin for Diplodoc transformer and builder
We found that @diplodoc/page-constructor-extension demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Package last updated on 30 Oct 2025
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
Security Community Slams MIT-linked Report Claiming AI Powers 80% of Ransomware
Experts push back on new claims about AI-driven ransomware, warning that hype and sponsored research are distorting how the threat is understood.
By Sarah Gooding -  Oct 30, 2025
Security News
Ruby Core Team Assumes Stewardship of RubyGems and Bundler, Former Maintainers Offer to Transfer All Rights to Matz
Ruby's creator Matz assumes control of RubyGems and Bundler repositories while former maintainers agree to step back and transfer all rights to end the dispute.
By Sarah Gooding -  Oct 29, 2025