html-proofer-mailto_awesome
An html-proofer check that requires mailto: links to carry the header fields you want every message to start with.
What an awesome mailto link is
People send email we did not ask for. A bare mailto: link opens a blank message, and the sender fills that blank with whatever is on their mind. Prefilling the subject and the body makes the useful message the path of least resistance. Replacing it takes effort.
This is a not-awesome link:
<a href="mailto:support@pacificmedicaltraining.com">Email us</a>This is an awesome link. The subject and the body are already there:
<a
href="mailto:support@pacificmedicaltraining.com?subject=Signing%20up&body=Hello%2C%0AI%20would%20like%20to%20sign%20up."
>
Email us
</a>RFC 6068 is the mailto: URI scheme. In HTML, write & for an ampersand inside the attribute. Header field names are case-insensitive. Subject and subject are the same field.
The same rule is published for HTML-validate as nice-checkers/mailto-awesome.
Installation
This gem runs on the Ruby branches that are still in normal or security maintenance: 3.3, 3.4, and 4.0. The list is Ruby maintenance branches. Install one of those Rubies from that page.
Add the gem to the application that builds or checks the site:
gem "html-proofer-mailto_awesome"Then install:
bundle installUsage
html-proofer runs only the checks named in checks. That option replaces the default list, which is Links, Images, and Scripts. Include those names when you still want them, and add MailtoAwesome.
Require this gem before run. html-proofer discovers the check by looking at classes that are already loaded.
require "html-proofer"
require "html-proofer-mailto_awesome"
desc "Check the built site"
task :test do
HTMLProofer.check_directory("_site", {
checks: ["Links", "Images", "Scripts", "MailtoAwesome"],
}).run
end
task default: :testRun it with Bundler so the gem is on the load path:
bundle exec rakeMailtoAwesome looks at a elements. A mailto: link passes when every required header field is present. The default required fields are subject and body. An empty value still counts as present (subject=). Text in the address, such as mailto:subject=trick@example.com, is not a header field. Spaces and ASCII control characters at either end of the attribute are ignored. URL parsing removes those characters before it reads the scheme, so a padded mailto:support@example.com is still checked.
A link that omits a field fails with mailto: link is missing required parameters: subject, body. A mailto: value that Ruby cannot parse as a URI fails with mailto: link is malformed and could not be parsed.
data-proofer-ignore skips the link, as it does for the other html-proofer checks.
Configuration
mailto_awesome.required_parameters replaces the default list. This matches the HTML-validate rule, which uses requiredParameters for the same purpose. Pass an empty array when you want the check loaded and no fields required.
HTMLProofer.check_directory("_site", {
checks: ["Links", "Images", "Scripts", "MailtoAwesome"],
mailto_awesome: {
required_parameters: ["subject", "body"],
},
}).runDevelopment
Clone the repository and install the gems it uses to test itself:
git clone https://github.com/fulldecent/html-proofer-mailto_awesome.git
cd html-proofer-mailto_awesome
bundle install
bundle exec rakeFormat the files the lint workflow checks. These commands call @latest on purpose. A pinned copy would let your machine rewrite files one way and continuous integration reject them another way. node.js-template records that constraint on its format script.
npx prettier@latest --write .
npx markdownlint-cli@latest --fix "**/*.md" --ignore node_modules*.md is in .prettierignore. Prettier does not wrap Markdown. markdownlint does, and .markdownlint.json turns off the line-length rule.
Releasing
Use fix:, feat:, or BREAKING CHANGE: in commit messages on main. A commit whose message starts with fix: opens or updates a release pull request that bumps the patch version. feat: bumps the minor version. BREAKING CHANGE: bumps the major version. One release pull request collects every such commit since the last release. A commit with any other prefix, including chore: and docs:, does not open that pull request.
The release workflow uses release-please with the Ruby strategy. The configuration is release-please-config.json. .release-please-manifest.json is the last released version, which is 2.1.0. Merging the release pull request is the release. That pull request sets the version in lib/html/proofer/mailto_awesome/version.rb and in the path spec in Gemfile.lock, and it writes CHANGELOG.md.
The publish job then runs the same Ruby matrix as .github/workflows/ruby.yml. After those tests pass, it tags v1.2.3, pushes that tag, and pushes the gem. The tag is the version Bundler's rake release task writes. Release Please reads tags of that shape. The older tag 2.0.0 has no v, so it is not a Release Please version. bootstrap-sha in the config is commit b4c37c1, the commit already published as 2.1.0. The next release is made of commits after that SHA.
The release pull request is opened with the workflow token. GitHub does not start .github/workflows/ruby.yml on a pull request opened that way. The publish job's test run is the one that gates the gem.
RubyGems.org still requires MFA for this gem (rubygems_mfa_required). Publishing from GitHub Actions follows RubyGems trusted publishing. The gem's trusted publisher names the workflow file release.yml and leaves the environment empty. GitHub's OIDC token is exchanged for a short-lived RubyGems credential. No RubyGems API key is stored in this repository.
Before the first automated publish, create that trusted publisher. On the gem page, open Trusted publishers and create one with owner fulldecent, repository html-proofer-mailto_awesome, and workflow filename release.yml. Leave the environment empty. In the GitHub repository settings, under Actions, General, Workflow permissions, select read and write permissions and check "Allow GitHub Actions to create and approve pull requests". This repository already has those two settings.
Maintenance
Do this every month or so:
- Read Ruby maintenance branches. Update
required_ruby_versionand the Ruby matrix in.github/workflows/ruby.ymlwhen a branch leaves security maintenance, or when a new branch enters normal maintenance. - Review external actions in
.github/workflows. GitHub-supported actions, the ones under theactions/organization, need a short review.ruby/setup-ruby,googleapis/release-please-action, andrubygems/release-gemare not in that organization. Read their changelogs before moving the tag. - Review
html-prooferagainst the 5.x releases. This gem depends on~> 5.0,>= 5.0.4. It also depends onlogger, because Ruby 4.0 removed that library from the default gems and html-proofer still loads it. - Keep
ffiat 1.17.4 or newer, andnokogiriat 1.19.0 or newer, inGemfile.lock. The x86_64-linux builds of ffi 1.17.2 and nokogiri 1.18.10 setrequired_ruby_versionto< 3.5.dev, sobundle installfails on Ruby 4.0. ffi 1.17.4 and nokogiri 1.19.4 allow Ruby before 4.1. ethon pulls in ffi. html-proofer pulls in nokogiri.
References
- We use title case for titles and proper nouns; not for headings and things. This includes our README above as well as our workflow rules and other configuration files. If you have a different policy, then please implement it throughout.
- This project is released under the MIT license.
- This project is built based on best practices documented in node.js-template. We took its lint workflow (Prettier and markdownlint, both invoked as
npx @latest),.editorconfig,.markdownlint.json,.prettierignore, and this references section. We did not take its Yarn install or its.node-versionpin. This is a Ruby gem. The lint job uses Node only as the tool runtime for those two checkers. - The check follows
nice-checkers/mailto-awesomein @fulldecent/nice-checkers-plugin: default required fields aresubjectandbody, and the caller can replace that list. Delta: this gem compares header field names case-insensitively because RFC 6068 section 2 says<hfname>is case-insensitive. The HTML-validate rule usesURLSearchParams, which compares names case-sensitively. - html-proofer custom checks are loaded by class name and selected with the
checksoption. Passingchecksreplaces the default list. That behavior is documented in the html-proofer README. - Ruby versions in the gemspec and in continuous integration are the branches still in normal or security maintenance, from Ruby maintenance branches. Ruby 4.0 does not ship
loggeras a default gem. This gem depends on theloggergem so html-proofer can load on that Ruby. - Releases follow release-please in manifest mode, with the Ruby strategy. Commit messages follow Conventional Commits 1.0.0. The release pull request is the review gate. semantic-release commits onto the default branch and assumes Node. Publishing the gem follows RubyGems trusted publishing and
rubygems/release-gem. The trusted publisher namesrelease.ymland leaves the environment empty.rake releasecreates thev1.2.3tag after the tests pass, because a tag created earlier would exist while the tests can still fail. A tag created byGITHUB_TOKENdoes not start another workflow (GitHub docs), so the publish job is in this same workflow. The shape of the workflow follows php-template's release workflow: Release Please opens the pull request, and the publish job creates the tag. Delta: this job pushes a gem with trusted publishing, and the version lives inversion.rbbecause the Ruby strategy updates that file. php-template takes the version from the tag alone.