Refactor: Single source of truth for bookmarklet metadata #82
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Move bookmarklet metadata from data/bookmarklets.json into the source JS files as JSDoc-style comment blocks. The build process now: - Auto-discovers JS files in bookmarklets/ directory - Parses @bookmarklet, @description, @author, @authorUrl, @tags, @Auditing, and @PageTest metadata from JSDoc comments - Generates bookmarklets.json from extracted metadata - Continues with existing minification/encoding pipeline This eliminates the need to edit two files when adding or updating a bookmarklet. Metadata stays with code, reducing sync issues.
Add bookmarklets.11tydata.cjs that uses Eleventy computed data to derive layout, file, permalink, and title from HTML filenames. Remove frontmatter from all 22 test pages - they now contain only test content with no YAML required.
Add scripts/new-bookmarklet.js that generates JS and HTML files for new bookmarklets with proper metadata templates. Usage: npm run new -- --name "Name" --author "Author" --tags "tags"
Add comprehensive validation to build.js: - Orphan detection: JS files without @bookmarklet metadata fail the build - Test page validation: @PageTest true requires matching HTML file - Metadata completeness: warnings for missing optional fields - Helper file support: @Helper true excludes files from validation Add @PageTest self to grouped-fields.js, tool-aria-usage.js, tool-aria.js Add @Helper true to test-js-external.js (CSP test helper, not a bookmarklet)
Introduce a consistent tag taxonomy: - Category tags (required): accessibility, diagnostic, utility - Modifier tags (optional): external - WCAG tags (optional): wcag:X.X.X format Update all 42 bookmarklets with non-compliant tags to use the new format. Add tag validation to build.js that warns on invalid tags or missing category. Document the taxonomy in plan.md with examples.
Create comprehensive contributor documentation covering: - Quick start with scaffolding script - Manual setup instructions - Metadata field reference - Tag taxonomy (categories, modifiers, WCAG format) - Test page conventions (@PageTest values) - Build process and available commands - PR submission checklist
- Convert data file to ESM format (.mjs) for Eleventy 3.0 compatibility
- Update permalink to place test pages at root level (/{name}/)
- Change passthrough copy to only copy JS files, not HTML templates
Test page links now resolve correctly without the bookmarklets/ prefix.
jsnmrs
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This refactor moves bookmarklet metadata from separate JSON files into the source JS files as JSDoc-style comments. The build process now auto-discovers JS files and extracts metadata, eliminating the need to edit two files when adding or updating bookmarklets.
Key changes:
npm run new) for creating bookmarkletsTest plan
npm run buildto verify build completes without errorsnpm run new -- --name "Test" --tags "diagnostic"