feat: Add grouping of messages in Github Actions, and lazy debug logging

Author: hatton

src/log.ts

@@ -14,13 +14,33 @@ export function warning(s: string): void {
 export function info(s: string): void {
   console.log(s);
 }
-export function heading(s: string): void {
-  console.log(chalk.blue(s));
+
+// make sure to call endGroup(), eventually, after calling this
+export function group(s: string): void {
+  console.log(chalk.blue(wrapForCI(s, "group")));
+}
+
+// github actions needs an ::endgroup:: to end a group
+export function endGroup(): void {
+  console.log(wrapForCI("", "endgroup"));
 }
+
 export function verbose(s: string): void {
   if (logLevel === "verbose" || logLevel === "debug")
     console.log(chalk.green(s));
 }
+
+// use this one if the debug info would take time to construct,
+// so you want to skip doing it if not in debug mode
+export function logDebugFn(
+  label: string,
+  runIfLoggingDebug: () => string
+): void {
+  if (logLevel === "debug") {
+    logDebug(label, runIfLoggingDebug());
+  }
+}
+
 export function logDebug(label: string, info: string): void {
   if (logLevel === "debug") {
     console.log(chalk.dim(wrapForCI(`[${label}]`, "debug")));

src/plugins/HeadingTransformer.ts

@@ -1,6 +1,7 @@
 import { NotionToMarkdown } from "notion-to-md";
 import { NotionBlock } from "../types";
 import { IPlugin } from "./pluginTypes";
+import { logDebug } from "../log";
 
 // Makes links to headings work in docusaurus
 // https://github.com/sillsdev/docu-notion/issues/20
@@ -13,6 +14,11 @@ async function headingTransformer(
 
   const markdown = await notionToMarkdown.blockToMarkdown(block);
 
+  logDebug(
+    "headingTransformer, markdown of a heading before adding id",
+    markdown
+  );
+
   // To make heading links work in docusaurus, we append an id. E.g.
   //  ### Hello World {#my-explicit-id}
   // See https://docusaurus.io/docs/markdown-features/toc#heading-ids.

src/pull.ts

@@ -7,7 +7,15 @@ import { NotionPage, PageType } from "./NotionPage";
 import { initImageHandling, cleanupOldImages } from "./images";
 
 import * as Path from "path";
-import { error, heading, info, logDebug, verbose, warning } from "./log";
+import {
+  endGroup,
+  error,
+  group,
+  info,
+  logDebug,
+  verbose,
+  warning,
+} from "./log";
 import { IDocuNotionContext } from "./plugins/pluginTypes";
 import { getMarkdownForPage } from "./transform";
 import {
@@ -70,21 +78,22 @@ export async function notionPull(options: DocuNotionOptions): Promise<void> {
 
   info("Connecting to Notion...");
 
-  heading(
+  group(
     "Stage 1: walk children of the page named 'Outline', looking for pages..."
   );
   await getPagesRecursively(options, "", options.rootPage, 0, true);
   logDebug("getPagesRecursively", JSON.stringify(pages, null, 2));
   info(`Found ${pages.length} pages`);
-  info(``);
-  heading(
+  endGroup();
+  group(
     `Stage 2: convert ${pages.length} Notion pages to markdown and save locally...`
   );
   await outputPages(options, config, pages);
-  info(``);
-  heading("Stage 3: clean up old files & images...");
+  endGroup();
+  group("Stage 3: clean up old files & images...");
   await layoutStrategy.cleanupOldFiles();
   await cleanupOldImages();
+  endGroup();
 }
 
 async function outputPages(

src/transform.ts

@@ -3,7 +3,7 @@ import {
   IDocuNotionContext,
   IRegexMarkdownModification,
 } from "./plugins/pluginTypes";
-import { error, info, logDebug, verbose, warning } from "./log";
+import { error, info, logDebug, logDebugFn, verbose, warning } from "./log";
 import { NotionPage } from "./NotionPage";
 import { IDocuNotionConfig } from "./config/configuration";
 import { NotionBlock } from "./types";
@@ -27,7 +27,7 @@ export async function getMarkdownForPage(
 
   const blocks = await context.getBlockChildren(page.pageId);
 
-  logDebug("pull", JSON.stringify(blocks));
+  logDebugFn("markdown from page", () => JSON.stringify(blocks, null, 2));
 
   const body = await getMarkdownFromNotionBlocks(context, config, blocks);
   const frontmatter = getFrontMatter(page); // todo should be a plugin
@@ -217,6 +217,10 @@ function registerNotionToMarkdownCustomTransforms(
   config.plugins.forEach(plugin => {
     if (plugin.notionToMarkdownTransforms) {
       plugin.notionToMarkdownTransforms.forEach(transform => {
+        logDebug(
+          "registering custom transform",
+          `${plugin.name} for ${transform.type}`
+        );
         docunotionContext.notionToMarkdown.setCustomTransformer(
           transform.type,
           (block: any) => {