english | русский

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:

• Prepared runtime
• MarkdownIt transform plugin
• React hooks

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 results script and style sections.
  Can be a string (both script and style will use the same name) or an object with separate script and style properties.
  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/styles';

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.