feat: add printable checklists for SFC certifications by madjin · Pull Request #320 · security-alliance/frameworks

madjin · 2025-12-16T07:04:07Z

Summary

Adds a generator script that creates print-optimized HTML checklists from SFC certification MDX files
Adds a Print button to certification pages (next to Import/Export) that opens the printable version
3-column CSS layout with smart section chunking for optimal print layout

Features

Print Button: Each SFC cert page now has a Print button linking to /printable/{cert-name}.html
Print-Optimized HTML: Standalone pages with org/owner/date fields, checkboxes, and notes sections
Auto-Generated: Runs during build, outputs to docs/public/printable/

Files Changed

utils/generate-printable-checklists.js - New generator script
components/cert/CertList.tsx - Print button added
components/cert/control.css - Print button styling
package.json - Build script integration
.gitignore - Ignore generated files

Test plan

Run pnpm run docs:dev and verify Print button appears on cert pages
Click Print button and verify printable HTML loads
Test print/PDF export from browser
Run pnpm run docs:build and verify files in docs/dist/printable/

🤖 Generated with Claude Code

Preview

- New utils/generate-printable-checklists.js script that reads cert MDX files and generates print-optimized HTML checklists - 3-column CSS layout with smart section chunking (splits at midpoint if >6 controls) - Runs as postdocs:build hook, outputs to docs/dist/printable/ - Includes print button, org/owner/date fields, and notes area per section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add Print button to CertList component linking to printable HTML - Style print button to match existing Import/Export buttons - Fix output path to docs/public/printable/ for vocs compatibility - Move generate-printables before vocs build for production support - Add docs/public/printable/ to gitignore (generated files) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel · 2025-12-16T07:04:11Z

@madjin is attempting to deploy a commit to the Security Alliance Team on Vercel.

A member of the Team first needs to authorize it.

- Escape title/subtitle for XSS prevention - Sanitize certName for safe URL/filename use - Filter invalid control objects - Coerce text input to String in escapeHtml 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

smagdali · 2025-12-16T11:52:57Z

This is cool (and the output looks great), but why deploy as a separate doc and button, rather than a standard print style sheet that is used when someone chooses Print in the browser?

Generally, it's considered not-great-practice to replicate browser furniture.

Does it trigger if I hit cmd-p ?

(maybe it does - I couldn't see from my skim of the code - dismiss at will).

madjin · 2025-12-16T18:38:17Z

This is cool (and the output looks great), but why deploy as a separate doc and button, rather than a standard print style sheet that is used when someone chooses Print in the browser?

Generally, it's considered not-great-practice to replicate browser furniture.

Does it trigger if I hit cmd-p ?

(maybe it does - I couldn't see from my skim of the code - dismiss at will).

not replicating browser furniture on the main page, moreso providing a link to a purpose-built printable form with fields for Org/Owner/Date, dense layout. Can print via button or cmd/ctrl-p on the new page

smagdali · 2025-12-16T18:54:36Z

It's a nit, but (more) correct behaviour would be to deploy that style sheet if someone prints the main page. https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries/Printing
https://wblinks.com/notes/always-include-a-print-stylesheet/

Per reviewer feedback, adds @media print styles so cmd-p on main pages produces clean output: - Hides nav, sidebar, banner, footer, action buttons - Full-width content with print margins - White background, black text - Shows URLs after external links - Prevents awkward page breaks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

madjin · 2025-12-16T20:12:21Z

Added print stylesheet so now ctrl/cmd-p on main page produces cleaner output. It's ~4x more pages (single-column web layout) vs the dedicated printable which is optimized as a dense 3-column paper form.

Here's how modified stylesheet looks, 12 pages vs 7 pages (after):

The dense html form is 2 pages. Both options now work ^^

- Hide additional vocs chrome elements (gutterTop, curtains, search) - Hide cert interactive elements (progress bars, toggles, inputs) - Force sections to expand when printing - Clean control card styling with subtle separators - Prevent page breaks inside control cards - Reduce padding for better content density 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

DicksonWu654 · 2026-01-04T05:55:57Z

Hey @madjin super sorry for the delay! The printable version looks amazing! Thank you so much!

But I found 1 bug: if you have frameworks on darkmode, the printable versions are unreadable 😅

I'm gonna suggest some fixes in the pr review

DicksonWu654

The fixes to the black background for darkmode print

utils/generate-printable-checklists.js

docs/styles.css

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

This reverts commit af5379f.

…pplication

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Adds the first and most critical review suggestion that was missed: force color-scheme: light only !important on :root for print media. This ensures browsers render print preview in light mode regardless of user's system theme preference. Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

DicksonWu654

lgtm!

vercel · 2026-01-12T10:34:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
frameworks	Ready	Preview, Comment	Jan 12, 2026 10:36am

madjin · 2026-01-22T18:32:35Z

Security Review: PR #320 - Printable Checklists

Overview

Quick security review of the printable checklist generator for potential hardening.

Findings

1. Path Sanitization Gap (Medium)

File: utils/generate-printable-checklists.js:370

The sanitizeCertName() function exists and is used for URL generation, but not for the output file path:

const certName = file.replace('.mdx', '');  // unsanitized                                                                     
const outputPath = path.join(OUTPUT_DIR, `${certName}.html`);

Fix: Apply existing sanitizer to both uses:

const certName = sanitizeCertName(file.replace('.mdx', ''));

2. Input Validation (Low)

Control properties from YAML are escaped but not type-checked. Malformed frontmatter could cause unexpected behavior.

Optional hardening:

if (typeof c.title !== 'string') continue;

What's Already Good

HTML escaping applied to all user content via escapeHtml()
Input files filtered to sfc-*.mdx pattern
Output directory gitignored
Link uses rel="noopener noreferrer"

Recommendation

Apply the one-line path sanitization fix. Everything else is defense-in-depth and optional.

madjin · 2026-01-22T18:39:21Z

Option 2: Consider Separating from Dev Build

Currently generate-printables runs on every docs:dev. Consider:

"docs:dev": "... && vocs dev", // no printables
"docs:build": "... && pnpm run generate-printables && vocs build", // build-only

Why? Reduces attack surface during normal dev - the generator only executes when deploying. Devs can
still run pnpm run generate-printables manually when needed.

Can also make it a CI-only thing + manual command only for even more protection

- Apply sanitizeCertName() to output file path (not just URL) - Add type validation for control.title from YAML frontmatter - Move generate-printables from docs:dev to docs:build only Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

madjin · 2026-01-28T18:57:26Z

Implemented the security hardening suggestions:

Path sanitization - sanitizeCertName() now applied to output file path, with validation to skip malformed filenames
Input validation - Added typeof c.title === 'string' check for YAML control properties
Separated from dev - generate-printables removed from docs:dev, runs only on docs:build

Devs can still run pnpm run generate-printables manually when needed during local development.

madjin and others added 2 commits December 16, 2025 01:35

scode2277 requested review from DicksonWu654 and Robert-MacWha December 29, 2025 12:02

DicksonWu654 suggested changes Jan 4, 2026

View reviewed changes

madjin and others added 12 commits January 8, 2026 12:49

Addresses PR review feedback from @DicksonWu654 to fix dark mode

41b8734

Update utils/generate-printable-checklists.js

38762c1

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Update utils/generate-printable-checklists.js

780f005

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Update docs/styles.css

af5379f

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Update utils/generate-printable-checklists.js

ae9d08c

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Update utils/generate-printable-checklists.js

f8660df

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Update utils/generate-printable-checklists.js

666476f

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Revert "Update docs/styles.css"

c691036

This reverts commit af5379f.

reset: revert styles.css to pre-dark-fix state for clean suggestion a…

93bc075

…pplication

Update docs/styles.css

f130a0c

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

Update docs/styles.css

23c01cd

Co-authored-by: Dickson Wu <33645481+DicksonWu654@users.noreply.github.com>

DicksonWu654 self-requested a review January 9, 2026 05:07

DicksonWu654 approved these changes Jan 9, 2026

View reviewed changes

vercel bot deployed to Preview January 12, 2026 10:36 View deployment

scode2277 added the enhancement Updates that improve or refine existing features, user experience, or system performance. label Jan 12, 2026

fix: harden printable checklist generator

e831c3a

- Apply sanitizeCertName() to output file path (not just URL) - Add type validation for control.title from YAML frontmatter - Move generate-printables from docs:dev to docs:build only Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Conversation

madjin commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Files Changed

Test plan

Preview

Uh oh!

vercel bot commented Dec 16, 2025

Uh oh!

smagdali commented Dec 16, 2025

Uh oh!

madjin commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smagdali commented Dec 16, 2025

Uh oh!

madjin commented Dec 16, 2025

Uh oh!

DicksonWu654 commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DicksonWu654 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DicksonWu654 left a comment

Choose a reason for hiding this comment

Uh oh!

vercel bot commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

madjin commented Jan 22, 2026

Security Review: PR #320 - Printable Checklists

Overview

Findings

1. Path Sanitization Gap (Medium)

2. Input Validation (Low)

What's Already Good

Recommendation

Uh oh!

madjin commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Option 2: Consider Separating from Dev Build

Uh oh!

madjin commented Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

madjin commented Dec 16, 2025 •

edited

Loading

madjin commented Dec 16, 2025 •

edited

Loading

DicksonWu654 commented Jan 4, 2026 •

edited

Loading

vercel bot commented Jan 12, 2026 •

edited

Loading

madjin commented Jan 22, 2026 •

edited

Loading