@raven-js/glean/lib/server/templates/sitemap.js

Glean documentation gold from your codebase - JSDoc parsing, validation, and beautiful doc generation

/**
 * @author Anonyfox <max@anonyfox.com>
 * @license MIT
 * @see {@link https://github.com/Anonyfox/ravenjs}
 * @see {@link https://ravenjs.dev}
 * @see {@link https://anonyfox.com}
 */

/**
 * @file XML sitemap template for documentation generator
 *
 * Generates standards-compliant XML sitemap for search engine optimization.
 * Follows the sitemaps.org protocol with proper XML formatting.
 */

/**
 * Generate XML sitemap from sitemap data following sitemaps.org protocol.
 *
 * @param {Object} data - Sitemap data with URLs and metadata
 * @param {Array<{loc: string, lastmod: string, changefreq: string, priority: string}>} data.urls - Array of URL objects with loc, lastmod, changefreq, priority
 * @param {number} data.totalUrls - Total number of URLs in sitemap
 * @param {string} data.generatedAt - ISO timestamp of generation
 * @returns {string} Complete XML sitemap
 *
 * @example
 * // Basic sitemap generation
 * sitemapTemplate({
 *   urls: [{ loc: 'https://example.com/', lastmod: '2023-01-01', changefreq: 'weekly', priority: '1.0' }],
 *   totalUrls: 1,
 *   generatedAt: '2023-01-01T00:00:00.000Z'
 * });
 */
export function sitemapTemplate(data) {
	const { urls, totalUrls, generatedAt } = data;

	const urlEntries = urls
		.map(
			(url) => `  <url>
    <loc>${escapeXml(url.loc)}</loc>
    <lastmod>${url.lastmod}</lastmod>
    <changefreq>${url.changefreq}</changefreq>
    <priority>${url.priority}</priority>
  </url>`,
		)
		.join("\n");

	return `<?xml version="1.0" encoding="UTF-8"?>
<!-- Generated by RavenJS Documentation Generator -->
<!-- Total URLs: ${totalUrls} | Generated: ${generatedAt} -->
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urlEntries}
</urlset>`;
}

/**
 * Escape XML special characters in URLs
 * @param {string} str - String to escape
 * @returns {string} XML-escaped string
 */
function escapeXml(str) {
	return str
		.replace(/&/g, "&amp;")
		.replace(/</g, "&lt;")
		.replace(/>/g, "&gt;")
		.replace(/"/g, "&quot;")
		.replace(/'/g, "&apos;");
}