@diplodoc/page-constructor-extension

v0.12.1

Published

8 days ago

Page constructor plugin for Diplodoc transformer and builder

0High
0Medium
0Low

3y3

page-constructor markdown-it

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 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/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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Diplodoc page-constructor extension

Quickstart

Syntax

MarkdownIt transform plugin

Prepared runtime

1. Using Generated Assets

2. Including in Your Bundle

Rendering Detection

Initialization Methods

1. React Component

2. Direct Runtime Import

3. Conditional Runtime Loading

Transform styles and runtime

React hooks

Link Resolvers

Example