Skip to content

feat: add .plain.html support for HTML folder serving#2631

Merged
karlpauls merged 8 commits into
mainfrom
plainhtml
Nov 13, 2025
Merged

feat: add .plain.html support for HTML folder serving#2631
karlpauls merged 8 commits into
mainfrom
plainhtml

Conversation

@karlpauls
Copy link
Copy Markdown
Contributor

@karlpauls karlpauls commented Nov 12, 2025 •
edited
Loading

Summary

Adds support for .plain.html files in HTML folder mode with metadata extraction. When a request comes in for a path without an extension (e.g., /drafts/page), the server now:

  1. First checks for a .html file (existing behavior)
  2. If not found, checks for a .plain.html file (new)
  3. Extracts and processes metadata blocks from .plain.html content
  4. Wraps content in proper HTML structure: <html><head><body><header><main><footer>
  5. Applies live reload injection to both file types

This enables content preview workflows where users can create simple HTML fragments with metadata, and the CLI automatically provides the complete page structure with proper meta tags.

Changes

  • Refactored handleHtmlFolderRequest() to use DRY approach with shared serving logic
  • Added resolveHtmlFolderFile() to check .html then .plain.html with proper priority
  • Added transformPlainHtml() to wrap plain content with HeadHtmlSupport integration

Testing

All tests pass (25 HTML folder tests, 252 total). New tests verify:

  • .plain.html files wrapped with proper HTML structure
  • .html files take precedence over .plain.html
  • Metadata extraction and meta tag generation
  • Special properties (title:suffix, canonical, tags)
  • Default value extraction (H1, paragraph, image)
  • Image src extraction from tags in metadata
  • HTML stripping from metadata values (using proper parsing)
  • Special character escaping in meta tags
  • Live reload works identically for both file types
  • Path traversal protection applies to both file types
  • Nested directory support
  • Remote head.html integration with HeadHtmlSupport
  • Behavior when head.html is missing

Documentation

  • Updated README.md with html-folder feature documentation and examples
  • Added CLI help text for --html-folder option

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Nov 12, 2025

This PR will trigger a minor release when merged.

@trieloff as-a-bot
Copy link
Copy Markdown
Contributor

trieloff commented Nov 13, 2025 •
edited
Loading

Code Review

Overview

This PR adds support for serving .plain.html files in HTML folder mode, automatically wrapping them with full HTML structure including head.html content. The implementation maintains backward compatibility while enabling a streamlined content preview workflow.

✅ Strengths

  1. Well-structured refactoring - The code extraction into resolveHtmlFolderFile() and transformPlainHtml() follows DRY principles and improves maintainability
  2. Security-conscious - Path traversal protection is consistently applied to both file types with proper validation
  3. Comprehensive test coverage - 6 new tests covering edge cases (precedence, nesting, security, missing head.html, live reload)
  4. Clear precedence logic - .html files correctly take priority over .plain.html, preventing unexpected behavior
  5. Live reload integration - Properly applies live reload to both file types uniformly

💡 Suggestions for Improvement

1. Duplicate Security Validation (src/server/HelixServer.js:182-190)

Both .html and .plain.html paths perform identical security checks. Consider extracting this into a helper:

// Add after resolveHtmlFolderFile:
validatePathSecurity(filePath) {
  const resolvedProjectDir = path.resolve(this._project.directory);
  const relPath = path.relative(resolvedProjectDir, filePath);
  return !relPath.startsWith('..');
}

Then use: if (!this.validatePathSecurity(htmlFile)) return null;

4. Test Enhancement Opportunity

All new tests use the same head.html setup. Consider adding a test that verifies behavior with remote head.html (successful fetch from proxy URL) to ensure HeadHtmlSupport integration works in all scenarios.

🔍 Code Quality Assessment

  • ✅ Correctness: Logic is sound, handles all documented cases
  • ✅ Performance: Efficient file resolution, minimal overhead
  • ✅ Security: Proper path validation prevents directory traversal
  • ✅ Maintainability: Clean separation of concerns
  • ✅ Test Coverage: Excellent coverage of edge cases

Minor Observations

  1. The isPlain flag is clear and well-used
  2. Error handling uses try-catch appropriately (fails gracefully to next middleware)
  3. Logging maintains consistency with existing patterns

Verdict

Approved - This is a solid implementation. The suggestions above are minor optimizations and don't block merging. The feature works as designed, maintains security, and has excellent test coverage.

Great work on the refactoring! The extracted methods make the code much more readable than the original implementation.

github-advanced-security[bot]
github-advanced-security AI found potential problems Nov 13, 2025
View reviewed changes
Comment thread src/server/utils.js Fixed
karlpauls and others added 2 commits November 12, 2025 20:48
@karlpauls @github-advanced-security
Potential fix for code scanning alert no. 52: Incomplete multi-charac…
6d3eeb4 
…ter sanitization

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
@karlpauls
Handle default metadata
c70eb0a
github-advanced-security[bot]
github-advanced-security AI found potential problems Nov 13, 2025
View reviewed changes
Comment thread src/server/utils.js Fixed
Comment thread src/server/utils.js Fixed
github-advanced-security[bot]
github-advanced-security AI found potential problems Nov 13, 2025
View reviewed changes
Comment thread src/server/utils.js Fixed
@karlpauls karlpauls merged commit 2186d4c into main Nov 13, 2025
9 checks passed
@karlpauls karlpauls deleted the plainhtml branch November 13, 2025 19:28
adobe-bot pushed a commit that referenced this pull request Nov 13, 2025
@semantic-release-bot
chore(release): 16.16.0 [skip ci]
1580918 
# [16.16.0](v16.15.13...v16.16.0) (2025-11-13)

### Features

* add .plain.html support for HTML folder serving ([#2631](#2631)) ([2186d4c](2186d4c))
@adobe-bot
Copy link
Copy Markdown
Collaborator

adobe-bot commented Nov 13, 2025

🎉 This PR is included in version 16.16.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

@catalan-adobe catalan-adobe mentioned this pull request Nov 13, 2025
Merged
@kptdobe kptdobe mentioned this pull request May 13, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tripodsan tripodsan tripodsan approved these changes

@trieloff trieloff Awaiting requested review from trieloff

Assignees

No one assigned

Labels

released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@karlpauls @trieloff @adobe-bot @tripodsan @github-advanced-security