Add verbose logging (-v option) functionality

docs/userGuide/cliCommands.md

@@ -21,16 +21,21 @@ An overview of MarkBind's Command Line Interface (CLI) can be referenced with `m
 ```
 $ markbind --help
 Usage: markbind <command>
-
- Options:
-   -V, --version                      output the version number
-   -h, --help                         output usage information
-
- Commands:
-   init|i [options] [root]            init a markbind website project
-   serve|s [options] [root]           build then serve a website from a directory
-   build|b [options] [root] [output]  build a website
-   deploy|d [options] [root]          deploy the latest build of the site to the repo's Github pages
+
+Options:
+  -V, --version                      output the version number
+  -h, --help                         display help for command
+
+Setup Commands
+  init|i [options] [root]            init a markbind site
+
+Site Commands
+  serve|s [options] [root]           Build then serve a website from a directory
+  build|b [options] [root] [output]  Build a website
+  deploy|d [options] [root]          Deploy the latest build of the site to GitHub Pages
+
+Commands:
+  help [command]                     display help for command
 ```
 <hr><!-- ========================================================================== -->
 <div id="markbind-init">
@@ -132,6 +137,9 @@ The caveat is that not building all pages during the initial process, or not reb
 * `-p <port>`, `--port <port>`<br>
     Serve the website in the specified port (Default is 8080).
 
+* `-v`, `--verbose`<br>
+    Enable verbose logging. This is useful for diagnosing page-specific errors (e.g., Vue rendering warnings) by showing which page is currently being processed.
+
 {{ icon_examples }}
 * `markbind serve` : Serves the site from the current working directory.
 * `markbind serve ./myWebsite` : Serves the site from the `./myWebsite` directory.
@@ -171,6 +179,9 @@ The caveat is that not building all pages during the initial process, or not reb
   Specify the site config file (default: `site.json`)<br>
   {{ icon_example }} `-s otherSite.json`
 
+* `-v`, `--verbose`<br>
+  Enable verbose logging. This is useful for diagnosing page-specific errors (e.g., Vue rendering warnings) by showing which page is currently being processed.
+
 **{{ icon_examples }}**
 * `markbind build` : Generates the site from the current working directory.
 * `markbind build ./myWebsite` : Generates the site from the `./myWebsite` directory.
@@ -210,6 +221,9 @@ The caveat is that not building all pages during the initial process, or not reb
   Specify the site config file (default: `site.json`).<br>
   {{ icon_example }} `-s otherSite.json`
 
+* `-v`, `--verbose`<br>
+  Enable verbose logging. This is useful for diagnosing page-specific errors during the build phase of deployment.
+
 %%{{ icon_info }} Related: [User Guide: Deploying the Website](deployingTheSite.html).%%
 
 **{{ icon_examples }}**

packages/cli/index.ts

@@ -86,8 +86,9 @@ program
     program.createOption('-a, --address <address>', 'specify the server address/host (Default is 127.0.0.1)'))
   .addOption(
     program.createOption('-s, --site-config <file>', 'specify the site config file (default: site.json)'))
-
-  // Development mode is hidden as it is not user facing and only works during local development
+  .addOption(
+    program.createOption('-v, --verbose', 'enable verbose logging (e.g., page building logs)'))
+  // Development mode is hidden as it is not user facing and only works in local development environment
   .addOption(
     new Option('-d, --dev', 'development mode, enabling live & hot reload for frontend source files.')
       .hideHelp())
@@ -101,6 +102,7 @@ program
   .option('--baseUrl [baseUrl]',
           'optional flag which overrides baseUrl in site.json, leave argument empty for empty baseUrl')
   .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
+  .option('-v, --verbose', 'enable verbose logging (e.g., page building logs)')
   .summary('Build a website')
   .description('Build a website')
   .action((userSpecifiedRoot, output, options) => {
@@ -113,6 +115,7 @@ program
   .option('-c, --ci [githubTokenName]', 'deploy the site in CI Environment [GITHUB_TOKEN]')
   .option('-n, --no-build', 'do not automatically build the site before deployment')
   .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
+  .option('-v, --verbose', 'enable verbose logging (e.g., page building logs)')
   .summary('Deploy the latest build of the site to GitHub Pages')
   .description('Deploy the latest build of the site to the repo\'s GitHub Pages')
   .action((userSpecifiedRoot, options) => {

packages/cli/src/cmd/build.ts

@@ -5,6 +5,10 @@ import * as cliUtil from '../util/cliUtil.js';
 import * as logger from '../util/logger.js';
 
 function build(userSpecifiedRoot: string, output: string, options: any) {
+  if (options.verbose) {
+    logger.useVerboseConsole();
+  }
+
   // if --baseUrl contains no arguments (options.baseUrl === true) then set baseUrl to empty string
   const baseUrl = _.isBoolean(options.baseUrl) ? '' : options.baseUrl;
 

packages/cli/src/cmd/deploy.ts

@@ -6,6 +6,9 @@ import * as logger from '../util/logger.js';
 
 function deploy(userSpecifiedRoot: string, options: any) {
   let rootFolder;
+  if (options.verbose) {
+    logger.useVerboseConsole();
+  }
   try {
     rootFolder = cliUtil.findRootFolder(userSpecifiedRoot, options.siteConfig);
   } catch (error) {

packages/cli/src/cmd/serve.ts

@@ -38,6 +38,8 @@ function questionAsync(question: string): Promise<string> {
 function serve(userSpecifiedRoot: string, options: any) {
   if (options.dev) {
     logger.useDebugConsole();
+  } else if (options.verbose) {
+    logger.useVerboseConsole();
   }
 
   let rootFolder;

packages/cli/src/util/logger.ts

@@ -30,6 +30,10 @@ function useDebugConsole(): void {
   consoleTransport.level = 'debug';
 }
 
+function useVerboseConsole(): void {
+  consoleTransport.level = 'verbose';
+}
+
 const dailyRotateFileTransport = new DailyRotateFile({
   format: fileFormat,
   datePattern: 'YYYY-MM-DD',
@@ -60,6 +64,7 @@ export {
 
 export {
   useDebugConsole,
+  useVerboseConsole,
 };
 
 // eslint-disable-next-line no-console

packages/core/src/Page/index.ts

@@ -518,7 +518,6 @@ export class Page {
    */
   async generate(externalManager: ExternalManager) {
     this.resetState(); // Reset for live reload
-
     const fileConfig: NodeProcessorConfig = {
       baseUrl: this.siteConfig.baseUrl,
       ignore: this.siteConfig.ignore,
@@ -594,6 +593,7 @@ export class Page {
      * However, for automated testings (e.g. snapshots), we will output the pre SSR-processed HTML content
      * as we want to retain the unrendered DOM for easier reference and checking.
      */
+    logger.verbose(`Rendering page: ${this.pageConfig.sourcePath}`);
     const vueSsrHtml = await pageVueServerRenderer.renderVuePage(renderFn);
     this.filterIconAssets(content, vueSsrHtml);
     if (process.env.TEST_MODE) {

packages/core/src/utils/logger.ts

@@ -28,48 +28,28 @@ winston.configure({
   transports: [consoleTransport],
 });
 
-// create a wrapper for error messages
-const errorWrap = (input: any) => {
+const createLoggerThatInterruptsProgressBar = (level: string) => (...args: any[]) => {
   if (progressBar) {
     progressBar.interruptBegin();
-    winston.error(input);
+    (winston as any).log(level, ...args);
     progressBar.interruptEnd();
   } else {
-    winston.error(input);
+    (winston as any).log(level, ...args);
   }
 };
 
-// create a wrapper for warning messages
-const warnWrap = (input: any) => {
-  if (progressBar) {
-    progressBar.interruptBegin();
-    winston.warn(input);
-    progressBar.interruptEnd();
-  } else {
-    winston.warn(input);
-  }
-};
-
-// create a wrapper for info messages
-const infoWrap = (input: any) => {
-  if (progressBar) {
-    progressBar.interruptBegin();
-    winston.info(input);
-    progressBar.interruptEnd();
-  } else {
-    winston.info(input);
-  }
-};
-
-const { debug } = winston;
-const { verbose } = winston;
+const errorWrap = createLoggerThatInterruptsProgressBar('error');
+const warnWrap = createLoggerThatInterruptsProgressBar('warn');
+const infoWrap = createLoggerThatInterruptsProgressBar('info');
+const verboseWrap = createLoggerThatInterruptsProgressBar('verbose');
+const debugWrap = createLoggerThatInterruptsProgressBar('debug');
 
 export {
   errorWrap as error,
   warnWrap as warn,
   infoWrap as info,
-  verbose,
-  debug,
+  verboseWrap as verbose,
+  debugWrap as debug,
   setProgressBar,
   removeProgressBar,
 };