W3C Offline HTML Validator

A Visual Studio Code extension that provides offline HTML validation using W3C standards. This extension integrates the W3C Nu HTML Checker directly into VSCode, allowing you to validate your HTML files without an internet connection. All necessary binaries are included in the package, ensuring seamless setup and operation.

Table of Contents

• Features
• Requirements
• Installation
• Usage
  • Automatic Validation on Save
  • Status Bar Integration
  • Enabling/Disabling Validation
• Extension Settings
• Known Issues
• Release Notes
• Contributing
• License

Features

• Offline HTML Validation: Validate your HTML files using W3C standards without needing an internet connection.
• Automatic Validation on Save: Automatically validates HTML files every time you save them.
• Real-time Validation State: Status bar updates immediately when code changes, showing current validation state.
• Status Bar Integration:
  • W3C Branded Status Bar: Displays "W3C" with clickable functionality to toggle validation.
  • Error and Warning Indicators:
    • Background Colors:
      • Red Background: Validation errors detected with error count.
      • Yellow Background: Validation warnings detected with warning count.
      • Green Background: Validation passed with no errors or warnings.
      • Gray Background: Validation is disabled.
    • Status Text:
      • "W3C": Validation enabled, not yet checked.
      • "W3C: X error(s)": Shows number of validation errors.
      • "W3C: X warning(s)": Shows number of validation warnings.
      • "W3C: OK": Validation passed successfully.
      • "W3C (Disabled)": Validation is disabled.
  • Quick Access to Problems Pane: When errors are present, clicking the status bar item opens the Problems pane.
• Error and Warning Diagnostics:
  • Validation errors and warnings are displayed in the Problems pane.
  • Errors and warnings are highlighted directly in the editor for easy identification.
• Cross-Platform Support: Works on Windows, macOS, and Linux with included binaries.
• Persistent Settings:
  • Validation state (enabled/disabled) is saved between sessions.
  • Configuration options are available for advanced users to customize the extension behavior.

Requirements

• Visual Studio Code version 1.93.0 or higher.
• Operating System: Windows, macOS, or Linux.
• No additional installations required: All necessary binaries are included.
• Apple Silicon Macs (M1/M2/M3/M4):
  • Rosetta 2 is required for the included Java runtime.
  • Important: Rosetta 2 is NOT automatically installed when the extension runs from terminal/command line. You must install it manually.
  • Manual Installation: Run this command in Terminal to install Rosetta 2:

    softwareupdate --install-rosetta --agree-to-license
    

  • For more information, see Apple's Rosetta 2 documentation.
  • The extension includes settings (OfflineW3cHTMLValidator.rosetta and OfflineW3cHTMLValidator.rosettaComplex) to help with Rosetta 2 detection and installation.

Installation

1. Install the Extension:

   • Search for "W3C Offline HTML Validator" in the VSCode Extensions Marketplace.
   • Click Install.

2. Reload VSCode:

   • After installation, reload VSCode to activate the extension.

Usage

Automatic Validation on Save

• The extension automatically validates any HTML file when you save it.
• If there are validation errors or warnings, they will appear in the Problems pane and be highlighted in the editor.

Enabling/Disabling Validation

• Toggle Validation:
  • Click the "W3C" status bar item to enable or disable validation.
• Persistent Setting:
  • The validation state is saved globally and persists across sessions.
• Real-time Updates:
  • Status bar updates immediately when you make changes to HTML files.
  • Validation state resets when code is modified, showing current status.

Extension Settings

The extension contributes the following settings:

1. OfflineW3cHTMLValidator.autoOpenProblems:

   • Type: boolean
   • Default: false
   • Description: Automatically open the Problems pane when validation errors are detected. Note: This will take focus away from the editor.

2. OfflineW3cHTMLValidator.noStream:

   • Type: boolean
   • Default: true
   • Description: VNU option: Forces all documents to be parsed in buffered mode instead of streaming mode (causes some parse errors to be treated as non-fatal document errors instead of as fatal document errors).

3. OfflineW3cHTMLValidator.noLangDetect:

   • Type: boolean
   • Default: true
   • Description: VNU option: Disables language detection, so that documents are not checked for missing or mislabeled html[lang] attributes.

4. OfflineW3cHTMLValidator.enableDebugLogging:

   • Type: boolean
   • Default: false
   • Description: Enable debug logging to the VSCode developer console.

5. OfflineW3cHTMLValidator.rosetta:

   • Type: boolean
   • Default: false
   • Description: Enable Rosetta 2 detection and installation. Required for Apple Silicon Macs (M1/M2/M3/M4) to run the included Java runtime.

6. OfflineW3cHTMLValidator.rosettaComplex:

   • Type: boolean
   • Default: false
   • Description: Enable complex Rosetta 2 detection and installation. Alternative detection method for Apple Silicon Macs.

7. OfflineW3cHTMLValidator.validateOnOpen:

   • Type: boolean
   • Default: false
   • Description: Validate HTML files when they are opened or when switching between documents.

Known Issues

• Auto-Dismiss Pop-up Messages:
  • The extension uses status bar messages instead of pop-up notifications to inform about validation results due to limitations in programmatically dismissing pop-ups.
• Focus Management:
  • The autoOpenProblems setting will take focus away from the editor when automatically opening the Problems pane. This is a VS Code limitation and cannot be avoided.
• Rosetta 2 Auto-Installation:
  • Rosetta 2 is not automatically installed when the extension runs from terminal/command line (which is how VS Code extensions execute processes). This differs from running GUI apps directly, where macOS prompts for Rosetta 2 installation.
  • Users must manually install Rosetta 2 using the terminal command: softwareupdate --install-rosetta --agree-to-license
• Performance on Large Files:
  • Validation may be slower for very large HTML files.

Release Notes

0.1.2

• Enhanced User Experience:
  • Animated Status Bar: Added smooth animation during validation process with braille spinner
  • Improved Path Handling: Fixed path escaping in vnu command arguments instead of in script wrapper
  • Better Error Handling: Enhanced error messages and validation state management
• New Configuration Options:
  • Debug Logging: Added OfflineW3cHTMLValidator.enableDebugLogging setting for troubleshooting
  • Rosetta Detection: Added OfflineW3cHTMLValidator.rosetta and OfflineW3cHTMLValidator.rosettaComplex settings for macOS Apple Silicon compatibility
  • Open Validation: Added OfflineW3cHTMLValidator.validateOnOpen setting to validate HTML files when opened or switching documents
• Settings Modernization:
  • Updated Configuration Namespace: Changed from offlineW3C to OfflineW3cHTMLValidator to fix VS Code settings display formatting
  • Fixed Settings Display: Resolved the "Offline W3 C: " spacing issue in VS Code settings UI
• Code Quality Improvements:
  • Improved code formatting and whitespace consistency
  • Enhanced error handling and validation state management
  • Better separation of concerns in validation logic

0.1.0

• Major UI/UX Overhaul:
  • New Interface: Complete redesign with improved W3C branding
  • Renamed Extension: Changed from "HTML Validator" to "W3C Offline HTML Validator"
  • New Icon: Updated extension icon for better visual identity
  • Enhanced Status Bar: Improved W3C branding with clearer status indicators and better error/warning count display
• Cross-Platform Fixes:
  • macOS Executable Permissions: Fixed vnu executable permissions on macOS
  • Path Handling: Improved handling of spaces in file paths for vnu, Java, and HTML documents across all platforms (Windows, macOS, Linux)
• Settings Modernization:
  • Configuration Rename: All settings now use offlineW3C prefix instead of htmlValidator
  • Simplified Settings: Removed unused settings and streamlined configuration options
  • Updated Defaults: More sensible default values for noStream and noLangDetect
• Code Quality Improvements:
  • Removed commented out code blocks and unused functions
  • Simplified argument building for vnu command using spread syntax
  • Improved error handling with cleaner error messages
  • Fixed linter issues and improved code organization

0.0.17

• Code Cleanup and Optimization:
  • Removed commented out code blocks and unused functions
  • Simplified argument building for vnu command using spread syntax
  • Improved error handling with cleaner error messages
  • Fixed linter issues and improved code organization
  • Removed debug console.log statements
  • Streamlined status bar logic
• Enhanced Status Bar:
  • Improved W3C branding with clearer status indicators
  • Better error and warning count display
  • Cleaner status bar text and tooltips
• Settings Simplification:
  • Removed unused settings (showErrorMessages, showWarningMessages, showOkMessages, vnuExecutable)
  • Updated default values for noStream and noLangDetect to true
  • Simplified configuration options

0.0.14

• Notifications:
  • Auto hide notifications

0.0.11 - 0.0.13

• UI/UX Improvements:
  • Added color-coded backgrounds to the status bar item to indicate validation status:
    • Green Background: Validation passed.
    • Red Background: Validation errors detected.
    • Gray Background: Validation is disabled.
  • Status bar item now provides quick access to the Problems pane when errors are present.
• Settings:
  • Introduced new settings to control notifications and behavior:
    • htmlValidator.showErrorMessages
    • htmlValidator.showWarningMessages
    • htmlValidator.showOkMessages
    • htmlValidator.autoOpenProblems
    • htmlValidator.noStream
    • htmlValidator.noLangDetect
• README.md:
  • Updated documentation to reflect new features and settings.

0.0.10

• Refactor

0.0.9

• Status Bar Item:
  • Added status bar integration for toggling validation.
  • Displays validation status and errors.
• Persistent Settings:
  • Validation state is stored globally and persists between sessions.

0.0.2 - 0.0.8

• Improvements

0.0.1

• Initial Release:
  • Basic offline HTML validation on save.
  • Inclusion of all necessary binaries for cross-platform support.

Contributing

Contributions are welcome! Please follow these steps:

0. Install VSCE:

   npm install -g @vscode/vsce
   

1. Fork the Repository:

   • Visit the GitHub repository and fork it.

2. Clone Your Fork:

   git clone https://github.com/your-username/w3c-offline-html-validator.git
   

3. Install Dependencies:

   cd w3c-offline-html-validator
   npm install
   

4. Development Workflow:

   • Use Node.js Version 22:

     nvm use 22
     

   • Compile the Extension:

     npm run compile
     

   • Package the Extension:

     npm run cp
     

     This command compiles the TypeScript code and creates a .vsix package file for local installation or distribution.
   • Publish the Extension:

     npm run cpp
     

     This command compiles, packages, and publishes the extension to the Visual Studio Code Marketplace.
   • Manual Packaging (Alternative):

     vsce package
     

   • Manual Publishing (Alternative):

     vsce publish
     

   • Run in Debug Mode:
     • Press F5 in VSCode to launch the extension in a new Extension Development Host window.

5. Available NPM Scripts:

   The project includes several convenient npm scripts for development and publishing:

   • npm run compile: Compiles TypeScript source code to JavaScript
   • npm run cp: Short for "compile and package" - compiles the code and creates a .vsix package file
   • npm run cpp: Short for "compile, package, and publish" - compiles, packages, and publishes to the marketplace
   • npm run lint: Runs ESLint to check code quality
   • npm test: Runs the test suite
   • npm run watch: Runs TypeScript compiler in watch mode for development

6. Submit a Pull Request:

   • Push your changes to your fork and submit a pull request to the main branch.

License

TODO

Contact

For questions, suggestions, or issues, please open an issue on the GitHub repository.

Additional Information

• Repository: https://github.com/fgmnts/w3c-offline-html-validator
• Publisher: fgmnts
• Category: Other

Acknowledgements

• W3C Nu HTML Checker: This extension utilizes the W3C Nu HTML Checker for validation.
• VSCode Extension API: Built using the Visual Studio Code Extension API.

Enjoy a seamless, offline HTML validation experience right within Visual Studio Code!