fixup! resolve suggestions

src/generators/man-page/index.mjs

@@ -32,6 +32,10 @@ export default {
       ({ slug }) => slug === 'environment-variables-1'
     );
 
+    if (optionsStart + environmentStart <= 0) {
+      throw new Error('Could not find headers');
+    }
+
     // Generate the option mandoc
     let optionsOutput = '';
     for (let i = optionsStart + 1; i < environmentStart; i++) {

src/generators/man-page/template.1

@@ -1,3 +1,12 @@
+.\"
+.\" This file is automatically generated by api-docs-tooling.
+.\" Do not edit this file directly. Please make changes to CLI.md
+.\" and then regenerate this file.
+.\"
+.\" For generation instructions using api-docs-tooling, see:
+.\" https://github.com/nodejs/api-docs-tooling
+.\"
+.\"======================================================================
 .Dd $Mdocdate$
 .Dt NODE 1
 .

src/generators/man-page/utils/converter.mjs

@@ -75,7 +75,7 @@ export function flagValueToMandoc(flag) {
   // Split the flag into the name and value based on = or space delimiter.
   const value = flag.split(sep)[1];
   // Format the value using Ns and Ar macros for Mandoc, if present.
-  // If the seperator is ' ', it'll become '', hence the .trim().
+  // If the seperator is ' ', it'll become ''.
   return value
     ? `${sep === ' ' ? '' : ' Ns = Ns'} Ar ${value.replace(/\]$/, '')}`
     : '';
@@ -102,6 +102,7 @@ export function convertOptionToMandoc(element) {
 
   // Remove the header itself.
   element.content.children.shift();
+
   // Return the formatted flags and content, separated by Mandoc markers.
   return `.It ${formattedFlags.trim()}\n${convertNodeToMandoc(element.content)}\n.\n`;
 }
@@ -119,11 +120,13 @@ export function convertEnvVarToMandoc(element) {
   const [varName, varValue] = element.heading.data.text
     .replace(/`/g, '')
     .split('=');
+
   // Format the variable value if present.
   const formattedValue = varValue ? ` Ar ${varValue}` : '';
 
   // Remove the header itself.
   element.content.children.shift();
+
   // Return the formatted environment variable and content, using Mandoc's .It (List item) and .Ev (Env Var) macros.
   return `.It Ev ${varName}${formattedValue}\n${convertNodeToMandoc(element.content)}\n.\n`;
 }

src/generators/mandoc/index.mjs

@@ -0,0 +1,64 @@
+'use strict';
+
+import { optionToMandoc, envToMandoc } from './utils/converter.mjs';
+import { writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * This generator generates a mandoc version of the API docs
+ *
+ * @typedef {Array<ApiDocMetadataEntry>} Input
+ *
+ * @type {import('../types.d.ts').GeneratorMetadata<Input, string>}
+ */
+export default {
+  name: 'mandoc',
+
+  version: '1.0.0',
+
+  description: 'Generates the `node.1` file.',
+
+  dependsOn: 'ast',
+
+  async generate(input, options) {
+    // Find the appropriate headers
+    const optionsStart = input.findIndex(({ slug }) => slug === 'options');
+    const environmentStart = input.findIndex(
+      ({ slug }) => slug === 'environment-variables-1'
+    );
+
+    // If the headers are not found
+    if (optionsStart + environmentStart <= 0) {
+      throw new Error('Could not find headers');
+    }
+
+    // Generate the option mandoc
+    let optionsOutput = '';
+    for (let i = optionsStart + 1; i < environmentStart; i++) {
+      const el = input[i];
+      if (el.heading?.depth === 3) {
+        optionsOutput += optionToMandoc(el);
+      }
+    }
+
+    // Generate the environment mandoc
+    let envOutput = '';
+    for (let i = environmentStart + 1; i < input.length; i++) {
+      const el = input[i];
+      if (el.heading?.depth === 3) {
+        envOutput += envToMandoc(el);
+      }
+      if (el.heading?.depth < 3) break;
+    }
+
+    const apiTemplate = await readFile(
+      join(import.meta.dirname, 'template.1'),
+      'utf-8'
+    );
+    const template = apiTemplate
+      .replace('__OPTIONS__', optionsOutput)
+      .replace('__ENVIRONMENT__', envOutput);
+
+    return await writeFile(options.output, template);
+  },
+};