Besoin d'afficher la documentation directement dans l'éditeur WordPress? Cet article explore l'approche optimale, tirant parti de la marque pour la gestion et la localisation des documents rationalisés.

Bien que les composants React et le HTML puissent sembler intuitifs, ils peuvent rapidement devenir lourds et difficiles à maintenir pour une documentation approfondie. Considérez cet exemple à partir d'un article précédent montrant la documentation dans un modal:

 const CacheControlDescription = () => {
  retour (
    <p>L'en-tête de contr?le de cache contiendra la valeur minimale d'age maximum de tous les champs / directives impliqués dans la demande, ou <code>no-store if the max-age is 0</code>
  )
}</p>

Markdown offre une solution plus propre. Ce qui précède pourrait être refactorisé dans un fichier Markdown ( /docs/cache-control.md ):

 L'en-tête de contr?le de cache contiendra la valeur minimale de l'age maximum de tous les champs / directives impliqués dans la demande, ou ?non-magasin? si l'age maximum est 0

Markdown vs HTML: avantages et inconvénients

Markdown simplifie le processus, mais manque de prise en charge de localisation intégrée, contrairement aux composants React qui permettent une traduction facile à l'aide de fichiers POT. étant donné que la localisation est cruciale, nous aborderons cette limitation. Cet article vise à atteindre deux objectifs clés:

1. Utilisation de Markdown pour la documentation dans un bloc d'éditeur WordPress.
2. Implémentation de la traduction de la documentation basée sur la langue de l'utilisateur.

Chargement du contenu Markdown

Avec /docs/cache-control.md créé, nous pouvons importer et rendre son contenu converti HTML:

 Importer cacheControldocumentation de '../docs/cache-control.md';

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

Cela repose sur WebPack, le module de base de l'éditeur WordPress (version 4.42). Nous personnaliserons la configuration de WebPack pour gérer les chargeurs Markdown et HTML.

Créez webpack.config.js à la racine du bloc:

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

module.exports = {
  ... defaultConfig,
  module: {
    ... defaultconfig.module,
    règles: [
      ... defaultconfig.module.rules,
      {
        tester: /\.md$/,
        utiliser: [
          {Loader: "html-chargedeur"},
          {Loader: "Markdown-chargedeur"}
        ]]
      }
    ],
  },
};

Installez les packages nécessaires:

 Installation de NPM - Save-DEV Markdown-chargedeur HTML-chargeur

Pour une organisation améliorée, ajoutez un alias WebPack ( @docs pointant vers /docs ):

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

Importe maintenant Simplify à:

 Importer cacheConTroldocumentation à partir de '@ docs / cache-control.md';

Localisation de la documentation

étant donné que la traduction directe de Markdown n'est pas possible, nous créons des fichiers de marque spécifiques à la langue:

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

Cette approche peut également gérer les variations spécifiques à la région (par exemple, /docs/en_US/cache-control.md ).

Récupération du langage utilisateur

Le langage de l'utilisateur est obtenu à l'aide de get_locale() et analysé pour extraire le code de la langue:

 fonction get_locale_language (): string {
  $ localparts = explosage ('_', get_locale ());
  Retour $ localparts [0];
}

Ce code linguistique est transmis au bloc via wp_localize_script() :

 wp_localize_script (
  $ BlockScriptregrationname,
  ?GraphQlapicacheControl?,
  [
    'userlang' => get_locale_language (),
  ]]
));

Maintenant accessible dans le bloc comme window.graphqlApiCacheControl.userLang .

Importations dynamiques

étant donné que la langue de l'utilisateur n'est connu qu'à l'exécution, nous utilisons les importations dynamiques:

 const Lang = Window.GraphQlapicacheControl.Userlang;
import (`@docs / $ {lang} / cache-control.md`) .then (module => {
  // ...
});

Le contenu est accessible via obj.default :

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

Ceci est encapsulé dans une fonction getMarkdownContent :

 const getMarkdownContent = (nom de fichier, lang) => {
  return import (/ * webpackchunkname: "docs / [request]" * / `@docs / $ {Lang} / $ {nom de fichier} .md`)
    .Then (obj => obj.default);
};

Le /* webpackChunkName: "docs/[request]" */ Comment assure la gestion des morceaux organisés.

Définir le chemin public

Le publicPath est crucial pour WebPack pour localiser les morceaux chargés dynamiquement. Cela peut être codé en dur, défini via une variable d'environnement ou passé au moment de l'exécution. Pour cet exemple, nous allons le passer:

 $ blockPublicPath = plugin_dir_url (__ file__). '/ blocks / cache-control / build /';
wp_localize_script (
  $ BlockScriptregrationname,
  ?GraphQlapicacheControl?,
  [
    // ...
    'publicPath' => $ blockPublicPath,
  ]]
));

Puis réglez-le du c?té javascript:

 __webpack_public_path__ = window.graphqlapicacheControl.publicPath;

Remplacement de la langue par défaut

Un mécanisme de secours gère les traductions manquantes:

 const getmarkdowncontentorusefault = (filename, defaultlang, lang) => {
  return getMarkdownContent (FileName, Lang)
    .Catch (err => getmarkdownContent (nom de fichier, defaultlang));
};

Intégrer avec le modal

Enfin, le contenu Markdown est intégré dans le modal:

 import {useState, useEffecte} de '@ wordpress / élément';
// ... Autres importations

const CacheControlContentModal = (accessoires) => {
  // ...
  const [page, setPage] = UseState ([]);

  useEFFECT (() => {
    getMarkdownContentorUsedEfault (FileName, Defaultlang, Lang) .Then (Value => {
      setPage (valeur);
    });
  }, []);

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

Cette approche fournit un système de documentation robuste, maintenable et localisé au sein de l'éditeur WordPress.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!