From b468c4a43a0acf07027aedbd12b123fee6b7be80 Mon Sep 17 00:00:00 2001 From: Pete Cheslock Date: Fri, 21 Nov 2025 11:56:49 -0500 Subject: [PATCH 1/2] Add tabbed content support in documentation and implement conversion to Docusaurus Tabs components - Introduced a new section in README.md detailing how to create tabbed content using HTML comment markers for Docusaurus. - Implemented a function in repo-transforms.js to convert GitHub-style tab markers into Docusaurus Tabs components, enhancing documentation interactivity. Signed-off-by: Pete Cheslock --- README.md | 38 +++++++++++++ .../remote-sources/repo-transforms.js | 55 ++++++++++++++++++- 2 files changed, 92 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1322ea2..ff3c908 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,43 @@ To add other remote content (non-component): **For local website content:** - Follow the standard pull request process below +### Creating Tabs in Remote Content + +When writing documentation in source repositories (like llm-d/llm-d) that will be synced to this Docusaurus site, you can create tabbed content using HTML comment markers. These are invisible in GitHub but will be transformed into Docusaurus tabs during the build. + +**In your GitHub README:** +```markdown +### Deploy Model Servers + + + +```bash +kubectl apply -k ./manifests/modelserver/gke -n ${NAMESPACE} +``` + + +```bash +kubectl apply -k ./manifests/modelserver/gke-a4 -n ${NAMESPACE} +``` + + +```bash +kubectl apply -k ./manifests/modelserver/coreweave -n ${NAMESPACE} +``` + +``` + +**Key points:** +- Use `` and `` to wrap the entire tabbed section +- Use `` before each tab's content +- Add `:default` after the label to make it the default selected tab (e.g., ``) +- **No imports needed** - the transformation automatically adds them +- On GitHub, the HTML comments are invisible, showing clean markdown +- On Docusaurus, these are transformed into proper `` components + +**Result on Docusaurus:** +The content will automatically be transformed with the proper Tabs imports and components, creating an interactive tabbed interface. + ### Troubleshooting | Problem | Solution | @@ -170,6 +207,7 @@ To add other remote content (non-component): | Links broken | Make sure you're using `createStandardTransform()` | | Component not showing | Check `components-data.yaml` and repository accessibility | | Wrong sidebar order | Adjust `sidebarPosition` numbers in configuration | +| Tabs not rendering | Check that you have both `TABS:START` and `TABS:END` markers | ## BEFORE DOING A PULL REQUEST diff --git a/remote-content/remote-sources/repo-transforms.js b/remote-content/remote-sources/repo-transforms.js index ad7f85f..3aadf71 100644 --- a/remote-content/remote-sources/repo-transforms.js +++ b/remote-content/remote-sources/repo-transforms.js @@ -55,12 +55,65 @@ function getInternalGuidePath(githubUrl) { return null; } +/** + * Convert GitHub-friendly tab markers to Docusaurus Tabs components + */ +function convertTabsToDocusaurus(content) { + // Check if there are any tab blocks + const hasTabBlocks = //.test(content); + if (!hasTabBlocks) return content; + + // Pattern to match tab blocks + const tabBlockRegex = /\n([\s\S]*?)/g; + + const transformedContent = content.replace(tabBlockRegex, (match, tabsContent) => { + // Extract individual tabs + const tabRegex = /\n([\s\S]*?)(?=`); + tabs.push({ label, content, isDefault }); + } + + if (tabs.length === 0) return match; + + // Generate Docusaurus Tabs component (without imports here) + let result = `\n`; + + tabs.forEach(tab => { + const defaultAttr = tab.isDefault ? ' default' : ''; + result += ` \n\n`; + result += `${tab.content}\n\n`; + result += ` \n`; + }); + + result += ``; + + return result; + }); + + // Add imports at the top of the file if tabs were found + if (transformedContent !== content) { + return `import Tabs from '@theme/Tabs';\nimport TabItem from '@theme/TabItem';\n\n${transformedContent}`; + } + + return transformedContent; +} + /** * Apply essential MDX compatibility fixes and content transformations * Combines all content-only transformations that don't require repository information */ function applyBasicMdxFixes(content) { - return content + // First convert tabs to Docusaurus format + let transformed = convertTabsToDocusaurus(content); + + // Then apply other MDX fixes + return transformed // Convert GitHub-style callouts to Docusaurus admonitions .replace(/^> \[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*\n((?:> .*\n?)*)/gm, (match, type, content) => { // Map GitHub callout types to Docusaurus admonition types From 1060804cabe505e9d826077d1155f3463f62d8c3 Mon Sep 17 00:00:00 2001 From: Pete Cheslock Date: Fri, 21 Nov 2025 13:13:59 -0500 Subject: [PATCH 2/2] Enhance documentation with GitHub callouts support and refine tab conversion Signed-off-by: Pete Cheslock --- README.md | 33 +++++++++++++++---- .../remote-sources/repo-transforms.js | 27 +++++++++------ 2 files changed, 44 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ff3c908..c172314 100644 --- a/README.md +++ b/README.md @@ -171,19 +171,14 @@ When writing documentation in source repositories (like llm-d/llm-d) that will b -```bash kubectl apply -k ./manifests/modelserver/gke -n ${NAMESPACE} -``` -```bash kubectl apply -k ./manifests/modelserver/gke-a4 -n ${NAMESPACE} -``` -```bash kubectl apply -k ./manifests/modelserver/coreweave -n ${NAMESPACE} -``` + ``` @@ -198,6 +193,32 @@ kubectl apply -k ./manifests/modelserver/coreweave -n ${NAMESPACE} **Result on Docusaurus:** The content will automatically be transformed with the proper Tabs imports and components, creating an interactive tabbed interface. +### GitHub Callouts Support + +The transformation system also automatically converts GitHub-style callouts to Docusaurus admonitions: + +```markdown +> [!NOTE] +> This is a note + +> [!TIP] +> This is a tip + +> [!IMPORTANT] +> This is important + +> [!WARNING] +> This is a warning + +> [!CAUTION] +> This is dangerous + +> [!REQUIREMENTS] +> These are requirements +``` + +These will be automatically converted to the appropriate Docusaurus `:::note`, `:::tip`, `:::info`, `:::warning`, and `:::danger` admonitions during the build. + ### Troubleshooting | Problem | Solution | diff --git a/remote-content/remote-sources/repo-transforms.js b/remote-content/remote-sources/repo-transforms.js index 3aadf71..7a485a5 100644 --- a/remote-content/remote-sources/repo-transforms.js +++ b/remote-content/remote-sources/repo-transforms.js @@ -67,16 +67,22 @@ function convertTabsToDocusaurus(content) { const tabBlockRegex = /\n([\s\S]*?)/g; const transformedContent = content.replace(tabBlockRegex, (match, tabsContent) => { - // Extract individual tabs - const tabRegex = /\n([\s\S]*?)(?=`); - tabs.push({ label, content, isDefault }); + // Skip first element (empty or content before first tab) + for (let i = 1; i < tabSections.length; i++) { + const section = tabSections[i]; + + // Extract label and check for :default marker + const labelMatch = section.match(/^([^:]+?)(?::default)?\s*-->\n([\s\S]*?)$/); + if (labelMatch) { + const label = labelMatch[1].trim(); + const content = labelMatch[2].trim(); + const isDefault = section.includes(':default -->'); + tabs.push({ label, content, isDefault }); + } } if (tabs.length === 0) return match; @@ -115,14 +121,15 @@ function applyBasicMdxFixes(content) { // Then apply other MDX fixes return transformed // Convert GitHub-style callouts to Docusaurus admonitions - .replace(/^> \[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*\n((?:> .*\n?)*)/gm, (match, type, content) => { + .replace(/^> \[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION|REQUIREMENTS)\]\s*\n((?:> .*\n?)*)/gm, (match, type, content) => { // Map GitHub callout types to Docusaurus admonition types const typeMap = { 'NOTE': 'note', 'TIP': 'tip', 'IMPORTANT': 'info', 'WARNING': 'warning', - 'CAUTION': 'danger' + 'CAUTION': 'danger', + 'REQUIREMENTS': 'info' // Map to info admonition }; const docusaurusType = typeMap[type] || type.toLowerCase();