feat: order-independent tab section mapping + FAQ synonyms (0.1.7)

Author: soderlind

CHANGELOG.md

@@ -1,4 +1,8 @@
 # Changelog
+## [0.1.7] - 2025-10-05
+### Fixed
+- wordpress.org tabbed theme now detects FAQ content even when the section is titled "Frequently Asked Questions" or appears out of the typical order. Sections are scanned globally and mapped to canonical tabs (description, installation, faq, changelog) irrespective of order.
+
 
 All notable changes to this project will be documented in this file.
 
@@ -71,6 +75,7 @@ The format is based on Keep a Changelog (https://keepachangelog.com/en/1.0.0/) a
 - Custom parser for WordPress readme formatting (FAQ, changelog headers, etc.)
 
 [0.1.6]: https://github.com/soderlind/wordpress-readme-preview/compare/v0.1.5...v0.1.6
+[0.1.7]: https://github.com/soderlind/wordpress-readme-preview/compare/v0.1.6...v0.1.7
 [0.1.4]: https://github.com/soderlind/wordpress-readme-preview/compare/v0.1.3...v0.1.4
 [0.1.5]: https://github.com/soderlind/wordpress-readme-preview/compare/v0.1.4...v0.1.5
 [0.1.3]: https://github.com/soderlind/wordpress-readme-preview/compare/v0.1.1...v0.1.3

package.json

@@ -2,7 +2,7 @@
 	"name": "wordpress-readme-preview",
 	"displayName": "WordPress Readme",
 	"description": "Preview, validate, and edit WordPress readme.txt files with syntax highlighting, IntelliSense, and accurate rendering",
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"publisher": "persoderlind",
 	"engines": {
 		"vscode": "^1.74.0"

src/preview/htmlGenerator.ts

@@ -2,6 +2,7 @@ import * as vscode from 'vscode';
 import { ParsedReadme, ReadmeHeader, ReadmeSection } from '../parser/readmeParser';
 import { ValidationResult, ValidationError } from '../parser/validator';
 import { WordPressMarkdownParser } from '../parser/markdownParser';
+import { canonicalSectionId } from './sectionMapping';
 
 export interface HtmlGeneratorOptions {
   resource: vscode.Uri;
@@ -107,19 +108,22 @@ export class HtmlGenerator {
   }
 
   private generateTabbedLayout(readme: ParsedReadme, validation: ValidationResult, assets?: PluginAssets): string {
-    // Tabs no longer include separate screenshots; gallery appended to Description panel
+    // Desired tab order; will render placeholders for missing canonical sections
     const tabs = [
       { id: 'description', title: 'Description' },
       { id: 'installation', title: 'Installation' },
       { id: 'faq', title: 'FAQ' },
       { id: 'changelog', title: 'Changelog' }
     ];
 
-    // Map readme sections to tab panels by simple title matching
-    const sectionMap: { [key: string]: string } = {};
+    // Build canonical section map (supports synonyms like Frequently Asked Questions -> faq)
+    const sectionMap: { [canonical: string]: string } = {};
     for (const section of readme.sections) {
-      const key = section.title.toLowerCase();
-      sectionMap[key] = this.generateSection(section);
+      const canonical = canonicalSectionId(section.title);
+      // First occurrence wins to preserve original ordering content
+      if (!sectionMap[canonical]) {
+        sectionMap[canonical] = this.generateSection(section);
+      }
     }
 
     // Asset header
@@ -129,8 +133,8 @@ export class HtmlGenerator {
     const tabButtons = tabs.map((t, i) => `<button role="tab" class="wporg-tab ${i===0?'active':''}" aria-selected="${i===0}" aria-controls="panel-${t.id}" id="tab-${t.id}">${t.title}</button>`).join('');
     const panels = tabs.map((t, i) => {
       let content = '';
-      if (sectionMap[t.title.toLowerCase()]) {
-        let sectionHtml = sectionMap[t.title.toLowerCase()] || '';
+      if (sectionMap[t.id]) {
+        let sectionHtml = sectionMap[t.id] || '';
         if (t.id === 'description' && assets?.screenshots && assets.screenshots.length) {
           // Append screenshots gallery with heading and anchor for hash #screenshots
           sectionHtml += `<div id="screenshots" class="screenshots-anchor"></div><h2 class="section-title screenshots-title">Screenshots</h2>${this.renderScreenshots(assets)}`;
@@ -404,15 +408,8 @@ export class HtmlGenerator {
   private generateSection(section: ReadmeSection): string {
     const sectionId = this.generateSectionId(section.title);
     // Define canonical alias IDs that tabbed theme expects
-    const canonicalIds: { [key: string]: string } = {
-      'description': 'description',
-      'installation': 'installation',
-      'faq': 'faq',
-      'frequently-asked-questions': 'faq',
-      'screenshots': 'screenshots',
-      'changelog': 'changelog'
-    };
-    const aliasId = canonicalIds[sectionId];
+    const canonicalId = canonicalSectionId(section.title);
+    const aliasId = canonicalId !== sectionId ? canonicalId : undefined;
 
     // Process FAQ questions (= Question =) as H3 headers
     let processedContent = section.content;

src/preview/sectionMapping.ts

@@ -0,0 +1,22 @@
+// Helper for mapping arbitrary section titles to canonical IDs used in tabbed theme
+// Keeps logic independent of VS Code APIs for easy unit testing.
+
+export function canonicalSectionId(title: string): string {
+  const slug = title.toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  const map: Record<string, string> = {
+    'frequently-asked-questions': 'faq',
+    'faq': 'faq',
+    'description': 'description',
+    'installation': 'installation',
+    'changelog': 'changelog',
+    'screenshots': 'screenshots'
+  };
+  return map[slug] || slug;
+}
+
+export function isCanonicalTab(id: string): boolean {
+  return ['description','installation','faq','changelog'].includes(id);
+}

src/test/tabbedTheme.sections.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { ReadmeParser } from '../parser/readmeParser';
+import { HtmlGenerator } from '../preview/htmlGenerator';
+import { vi } from 'vitest';
+
+// Mock vscode module to satisfy htmlGenerator import in unit context
+vi.mock('vscode', () => {
+  return {
+    Uri: {
+      joinPath: (...parts: any[]) => parts[parts.length - 1],
+      parse: (v: string) => ({ toString: () => v })
+    }
+  };
+});
+
+// Minimal stubs for VS Code types used inside HtmlGenerator
+// We'll monkey-patch methods that rely on webview specifics.
+const fakeUri: any = { toString: () => 'vscode-resource://fake' };
+const fakeWebview: any = {
+  asWebviewUri: (u: any) => u,
+  cspSource: 'vscode-resource:'
+};
+const fakeContext: any = { extensionUri: fakeUri };
+
+function extractPanel(html: string, id: string): string | undefined {
+  // Use [\s\S] to match any content including newlines greedily but stop at first closing </div> of the panel.
+  const re = new RegExp(`<div role=\"tabpanel\" id=\"panel-${id}\"[\\s\\S]*?<\\/div>`,'i');
+  const m = html.match(re);
+  return m ? m[0] : undefined;
+}
+
+describe('Tabbed theme section mapping', () => {
+  it('maps Frequently Asked Questions to FAQ tab regardless of order', async () => {
+    const content = `=== Plugin Name ===\nContributors: a\nTags: one\nRequires at least: 5.0\nTested up to: 6.3\nStable tag: 1.0\nLicense: GPLv2\n\n== Installation ==\nSteps here\n\n== Frequently Asked Questions ==\n= What? =\nBecause.\n\n== Description ==\nSome description text.\n`;    
+    const parsed = ReadmeParser.parse(content);
+    const generator = new HtmlGenerator(fakeContext as any);
+    const validation: any = { errors: [], warnings: [], score: 100 };
+    const html = await generator.generateHtml(parsed, validation, { resource: fakeUri, webview: fakeWebview, extensionUri: fakeUri, theme: 'wordpress-org' });
+
+    const faqPanel = extractPanel(html, 'faq');
+    expect(faqPanel).toBeDefined();
+    expect(faqPanel).toMatch(/What\?/);
+
+    const descPanel = extractPanel(html, 'description');
+    expect(descPanel).toBeDefined();
+  });
+
+  it('supports simple FAQ heading labeled just FAQ', async () => {
+    const content = `=== Plugin Name ===\nContributors: a\nTags: one\nRequires at least: 5.0\nTested up to: 6.3\nStable tag: 1.0\nLicense: GPLv2\n\n== FAQ ==\n= Why? =\nBecause.\n\n== Description ==\nSome description text.\n`;    
+    const parsed = ReadmeParser.parse(content);
+    const generator = new HtmlGenerator(fakeContext as any);
+    const validation: any = { errors: [], warnings: [], score: 100 };
+    const html = await generator.generateHtml(parsed, validation, { resource: fakeUri, webview: fakeWebview, extensionUri: fakeUri, theme: 'wordpress-org' });
+
+    const faqPanel = extractPanel(html, 'faq');
+    expect(faqPanel).toBeDefined();
+    expect(faqPanel).toMatch(/Why\?/);
+  });
+});