chore: updated metadata parsing

Author: ovflowd

src/generators/json-simple/index.mjs

@@ -38,9 +38,12 @@ export default {
       // Deep clones the content nodes to avoid affecting upstream nodes
       const content = JSON.parse(JSON.stringify(node.content));
 
-      // Removes all the Stability Index nodes, since they shouldn't be included in the final JSON
-      // and are already represented in the metadata (metadata.stability.toJSON)
-      remove(content, [createQueries.UNIST.isStabilityNode]);
+      // Removes numerous nodes from the content that should not be on the "body"
+      // of the JSON version of the API docs as they are already represented in the metadata
+      remove(content, [
+        createQueries.UNIST.isStabilityNode,
+        createQueries.UNIST.isHeading,
+      ]);
 
       // For the JSON generate we want to transform the whole content into JSON
       content.toJSON = () => remarkProcessor.stringify(content);

src/metadata.mjs

@@ -69,15 +69,19 @@ const createMetadata = slugger => {
      * @param {HeadingMetadataParent} heading The new heading metadata
      */
     setHeading: heading => {
-      internalMetadata.heading = heading;
+      // We clone the heading to ensure that we don't accidentally override it
+      // with later mutations below on the `.create` method
+      internalMetadata.heading = { ...heading };
     },
     /**
      * Set the Stability Index of a given Metadata
      *
      * @param {StabilityIndexParent} stability The stability index node to be added
      */
     addStability: stability => {
-      internalMetadata.stability.children.push(stability);
+      // We clone the stability to ensure that we don't accidentally override it
+      // with later mutations below on the `.create` method
+      internalMetadata.stability.children.push({ ...stability });
     },
     /**
      * Set the Metadata (from YAML if exists) properties to the current Metadata entry
@@ -132,7 +136,7 @@ const createMetadata = slugger => {
       // a certain navigation section to a page ad the exact point of the page (scroll)
       // This is useful for classes, globals and other type of YAML entries, as they reside
       // within a module (page) and we want to link to them directly
-      const slugHash = `#${slugger.slug(internalMetadata.heading.text)}`;
+      const sectionSlug = slugger.slug(internalMetadata.heading.data.text);
 
       const {
         source_link: sourceLink,
@@ -141,6 +145,9 @@ const createMetadata = slugger => {
         tags = [],
       } = internalMetadata.properties;
 
+      // Also add the slug to the heading data as it is used to build the heading
+      internalMetadata.heading.data.slug = sectionSlug;
+
       // Defines the toJSON method for the Heading AST node to be converted as JSON
       internalMetadata.heading.toJSON = () => internalMetadata.heading.data;
 
@@ -153,7 +160,7 @@ const createMetadata = slugger => {
         // The API file basename (without the extension)
         api: apiDoc.stem,
         // The path/slug of the API section
-        slug: `${apiDoc.stem}.html${slugHash}`,
+        slug: sectionSlug,
         // The source link of said API section
         sourceLink: sourceLink,
         // The latest updates to an API section

src/parser.mjs

@@ -64,6 +64,9 @@ const createParser = () => {
     // Get all Markdown Footnote definitions from the tree
     const markdownDefinitions = selectAll('definition', apiDocTree);
 
+    // Get all Markdown Heading entries from the tree
+    const headingNodes = selectAll('heading', apiDocTree);
+
     // Handles Markdown link references and updates them to be plain links
     visit(apiDocTree, createQueries.UNIST.isLinkReference, node =>
       updateLinkReference(node, markdownDefinitions)
@@ -79,6 +82,12 @@ const createParser = () => {
       updateMarkdownLink(node)
     );
 
+    // If the document has no headings but it has content, we add a fake heading to the top
+    // so that our parsing logic can work correctly, and generate content for the whole file
+    if (headingNodes.length === 0 && apiDocTree.children.length > 0) {
+      apiDocTree.children.unshift(createTree('heading', { depth: 1 }, []));
+    }
+
     // Handles iterating the tree and creating subtrees for each API doc entry
     // where an API doc entry is defined by a Heading Node
     // (so all elements after a Heading until the next Heading)
@@ -113,7 +122,7 @@ const createParser = () => {
       // `index + 1` is used to skip the current Heading Node
       const subTree = createTree(
         'root',
-        apiDocTree.children.slice(index + 1, stop)
+        apiDocTree.children.slice(index, stop)
       );
 
       // Visits all Stability Index nodes from the current subtree if there's any

src/types.d.ts

@@ -1,4 +1,4 @@
-import type { Root } from 'mdast';
+import type { Heading, Root } from 'mdast';
 import type { SemVer } from 'semver';
 import type { Parent, Node, Data } from 'unist';
 
@@ -20,7 +20,7 @@ declare global {
   }
 
   export interface StabilityIndexParent extends Parent {
-    children: Array<NodeWithData<Node, StabilityIndexMetadataEntry>>;
+    children: Array<NodeWithData<Root, StabilityIndexMetadataEntry>>;
   }
 
   export interface HeadingMetadataEntry {
@@ -35,10 +35,11 @@ declare global {
     text: string;
     name: string;
     depth: number;
+    slug: string;
   }
 
   export interface HeadingMetadataParent
-    extends NodeWithData<Parent, HeadingMetadataEntry> {}
+    extends NodeWithData<Heading, HeadingMetadataEntry> {}
 
   export interface ApiDocMetadataChange {
     // The Node.js version or versions where said change was introduced simultaneously