chore(docs): sitemap

projects/site/eleventy.config.js

@@ -4,7 +4,7 @@ import { EleventyRenderPlugin, IdAttributePlugin } from '@11ty/eleventy';
 import EleventyPluginVite from '@11ty/eleventy-plugin-vite';
 import litPlugin from '@lit-labs/eleventy-plugin-lit';
 
-import { BASE_URL } from './src/_11ty/layouts/common.js';
+import { BASE_URL } from './src/_11ty/layouts/metadata.js';
 import {
   ELEMENTS_PAGES_BASE_URL,
   ELEMENTS_REPO_BASE_URL,
@@ -16,6 +16,7 @@ import {
 } from './src/_11ty/utils/env.js';
 import { searchPlugin } from './src/_11ty/plugins/search.js';
 import { llmsTxtPlugin } from './src/_11ty/plugins/llms-txt.js';
+import { sitemapPlugin } from './src/_11ty/plugins/sitemap-xml.js';
 import { elementLoaderTransform } from './src/_11ty/transforms/element-loader.js';
 import { anchorGeneratorTransform } from './src/_11ty/transforms/anchor-generator.js';
 import { htmlMinifyTransform } from './src/_11ty/transforms/html-minify.js';
@@ -104,8 +105,6 @@ export default function (eleventyConfig) {
   eleventyConfig.addPassthroughCopy({ '../themes/dist/bundles': 'local-bundles/themes' });
   eleventyConfig.addPassthroughCopy({ '../styles/dist/bundles': 'local-bundles/styles' });
 
-  eleventyConfig.addPassthroughCopy('src/robots.txt');
-
   // Configure Lit SSR plugin for web components
   eleventyConfig.addPlugin(litPlugin, {
     mode: 'worker',
@@ -174,6 +173,11 @@ export default function (eleventyConfig) {
     eleventyConfig.addPlugin(llmsTxtPlugin);
   }
 
+  // https://www.sitemaps.org
+  if (process.env.ELEVENTY_RUN_MODE === 'build') {
+    eleventyConfig.addPlugin(sitemapPlugin);
+  }
+
   // Set custom markdown library
   eleventyConfig.setLibrary('md', markdown);
 

projects/site/package.json

@@ -63,6 +63,10 @@
         "PAGES_BASE_URL": {
           "external": true,
           "default": "/elements/"
+        },
+        "ELEMENTS_SITE_URL": {
+          "external": true,
+          "default": "https://nvidia.github.io"
         }
       }
     },

projects/site/public/robots.txt

@@ -1,2 +1,6 @@
 User-agent: *
-Disallow:
+Allow: /
+Disallow: /assets/
+Disallow: /.pagefind/
+
+Sitemap: https://nvidia.github.io/elements/sitemap.xml

projects/site/src/_11ty/layouts/common.js

@@ -1,29 +1,32 @@
 /* eslint-env node */
 /* global process */
 
-import { join } from 'node:path';
-import { ELEMENTS_PAGES_BASE_URL, ELEMENTS_PLAYGROUND_BASE_URL, ELEMENTS_REPO_BASE_URL } from '../utils/env.js';
-
-export const BASE_URL = join('/', process.env.PAGES_BASE_URL ?? '', '/');
+import { ELEMENTS_PLAYGROUND_BASE_URL, ELEMENTS_REPO_BASE_URL } from '../utils/env.js';
+import { escapeAttr, resolvePageMeta, renderJsonLd, BASE_URL } from './metadata.js';
 
 /**
  * This renders the base head element with all the common styles and scripts needed for ALL PAGES.
  * Page specific resources should not be placed here.
  */
-export const renderBaseHead = data => /* html */ `
+export const renderBaseHead = data => {
+  const meta = resolvePageMeta(data);
+  const ogType = meta.url === '/' ? 'website' : 'article';
+  return /* html */ `
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <meta name="robots" content="all">
   <base href="${BASE_URL}" />
-  <title data-pagefind-meta="title">${data.title}</title>
-  <meta name="description" content="Elements - ${data.title}">
-  <meta property="og:title" content="Elements - ${data.title}" >
-  <meta property="og:url" content="${data.page?.url ?? ''}">
-  <meta property="og:description" content="NVIDIA Elements is a flexible, framework-agnostic design system and toolkit that empowers teams to build exceptional user experiences.">
-  <meta property="og:image" content="/favicon.svg">
-  <meta property="og:site_name" content="${ELEMENTS_PAGES_BASE_URL}/">
-  <meta property="og:type" content="website">
+  <title data-pagefind-meta="title">${escapeAttr(meta.title)}</title>
+  <meta name="description" content="${escapeAttr(meta.description)}">
+  <link rel="canonical" href="${meta.canonicalUrl}">
+  <meta property="og:title" content="${escapeAttr(meta.title)}">
+  <meta property="og:url" content="${meta.canonicalUrl}">
+  <meta property="og:description" content="${escapeAttr(meta.description)}">
+  <meta property="og:image" content="${meta.ogImage}">
+  <meta property="og:site_name" content="NVIDIA Elements">
+  <meta property="og:type" content="${ogType}">
   <link rel="icon" href="/favicon.svg">
+  ${renderJsonLd(data, meta)}
   ${renderGlobalsScript(data)}
   <style>
     @import '@nvidia-elements/themes/fonts/inter.css';
@@ -99,6 +102,7 @@ export const renderBaseHead = data => /* html */ `
     globalThis.document.documentElement.removeAttribute('no-js');
   </script>
 `;
+};
 
 export const renderDocsNav = data => /* html */ `
 <nve-tree id="docs-nav" data-pagefind-ignore="all" behavior-expand selectable="single">

projects/site/src/_11ty/layouts/metadata.js

@@ -0,0 +1,133 @@
+import { join } from 'node:path';
+import { ELEMENTS_SITE_URL } from '../utils/env.js';
+import { siteData } from '../../index.11tydata.js';
+
+export const BASE_URL = join('/', process.env.PAGES_BASE_URL ?? '', '/');
+
+const SITE_ORIGIN = ELEMENTS_SITE_URL.replace(/\/$/, '');
+const PATH_PREFIX = BASE_URL.replace(/\/$/, '');
+
+const BREADCRUMB_TERMS = {
+  api: 'API',
+  cli: 'CLI',
+  mcp: 'MCP',
+  ssr: 'SSR',
+  i18n: 'i18n',
+  ui: 'UI',
+  nextjs: 'Next.js',
+  solidjs: 'SolidJS',
+  nuxt: 'Nuxt',
+  typescript: 'TypeScript',
+  go: 'Go',
+  vue: 'Vue',
+  react: 'React',
+  svelte: 'Svelte',
+  preact: 'Preact',
+  lit: 'Lit',
+  hugo: 'Hugo',
+  angular: 'Angular',
+  monaco: 'Monaco',
+  jsdoc: 'JSDoc',
+  json: 'JSON',
+  html: 'HTML',
+  css: 'CSS',
+  nvidia: 'NVIDIA',
+  npm: 'npm'
+};
+
+export function escapeAttr(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function titleCaseSegment(segment) {
+  if (BREADCRUMB_TERMS[segment]) return BREADCRUMB_TERMS[segment];
+  return segment
+    .split('-')
+    .map(part => BREADCRUMB_TERMS[part] ?? part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function findElementByTag(tag) {
+  if (!tag) return null;
+  return siteData.elements.find(e => e.name === tag) ?? null;
+}
+
+export function resolvePageMeta(data) {
+  const url = data.page?.url ?? '/';
+  const title = data.title ?? 'NVIDIA Elements';
+  const tag = data.tag ?? data.component?.data?.tag;
+  const element = findElementByTag(tag);
+  const componentDescription = element?.manifest?.description?.trim();
+
+  let description;
+  if (data.description) {
+    description = data.description;
+  } else if (data.isApiTab && componentDescription) {
+    description = `${componentDescription} — API reference for <${tag}>.`;
+  } else if (data.isExamplesTab && componentDescription) {
+    description = `${componentDescription} — Interactive examples for <${tag}>.`;
+  } else if (componentDescription) {
+    description = componentDescription;
+  } else {
+    description = `Documentation for ${title} in NVIDIA Elements, the framework-agnostic design system for AI/ML factories.`;
+  }
+
+  const canonicalUrl = `${SITE_ORIGIN}${PATH_PREFIX}${url}`;
+  const ogImage = `${SITE_ORIGIN}${PATH_PREFIX}/favicon.svg`;
+  return { title, description, canonicalUrl, ogImage, url };
+}
+
+function jsonLdEncode(value) {
+  return JSON.stringify(value).replace(/<\//g, '<\\/');
+}
+
+export function renderJsonLd(data, meta) {
+  const isDocs = meta.url.startsWith('/docs/');
+  const articleType = isDocs ? 'TechArticle' : 'WebPage';
+  const date = data.page?.date instanceof Date ? data.page.date.toISOString() : new Date().toISOString();
+
+  const article = {
+    '@context': 'https://schema.org',
+    '@type': articleType,
+    headline: meta.title,
+    description: meta.description,
+    url: meta.canonicalUrl,
+    mainEntityOfPage: meta.canonicalUrl,
+    inLanguage: 'en',
+    image: meta.ogImage,
+    datePublished: date,
+    dateModified: date,
+    publisher: { '@type': 'Organization', name: 'NVIDIA', url: SITE_ORIGIN },
+    author: { '@type': 'Organization', name: 'NVIDIA' }
+  };
+
+  const segments = meta.url.split('/').filter(Boolean);
+  const articleScript = `<script type="application/ld+json">${jsonLdEncode(article)}</script>`;
+  if (segments.length === 0) {
+    return articleScript;
+  }
+
+  const itemListElement = [{ '@type': 'ListItem', position: 1, name: 'Home', item: `${SITE_ORIGIN}${PATH_PREFIX}/` }];
+  let cumulative = '';
+  segments.forEach((seg, i) => {
+    cumulative += `/${seg}`;
+    itemListElement.push({
+      '@type': 'ListItem',
+      position: i + 2,
+      name: titleCaseSegment(seg),
+      item: `${SITE_ORIGIN}${PATH_PREFIX}${cumulative}/`
+    });
+  });
+
+  const breadcrumb = {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement
+  };
+  return `${articleScript}\n  <script type="application/ld+json">${jsonLdEncode(breadcrumb)}</script>`;
+}

projects/site/src/_11ty/plugins/sitemap-xml.js

@@ -0,0 +1,36 @@
+import { promises as fsp } from 'node:fs';
+import { BASE_URL } from '../layouts/metadata.js';
+import { ELEMENTS_SITE_URL } from '../utils/env.js';
+
+const SITE_ORIGIN = ELEMENTS_SITE_URL.replace(/\/$/, '');
+const PATH_PREFIX = BASE_URL.replace(/\/$/, '');
+const EXCLUDED_PREFIXES = ['/docs/changelog/', '/docs/metrics/', '/examples/', '/404'];
+
+function isPublishable(url) {
+  if (!url) return false;
+  if (!url.endsWith('/') && !url.endsWith('.html')) return false;
+  if (EXCLUDED_PREFIXES.some(prefix => url.startsWith(prefix))) return false;
+  return true;
+}
+
+export function sitemapPlugin(eleventyConfig) {
+  eleventyConfig.on('eleventy.after', async ({ results } = {}) => {
+    const urls = [...new Set((results ?? []).map(r => r.url).filter(isPublishable))].sort();
+    const lastmod = new Date().toISOString();
+    const entries = urls.map(url => {
+      const loc = `${SITE_ORIGIN}${PATH_PREFIX}${url}`;
+      return ['<url>', `<loc>${loc}</loc>`, `<lastmod>${lastmod}</lastmod>`, '</url>'].join('\n');
+    });
+
+    const xml = [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+      ...entries,
+      '</urlset>',
+      ''
+    ].join('\n');
+
+    await fsp.mkdir('./.11ty-vite/public/', { recursive: true });
+    await fsp.writeFile('./.11ty-vite/public/sitemap.xml', xml, 'utf-8');
+  });
+}

projects/site/src/_11ty/utils/env.js

@@ -8,3 +8,4 @@ export const ELEMENTS_REGISTRY_URL = process.env.ELEMENTS_REGISTRY_URL ?? '';
 export const ELEMENTS_ASSETS_CDN_BASE_URL = process.env.ELEMENTS_ASSETS_CDN_BASE_URL ?? '';
 export const ELEMENTS_ESM_CDN_BASE_URL = process.env.ELEMENTS_ESM_CDN_BASE_URL ?? '';
 export const ELEMENTS_CDN_BASE_URL = process.env.ELEMENTS_CDN_BASE_URL ?? '';
+export const ELEMENTS_SITE_URL = process.env.ELEMENTS_SITE_URL ?? 'https://nvidia.github.io';

projects/site/src/docs/elements/_tabs/examples.11ty.js

@@ -51,6 +51,7 @@ export async function render(data) {
   data.tag = componentData.tag;
   data.title = componentData.title;
   data.page.fileSlug = componentData.page.fileSlug;
+  data.isExamplesTab = true;
 
   return /* html */ `
     <style scoped>

projects/site/src/index.md

@@ -1,6 +1,7 @@
 ---
 {
   title: 'Getting Started',
+  description: 'Get started with NVIDIA Elements: install Web Components, themes, and starter templates for building framework-agnostic UI for AI/ML factories.',
   layout: 'docs.11ty.js'
 }
 ---