Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Add a way for consumers to pass custom components for MDX parsing

オープン
  • 何か問題がありますか？
#222 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
45/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
typescript
領域
documentation

調査の方向性

src/pages/[section]/[...page].astro:84-106 と src/pages/[section]/[page]/[tab].astro:116-137 のコンポーネント props から始め、次に pf-docs.config.mjs:44 と cli/convertToMDX.ts:48-52 を読みます。設定と import の保持のどちらにするかを決め、カスタムコンポーネントが一般的な MDX と LiveExample のコンテンツで動作し、組み込みの解決を維持し、TypeScript をサポートし、ドキュメント化されていることを確認します。

索引モデルが issue の本文から書いたものです。

説明

enhancement PF Team

Problem Summary

Consumers cannot use custom components directly within their MDX/markdown files. The MDX component mapping is hardcoded in the Astro page files ([...page].astro and [tab].astro), preventing users from injecting custom components like PatternFly's [Alert /] into their documentation content.

Current limitation: While the scope config option (in pf-docs.config.mjs) allows passing custom components for use within [LiveExample] blocks, there's no way to use custom components in the general MDX content outside of examples.

Use Case

When integrating docs-core v1.20.0, consumers need to:

  • Use PatternFly components (Alert, Banner, etc.) directly in markdown content for callouts and warnings

  • Import custom documentation components for specialized content rendering

  • Include organization-specific UI components in documentation pages

  • Render interactive widgets or diagrams inline with documentation

Example of desired usage:

h1. Component Documentation

[Alert variant="warning" title="Important Note"]
  This component is deprecated. Use the new version instead.
[/Alert]

Rest of documentation content...

Current Architecture

MDX components are provided via the components prop on the [Content /] component in Astro page files:

// src/pages/[section]/[...page].astro:84-106
[Content
  components={{
    SectionGallery,
    h1, h2, h3, h4, h5, h6,
    p, a, small, blockquote,
    pre, hr, ul, ol, dl, li, dt, dd,
    LiveExample,
  }}
/]

Why this is hardcoded:

  • The components object maps MDX elements to React/Astro components

  • Currently only includes HTML elements, LiveExample, and SectionGallery

  • No mechanism to merge in user-provided components from config

Related scope mechanism:

  • pf-docs.config.mjs has a scope property for LiveExample components

  • LiveExample.tsx:35-43 merges config.scope with built-in PatternFly components

  • This only applies to code inside [LiveExample] blocks, not general MDX content

MDX import stripping:
The convertToMDX process (cli/convertToMDX.ts:48-52) also removes absolute imports, which would prevent direct imports even if components were available:

function removeExistingImports(content: string): string {
  // Remove imports that are absolute and not CSS
  const importRegex = /^import {?[\w\s,\n]_}? from ['"|?!\.\.?\/](?!._\.css['"])[^'"]*['"];?\n/gm
  return content.replace(importRegex, '')
}

Potential Approaches

Two options have been identified:

  1. Configuration-based approach: Enable consumers to specify custom components through the pf-docs configuration file that become available globally in MDX files

  2. Import preservation approach: Modify the MDX conversion process to retain certain component imports in markdown files, while selectively removing only imports used exclusively in LiveExamples

Completion Criteria

The issue is resolved when:

  1. Custom components in MDX: Consumers can use custom components directly in MDX content outside of [LiveExample] blocks
  2. Configuration support: Clear mechanism (config or import-based) for registering custom components
  3. Component merging: User-provided components are merged with built-in components in the [Content /] components prop
  4. LiveExample compatibility: Custom components work in both general MDX content and within [LiveExample] scopes
  5. No conflicts: Custom components don't interfere with built-in component resolution or auto-generated imports
  6. Type safety: Proper TypeScript support for custom component registration
  7. Documentation: Clear examples showing how to register and use custom components

Technical Notes

  • File locations needing changes:

  • src/pages/[section]/[...page].astro:84-106 (components prop)

  • src/pages/[section]/[page]/[tab].astro:116-137 (components prop)

  • cli/convertToMDX.ts:48-52 (if using import preservation approach)

  • Existing scope config: pf-docs.config.mjs:44 has a scope property (currently only for LiveExample)

  • MDX components are provided via Astro's [Content components={{...}} /] pattern

  • Astro docs: https://docs.astro.build/en/guides/markdown-content/#custom-components-with-imported-mdx

Related Links

Jira Issue: PF-3654

主要言語
TypeScript
スター
3
フォーク
11
平均マージ
4日 18時間
マージ済み PR（30日）
2

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

patternfly/patternfly-doc-core のほかの issue

patternfly/patternfly-doc-core の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。