fix(docs): prevent concurrent site output writes

Eleventy completion hooks could write into .11ty-vite/public while Vite
renamed dist into .11ty-vite, causing ENOTEMPTY build failures.

Run hooks sequentially so Vite completes before search, sitemap, and feed
writers publish to the final output directory. Sitemap and feed writers
use Eleventy's configured output directory.

Validation: site build and 14 sitemap/feed tests passed.
Signed-off-by: John Yanarella <jyanarella@nvidia.com>

Author: johnyanarella

projects/site/eleventy.config.js

@@ -93,6 +93,8 @@ const entrypoints = [
  * Sets up plugins, transforms, collections, and build options
  */
 export default function (eleventyConfig) {
+  // Vite must finish before the other output writers run.
+  eleventyConfig.setEventEmitterMode('sequential');
   eleventyConfig.pathPrefix = BASE_URL;
 
   // Add core 11ty plugins
@@ -166,9 +168,7 @@ export default function (eleventyConfig) {
 
   // Add search plugin for documentation search functionality
   if (process.env.ELEVENTY_RUN_MODE === 'build') {
-    eleventyConfig.addPlugin(searchPlugin, {
-      outputPath: './.11ty-vite/public/.pagefind'
-    });
+    eleventyConfig.addPlugin(searchPlugin);
   }
 
   // https://llmstxt.org

projects/site/src/_11ty/plugins/search.js

@@ -1,6 +1,7 @@
+import { join } from 'node:path';
 import * as pagefind from 'pagefind';
 
-export async function searchPlugin(eleventyConfig, pluginOptions) {
+export async function searchPlugin(eleventyConfig) {
   const { index } = await pagefind.createIndex();
 
   eleventyConfig.addTransform('search-index', async function (content) {
@@ -17,9 +18,9 @@ export async function searchPlugin(eleventyConfig, pluginOptions) {
     return content;
   });
 
-  eleventyConfig.on('eleventy.after', async () => {
+  eleventyConfig.on('eleventy.after', async ({ directories }) => {
     const { errors } = await index.writeFiles({
-      outputPath: pluginOptions.outputPath
+      outputPath: join(directories.output, '.pagefind')
     });
     if (errors.length > 0) {
       console.error('Pagefind errors', errors);

projects/site/src/_11ty/plugins/search.test.ts

@@ -0,0 +1,30 @@
+import { access, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { searchPlugin } from './search.js';
+
+describe('searchPlugin', () => {
+  let outputPath: string | undefined;
+
+  afterEach(async () => {
+    if (outputPath) await rm(outputPath, { force: true, recursive: true });
+  });
+
+  it('should publish the search index to the selected site output', async () => {
+    outputPath = await mkdtemp(join(tmpdir(), 'elements-search-'));
+    const on = vi.fn();
+    const addTransform = vi.fn();
+    await searchPlugin({ on, addTransform });
+    const transform = addTransform.mock.calls[0]?.[1];
+    const afterBuild = on.mock.calls.find(([event]) => event === 'eleventy.after')?.[1];
+
+    await transform.call(
+      { page: { url: '/docs/elements/tabs/', inputPath: 'tabs.html' } },
+      '<html lang="en"><body><h1>Tabs</h1><p>Tab composition</p></body></html>'
+    );
+    await afterBuild({ directories: { output: outputPath } });
+
+    await expect(access(join(outputPath, '.pagefind', 'pagefind.js'))).resolves.toBeUndefined();
+  });
+});

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

@@ -1,4 +1,5 @@
 import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
 import { getExplicitModifiedDate, normalizeContentDate } from '../utils/content-dates.js';
 import { getReleaseVideo } from '../utils/release-video.js';
 import { getSiteUrl } from '../utils/site-url.js';
@@ -107,8 +108,8 @@ export function renderSitemap(results = []) {
 }
 
 export function sitemapPlugin(eleventyConfig) {
-  eleventyConfig.on('eleventy.after', async ({ results } = {}) => {
-    await fsp.mkdir('./.11ty-vite/public/', { recursive: true });
-    await fsp.writeFile('./.11ty-vite/public/sitemap.xml', renderSitemap(results), 'utf-8');
+  eleventyConfig.on('eleventy.after', async ({ results, directories }) => {
+    await fsp.mkdir(directories.output, { recursive: true });
+    await fsp.writeFile(join(directories.output, 'sitemap.xml'), renderSitemap(results), 'utf-8');
   });
 }

projects/site/src/_11ty/plugins/sitemap-xml.test.ts

@@ -1,6 +1,9 @@
-import { describe, expect, it } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { lintRules } from '../../docs/lint/rules.js';
-import { isSitemapPageUrl, renderSitemap } from './sitemap-xml.js';
+import { isSitemapPageUrl, renderSitemap, sitemapPlugin } from './sitemap-xml.js';
 
 describe('isSitemapPageUrl', () => {
   it('should include crawlable html pages', () => {
@@ -105,3 +108,27 @@ describe('isSitemapPageUrl', () => {
     expect(sitemap.match(/<video:video>/g)).toHaveLength(1);
   });
 });
+
+describe('sitemapPlugin', () => {
+  let outputPath: string | undefined;
+
+  afterEach(async () => {
+    if (outputPath) await rm(outputPath, { force: true, recursive: true });
+  });
+
+  it('should publish the sitemap to the completed site output', async () => {
+    outputPath = await mkdtemp(join(tmpdir(), 'elements-sitemap-'));
+    const on = vi.fn();
+    sitemapPlugin({ on });
+    const afterBuild = on.mock.calls.find(([event]) => event === 'eleventy.after')?.[1];
+
+    await afterBuild({
+      directories: { output: outputPath },
+      results: [{ url: '/docs/elements/tabs/', content: '' }]
+    });
+
+    await expect(readFile(join(outputPath, 'sitemap.xml'), 'utf-8')).resolves.toContain(
+      '<loc>https://nvidia.github.io/elements/docs/elements/tabs/</loc>'
+    );
+  });
+});

projects/site/src/_11ty/plugins/updates-feed.js

@@ -4,7 +4,7 @@ import rssPlugin from '@11ty/eleventy-plugin-rss';
 import { getContentDates, normalizeContentDate } from '../utils/content-dates.js';
 import { ELEMENTS_SITE_ORIGIN } from '../utils/site-url.js';
 
-const DEFAULT_PUBLIC_OUTPUT_PATH = './.11ty-vite/public';
+const DEFAULT_PUBLIC_OUTPUT_PATH = './dist';
 
 export const UPDATES_COLLECTION = 'updates';
 export const RSS_UPDATES_COLLECTION = 'rssUpdates';
@@ -138,7 +138,7 @@ export function getAtomUpdatesCollection(collectionApi) {
   );
 }
 
-export function updatesFeedPlugin(eleventyConfig, { publicOutputPath = DEFAULT_PUBLIC_OUTPUT_PATH } = {}) {
+export function updatesFeedPlugin(eleventyConfig, { publicOutputPath } = {}) {
   eleventyConfig.addCollection(RSS_UPDATES_COLLECTION, getRssUpdatesCollection);
   eleventyConfig.addCollection(ATOM_UPDATES_COLLECTION, getAtomUpdatesCollection);
   eleventyConfig.addPlugin(rssPlugin);
@@ -152,5 +152,7 @@ export function updatesFeedPlugin(eleventyConfig, { publicOutputPath = DEFAULT_P
       permalink: feed.outputPath
     });
   }
-  eleventyConfig.on('eleventy.after', ({ results } = {}) => writeUpdateFeeds(results ?? [], publicOutputPath));
+  eleventyConfig.on('eleventy.after', ({ results, directories }) =>
+    writeUpdateFeeds(results ?? [], publicOutputPath ?? directories.output)
+  );
 }

projects/site/src/_11ty/plugins/updates-feed.test.ts

@@ -116,14 +116,15 @@ describe('updatesFeedPlugin', () => {
     );
   });
 
-  it('should publish generated feeds to the Vite public directory', async () => {
+  it('should publish generated feeds to the completed site output', async () => {
     publicOutputPath = await mkdtemp(join(tmpdir(), 'elements-updates-feed-'));
     const on = vi.fn();
     const atom = '<feed>updates</feed>';
-    updatesFeedPlugin({ addCollection: vi.fn(), addPlugin: vi.fn(), addTemplate: vi.fn(), on }, { publicOutputPath });
+    updatesFeedPlugin({ addCollection: vi.fn(), addPlugin: vi.fn(), addTemplate: vi.fn(), on });
     const afterBuild = on.mock.calls.find(([event]) => event === 'eleventy.after')?.[1];
 
     await afterBuild({
+      directories: { output: publicOutputPath },
       results: [
         { content: '<rss>updates</rss>', url: '/feed.xml' },
         { content: atom, url: '/atom.xml' },