Using Markdown and Localization in the WordPress Block Editor

Need to display documentation directly within the WordPress editor? This article explores the optimal approach, leveraging Markdown for streamlined documentation management and localization.

While React components and HTML might seem intuitive, they can quickly become unwieldy and difficult to maintain for extensive documentation. Consider this example from a previous article showing documentation in a modal:

const CacheControlDescription = () => {
  return (
    <p>The Cache-Control header will contain the minimum max-age value from all fields/directives involved in the request, or <code>no-store if the max-age is 0</code></p>
  )
}

Markdown offers a cleaner solution. The above could be refactored into a Markdown file (/docs/cache-control.md):

The Cache-Control header will contain the minimum max-age value from all fields/directives involved in the request, or `no-store` if the max-age is 0

Markdown vs. HTML: Advantages and Disadvantages

Markdown simplifies the process, but lacks built-in localization support, unlike React components which allow for easy translation using POT files. Since localization is crucial, we'll address this limitation. This article aims to achieve two key objectives:

1. Utilizing Markdown for documentation within a WordPress editor block.
2. Implementing documentation translation based on the user's language.

Loading Markdown Content

With /docs/cache-control.md created, we can import and render its HTML-converted content:

import CacheControlDocumentation from '../docs/cache-control.md';

const CacheControlDescription = () => {
  return (
    <div dangerouslysetinnerhtml="{{" __html: cachecontroldocumentation></div>
  );
}

This relies on webpack, the WordPress editor's core module bundler (version 4.42). We'll customize webpack's configuration to handle Markdown and HTML loaders.

Create webpack.config.js at the block's root:

const defaultConfig = require('@wordpress/scripts/config/webpack.config');

module.exports = {
  ...defaultConfig,
  module: {
    ...defaultConfig.module,
    rules: [
      ...defaultConfig.module.rules,
      {
        test: /\.md$/,
        use: [
          { loader: "html-loader" },
          { loader: "markdown-loader" }
        ]
      }
    ],
  },
};

Install necessary packages:

npm install --save-dev markdown-loader html-loader

For improved organization, add a webpack alias (@docs pointing to /docs):

const path = require('path');
config.resolve.alias['@docs'] = path.resolve(process.cwd(), 'docs/');

Now imports simplify to:

import CacheControlDocumentation from '@docs/cache-control.md';

Localizing Documentation

Since direct Markdown translation isn't feasible, we create language-specific Markdown files:

• /docs/en/cache-control.md
• /docs/fr/cache-control.md
• /docs/zh/cache-control.md etc.

This approach can also handle region-specific variations (e.g., /docs/en_US/cache-control.md).

Retrieving User Language

The user's language is obtained using get_locale() and parsed to extract the language code:

function get_locale_language(): string {
  $localeParts = explode('_', get_locale());
  return $localeParts[0];
}

This language code is passed to the block via wp_localize_script():

wp_localize_script(
  $blockScriptRegistrationName,
  'graphqlApiCacheControl',
  [
    'userLang' => get_locale_language(),
  ]
);

Now accessible in the block as window.graphqlApiCacheControl.userLang.

Dynamic Imports

Since the user's language is known only at runtime, we use dynamic imports:

const lang = window.graphqlApiCacheControl.userLang;
import(`@docs/${lang}/cache-control.md`).then(module => {
  // ...
});

The content is accessed via obj.default:

const cacheControlContent = import(`@docs/${lang}/cache-control.md`).then(obj => obj.default);

This is encapsulated in a getMarkdownContent function:

const getMarkdownContent = (fileName, lang) => {
  return import(/* webpackChunkName: "docs/[request]" */ `@docs/${lang}/${fileName}.md`)
    .then(obj => obj.default);
};

The /* webpackChunkName: "docs/[request]" */ comment ensures organized chunk management.

Setting the Public Path

The publicPath is crucial for webpack to locate the dynamically loaded chunks. This can be hardcoded, set via an environment variable, or passed at runtime. For this example, we'll pass it:

$blockPublicPath = plugin_dir_url(__FILE__) . '/blocks/cache-control/build/';
wp_localize_script(
  $blockScriptRegistrationName,
  'graphqlApiCacheControl',
  [
    // ...
    'publicPath' => $blockPublicPath,
  ]
);

Then set it on the JavaScript side:

__webpack_public_path__ = window.graphqlApiCacheControl.publicPath;

Default Language Fallback

A fallback mechanism handles missing translations:

const getMarkdownContentOrUseDefault = (fileName, defaultLang, lang) => {
  return getMarkdownContent(fileName, lang)
    .catch(err => getMarkdownContent(fileName, defaultLang));
};

Integrating with the Modal

Finally, the Markdown content is integrated into the modal:

import { useState, useEffect } from '@wordpress/element';
// ... other imports

const CacheControlContentModal = (props) => {
  // ...
  const [page, setPage] = useState([]);

  useEffect(() => {
    getMarkdownContentOrUseDefault(fileName, defaultLang, lang).then(value => {
      setPage(value);
    });
  }, []);

  return (
    <contentmodal content="{page}"></contentmodal>
  );
};

This approach provides a robust, maintainable, and localized documentation system within the WordPress editor.

The above is the detailed content of Using Markdown and Localization in the WordPress Block Editor. For more information, please follow other related articles on the PHP Chinese website!