Open-source SEO, GEO, and marketing skills for AI agents.
docs(nextjs-blog): require safe article renderer (#111)
Tong Chen2481dc805265
diff --git a/notfair-nextjs-blog/README.md b/notfair-nextjs-blog/README.mdindex 47f4833c..19123a32 100644--- a/notfair-nextjs-blog/README.md+++ b/notfair-nextjs-blog/README.md@@ -7,10 +7,11 @@ pushed to your infrastructure.## Setup-1. Install the package:+1. Install the package and the server-side HTML sanitizer:```bash-npm install notfair-nextjs-blog+npm install notfair-nextjs-blog sanitize-html+npm install --save-dev @types/sanitize-html```2. In the NotFair SEO dashboard, create a **Next.js / headless**@@ -27,6 +28,110 @@ NOTFAIR_SEO_API_KEY=nfbl_...## Minimal app/blog+### Required safe article renderer++`content_html` is remote HTML. Do not render it directly or rely on browser+defaults for its typography: Tailwind's base reset removes heading hierarchy and+list markers unless the host site styles those elements explicitly. Keep the+presentation in the host app so it can match the existing blog design.++Create `src/lib/notfair-article.ts`:++```ts+import sanitizeHtml from "sanitize-html";++export function sanitizeNotFairArticleHtml(html: string) {+ return sanitizeHtml(html, {+ allowedTags: [+ ...sanitizeHtml.defaults.allowedTags,+ "figure", "figcaption", "h1", "h2", "h3", "h4", "img", "nav",+ "table", "thead", "tbody", "tr", "th", "td",+ ],+ allowedAttributes: {+ ...sanitizeHtml.defaults.allowedAttributes,+ a: ["href", "title", "target", "rel"],+ div: ["class"],+ h1: ["id"], h2: ["id"], h3: ["id"], h4: ["id"],+ img: ["src", "alt", "title", "width", "height", "loading"],+ li: ["class"],+ nav: ["aria-label", "class"],+ p: ["class"],+ },+ allowedClasses: {+ div: ["nf-tablewrap"],+ li: ["nf-toc-l2", "nf-toc-l3"],+ nav: ["nf-toc"],+ p: ["nf-attribution", "nf-toc-title"],+ },+ allowedSchemes: ["http", "https", "mailto"],+ allowedSchemesByTag: { img: ["https"] },+ transformTags: {+ a: sanitizeHtml.simpleTransform("a", { rel: "noopener noreferrer" }, true),+ },+ });+}+```++Create `app/blog/notfair-article.module.css`, then adapt the values to the+existing design system. Keep these selectors: they restore semantic hierarchy,+mobile table behavior, and NotFair's stable structural hooks.++```css+.articleContent { color: inherit; font-size: 1.0625rem; line-height: 1.75; }+.articleContent > * + * { margin-top: 1.25rem; }++.articleContent h1,+.articleContent h2,+.articleContent h3,+.articleContent h4 {+ font-weight: 600;+ letter-spacing: -0.01em;+ scroll-margin-top: 6rem;+}++.articleContent h2 { margin-top: 3rem; font-size: 1.5rem; line-height: 1.25; }+.articleContent h3 { margin-top: 2.25rem; font-size: 1.25rem; line-height: 1.35; }+.articleContent ul,+.articleContent ol { padding-left: 1.5rem; }+.articleContent ul { list-style: disc; }+.articleContent ol { list-style: decimal; }+.articleContent li + li { margin-top: 0.5rem; }+.articleContent a { color: var(--notfair-article-link, currentColor); text-decoration: underline; text-underline-offset: 0.2em; }+.articleContent blockquote { border-left: 3px solid var(--notfair-article-accent, currentColor); padding-left: 1rem; }++.articleContent :global(.nf-toc) {+ border: 1px solid var(--notfair-article-border, currentColor);+ border-radius: 0.5rem;+ padding: 1rem 1.25rem;+}+.articleContent :global(.nf-toc) ul { list-style: none; padding-left: 0; }+.articleContent :global(.nf-toc-l3) { padding-left: 1rem; }+.articleContent :global(.nf-toc-title) { font-weight: 600; }+.articleContent :global(.nf-tablewrap) { overflow-x: auto; }++.articleContent table { width: 100%; border-collapse: collapse; }+.articleContent th,+.articleContent td {+ border: 1px solid var(--notfair-article-border, currentColor);+ min-width: 11rem;+ padding: 0.75rem 1rem;+ text-align: left;+ vertical-align: top;+}+.articleContent :global(.nf-attribution) { font-size: 0.875rem; opacity: 0.75; }+```++The `nf-*` classes are a small, stable semantic contract:++- `nf-toc`, `nf-toc-title`, `nf-toc-l2`, and `nf-toc-l3` describe the table of contents.+- `nf-tablewrap` enables horizontal scrolling for wide tables on mobile.+- `nf-attribution` identifies the disclosure line.++Do not let the content generator emit your app's Tailwind utility classes. Use+the scoped CSS module above, or adapt the same selectors to the site's existing+article renderer. Tailwind Typography is optional only when it is already part+of the host application's design system.+`app/blog/page.tsx`:```tsx@@ -53,6 +158,8 @@ export default async function BlogIndex() {```tsximport { notFound } from "next/navigation";import { getSeoPost } from "notfair-nextjs-blog";+import { sanitizeNotFairArticleHtml } from "@/lib/notfair-article";+import styles from "../notfair-article.module.css";export default async function BlogPost({params,@@ -65,7 +172,12 @@ export default async function BlogPost({return (<article><h1>{post.title}</h1>- <div dangerouslySetInnerHTML={{ __html: post.content_html }} />+ <div+ className={styles.articleContent}+ dangerouslySetInnerHTML={{+ __html: sanitizeNotFairArticleHtml(post.content_html),+ }}+ /></article>);}@@ -111,7 +223,12 @@ if (result.source === "existing") {return (<article><h1>{result.post.title}</h1>- <div dangerouslySetInnerHTML={{ __html: result.post.content_html }} />+ <div+ className={styles.articleContent}+ dangerouslySetInnerHTML={{+ __html: sanitizeNotFairArticleHtml(result.post.content_html),+ }}+ /></article>);```@@ -119,6 +236,14 @@ return (Apply the same native-first lookup in `generateMetadata`. Do not call`notFound()` until both sources return no post.+## Verify before marking setup complete++Deploy a real NotFair post and check both desktop and mobile. Confirm the+featured image loads, headings are visually distinct, list markers are visible,+wide tables scroll horizontally, table-of-contents links jump to their+headings, and the attribution remains visible. Published pages must be publicly+reachable at the configured `/blog/{slug}` URL for link verification.+## API- `getSeoPosts({ revalidate? })` → `[{ id, title, slug, published_at, created_at }]`diff --git a/notfair-nextjs-blog/package.json b/notfair-nextjs-blog/package.jsonindex f6e63ecc..641e92ce 100644--- a/notfair-nextjs-blog/package.json+++ b/notfair-nextjs-blog/package.json@@ -1,6 +1,6 @@{"name": "notfair-nextjs-blog",- "version": "0.3.0",+ "version": "0.3.1","description": "Render your NotFair SEO exchange posts on a Next.js blog — server-side content pulls with your private site API key.","license": "MIT","type": "module",diff --git a/notfair-nextjs-blog/test/readme.test.mjs b/notfair-nextjs-blog/test/readme.test.mjsnew file mode 100644index 00000000..89195035--- /dev/null+++ b/notfair-nextjs-blog/test/readme.test.mjs@@ -0,0 +1,20 @@+import assert from "node:assert/strict";+import { readFile } from "node:fs/promises";+import { fileURLToPath } from "node:url";++import test from "node:test";++const readme = await readFile(+ fileURLToPath(new URL("../README.md", import.meta.url)),+ "utf8",+);++test("README requires sanitized, scoped NotFair article rendering", () => {+ assert.match(readme, /sanitizeNotFairArticleHtml/);+ assert.match(readme, /notfair-article\.module\.css/);+ assert.match(readme, /:global\(\.nf-toc\)/);+ assert.match(readme, /:global\(\.nf-tablewrap\)/);+ assert.match(readme, /list-style: disc/);+ assert.match(readme, /from "\.\.\/notfair-article\.module\.css"/);+ assert.doesNotMatch(readme, /dangerouslySetInnerHTML=\{\{ __html: post\.content_html \}\}/);+});