feat: create sitemap generator (#520)

Author: araujogui

src/generators/index.mjs

@@ -14,6 +14,7 @@ import llmsTxt from './llms-txt/index.mjs';
 import manPage from './man-page/index.mjs';
 import metadata from './metadata/index.mjs';
 import oramaDb from './orama-db/index.mjs';
+import sitemap from './sitemap/index.mjs';
 import web from './web/index.mjs';
 
 export const publicGenerators = {
@@ -27,6 +28,7 @@ export const publicGenerators = {
   'api-links': apiLinks,
   'orama-db': oramaDb,
   'llms-txt': llmsTxt,
+  sitemap,
   web,
 };
 

src/generators/llms-txt/utils/buildApiDocLink.mjs

@@ -1,5 +1,5 @@
-import { BASE_URL } from '../../../constants.mjs';
 import { transformNodeToString } from '../../../utils/unist.mjs';
+import { buildApiDocURL } from '../../../utils/url.mjs';
 
 /**
  * Retrieves the description of a given API doc entry. It first checks whether
@@ -38,8 +38,7 @@ export const getEntryDescription = entry => {
 export const buildApiDocLink = entry => {
   const title = entry.heading.data.name;
 
-  const path = entry.api_doc_source.replace(/^doc\//, '/docs/latest/');
-  const url = new URL(path, BASE_URL);
+  const url = buildApiDocURL(entry);
 
   const link = `[${title}](${url})`;
 

src/generators/sitemap/entry-template.xml

@@ -0,0 +1,6 @@
+<url>
+  <loc>__LOC__</loc>
+  <lastmod>__LASTMOD__</lastmod>
+  <changefreq>__CHANGEFREQ__</changefreq>
+  <priority>__PRIORITY__</priority>
+</url>

src/generators/sitemap/index.mjs

@@ -0,0 +1,79 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { BASE_URL } from '../../constants.mjs';
+import { createPageSitemapEntry } from './utils/createPageSitemapEntry.mjs';
+
+/**
+ * This generator generates a sitemap.xml file for search engine optimization
+ *
+ * @typedef {Array<ApiDocMetadataEntry>} Input
+ *
+ * @type {GeneratorMetadata<Input, string>}
+ */
+export default {
+  name: 'sitemap',
+
+  version: '1.0.0',
+
+  description: 'Generates a sitemap.xml file for search engine optimization',
+
+  dependsOn: 'metadata',
+
+  /**
+   * Generates a sitemap.xml file
+   *
+   * @param {Input} entries
+   * @param {Partial<GeneratorOptions>} options
+   * @returns {Promise<string>}
+   */
+  async generate(entries, { output }) {
+    const template = await readFile(
+      join(import.meta.dirname, 'template.xml'),
+      'utf-8'
+    );
+
+    const entryTemplate = await readFile(
+      join(import.meta.dirname, 'entry-template.xml'),
+      'utf-8'
+    );
+
+    const lastmod = new Date().toISOString().split('T')[0];
+
+    const apiPages = entries
+      .filter(entry => entry.heading.depth === 1)
+      .map(entry => createPageSitemapEntry(entry, lastmod));
+
+    const { href: loc } = new URL('/docs/latest/api/', BASE_URL);
+
+    /**
+     * @typedef {import('./types').SitemapEntry}
+     */
+    const mainPage = {
+      loc,
+      lastmod,
+      changefreq: 'daily',
+      priority: '1.0',
+    };
+
+    apiPages.push(mainPage);
+
+    const urlset = apiPages
+      .map(page =>
+        entryTemplate
+          .replace('__LOC__', page.loc)
+          .replace('__LASTMOD__', page.lastmod)
+          .replace('__CHANGEFREQ__', page.changefreq)
+          .replace('__PRIORITY__', page.priority)
+      )
+      .join('');
+
+    const sitemap = template.replace('__URLSET__', urlset);
+
+    if (output) {
+      await writeFile(join(output, 'sitemap.xml'), sitemap, 'utf-8');
+    }
+
+    return sitemap;
+  },
+};

src/generators/sitemap/template.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+__URLSET__
+</urlset>

src/generators/sitemap/types.d.ts

@@ -0,0 +1,13 @@
+export interface SitemapEntry {
+  loc: string;
+  lastmod?: string;
+  changefreq?:
+    | 'always'
+    | 'hourly'
+    | 'daily'
+    | 'weekly'
+    | 'monthly'
+    | 'yearly'
+    | 'never';
+  priority?: string;
+}

src/generators/sitemap/utils/createPageSitemapEntry.mjs

@@ -0,0 +1,14 @@
+import { buildApiDocURL } from '../../../utils/url.mjs';
+
+/**
+ * Builds an API doc sitemap url.
+ *
+ * @param {ApiDocMetadataEntry} entry
+ * @param {string} lastmod
+ * @returns {import('../types').SitemapEntry}
+ */
+export const createPageSitemapEntry = (entry, lastmod) => {
+  const { href } = buildApiDocURL(entry, true);
+
+  return { loc: href, lastmod, changefreq: 'weekly', priority: '0.8' };
+};

src/utils/__tests__/url.test.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { buildApiDocURL } from '../url.mjs';
+
+const BASE = 'https://nodejs.org/';
+
+describe('buildApiDocURL', () => {
+  it('builds markdown doc URLs from doc/ sources', () => {
+    const entry = { api_doc_source: 'doc/api/fs.md' };
+
+    const result = buildApiDocURL(entry);
+
+    assert.equal(result.href, `${BASE}docs/latest/api/fs.md`);
+  });
+
+  it('builds html doc URLs when requested', () => {
+    const entry = { api_doc_source: 'doc/api/path.md' };
+
+    const result = buildApiDocURL(entry, true);
+
+    assert.equal(result.href, `${BASE}docs/latest/api/path.html`);
+  });
+
+  it('leaves non doc/ sources untouched', () => {
+    const entry = { api_doc_source: 'api/crypto.md' };
+
+    const result = buildApiDocURL(entry);
+
+    assert.equal(result.href, `${BASE}api/crypto.md`);
+  });
+});

src/utils/url.mjs

@@ -0,0 +1,18 @@
+import { BASE_URL } from '../constants.mjs';
+
+/**
+ * Builds the url of a api doc entry.
+ *
+ * @param {ApiDocMetadataEntry} entry
+ * @param {boolean} [useHtml]
+ * @returns {URL}
+ */
+export const buildApiDocURL = (entry, useHtml = false) => {
+  const path = entry.api_doc_source.replace(/^doc\//, '/docs/latest/');
+
+  if (useHtml) {
+    return URL.parse(path.replace(/\.md$/, '.html'), BASE_URL);
+  }
+
+  return URL.parse(path, BASE_URL);
+};