From 6b50d4a803206cb2bd059fdb3eb6a23ddd3ce641 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 17:03:47 +0800 Subject: [PATCH 01/15] Upgrade commander v8 to v14 --- package-lock.json | 11 ++++++++++- packages/cli/package.json | 12 ++++++------ 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index 230cc41c4b..4c41508784 100644 --- a/package-lock.json +++ b/package-lock.json @@ -21913,7 +21913,7 @@ "cheerio": "^0.22.0", "chokidar": "^3.3.0", "colors": "1.4.0", - "commander": "^8.1.0", + "commander": "^14.0.3", "figlet": "^1.9.4", "find-up": "^4.1.0", "fs-extra": "^9.0.1", @@ -21967,6 +21967,15 @@ "node": ">=8" } }, + "packages/cli/node_modules/commander": { + "version": "14.0.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz", + "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==", + "license": "MIT", + "engines": { + "node": ">=20" + } + }, "packages/cli/node_modules/file-stream-rotator": { "version": "0.6.1", "resolved": "https://registry.npmjs.org/file-stream-rotator/-/file-stream-rotator-0.6.1.tgz", diff --git a/packages/cli/package.json b/packages/cli/package.json index 96f6fd46e2..614afeb065 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -39,7 +39,7 @@ "cheerio": "^0.22.0", "chokidar": "^3.3.0", "colors": "1.4.0", - "commander": "^8.1.0", + "commander": "^14.0.3", "figlet": "^1.9.4", "find-up": "^4.1.0", "fs-extra": "^9.0.1", @@ -50,18 +50,18 @@ "winston-daily-rotate-file": "^5.0.0" }, "devDependencies": { + "@babel/core": "^7.29.0", + "@babel/preset-env": "^7.29.0", + "@babel/preset-typescript": "^7.28.5", "@types/jest": "^29.4.6", "@types/lodash": "^4.17.15", "@types/url-parse": "^1.4.8", + "babel-jest": "^29.7.0", "diff": "^8.0.3", "ignore": "^7.0.5", "istextorbinary": "^9.5.0", "jest": "^29.7.0", "memfs": "^4.56.2", - "walk-sync": "^2.0.2", - "@babel/core": "^7.29.0", - "@babel/preset-env": "^7.29.0", - "@babel/preset-typescript": "^7.28.5", - "babel-jest": "^29.7.0" + "walk-sync": "^2.0.2" } } From fc9b8650bf1542922fedc73162c23504961528d2 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 18:45:10 +0800 Subject: [PATCH 02/15] Update commander syntax to latest v14 --- packages/cli/index.ts | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/packages/cli/index.ts b/packages/cli/index.ts index a98e0ad53c..ef8f451bea 100755 --- a/packages/cli/index.ts +++ b/packages/cli/index.ts @@ -1,7 +1,8 @@ #!/usr/bin/env node // Entry file for MarkBind project -import { program } from 'commander'; +import { program, Option } from 'commander'; +import chalk from 'chalk'; import * as logger from './src/util/logger.js'; import { build } from './src/cmd/build.js'; import { deploy } from './src/cmd/deploy.js'; @@ -24,7 +25,11 @@ function printHeader() { program .addHelpText('beforeAll', printHeader()) - .showHelpAfterError('(run "markbind --help" to list commands)'); + .showHelpAfterError('(run "markbind --help" to list commands)') + .configureHelp({ + styleTitle: (str) => chalk.bold.cyan(str), + styleUsage: (str) => chalk.bold.cyan(str), + }); program .allowUnknownOption() @@ -47,18 +52,26 @@ program program .command('serve [root]') .alias('s') - .option('-f, --force-reload', 'force a full reload of all site files when a file is changed') - .option('-n, --no-open', 'do not automatically open the site in browser') - .option('-o, --one-page [file]', 'build and serve only a single page in the site initially,' + .description('Build and serve a website from a directory') + + .optionsGroup('Build Options') + .addOption(program.createOption('-f, --force-reload', 'force a full reload of all site files when a file is changed') + .conflicts('onePage')) + .addOption(program.createOption('-o, --one-page [file]', 'build and serve only a single page in the site initially, ' + 'building more pages when they are navigated to. Also lazily rebuilds only the page being viewed when' - + 'there are changes to the source files (if needed), building others when navigated to') - .option('-b, --background-build', 'when --one-page is specified, enhances one-page serve by building' - + 'remaining pages in the background') - .option('-p, --port ', 'port for server to listen on (Default is 8080)') - .option('-s, --site-config ', 'specify the site config file (default: site.json)') - .option('-d, --dev', 'development mode, enabling live & hot reload for frontend source files.') - .option('-a, --address
', 'specify the server address/host (Default is 127.0.0.1)') - .description('build then serve a website from a directory') + + 'there are changes to the source files (if needed), building others when navigated to')) + .addOption(program.createOption('-b, --background-build', 'when --one-page is specified, enhances one-page serve by building' + + 'remaining pages in the background')) + + .optionsGroup('Server Options') + .addOption(program.createOption('-n, --no-open', 'do not automatically open the site in browser')) + .addOption(program.createOption('-p, --port ', 'port for server to listen on (Default is 8080)')) + .addOption(program.createOption('-a, --address
', 'specify the server address/host (Default is 127.0.0.1)')) + .addOption(program.createOption('-s, --site-config ', '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(new Option('-d, --dev', 'development mode, enabling live & hot reload for frontend source files.') + .hideHelp()) .action((userSpecifiedRoot, options) => { serve(userSpecifiedRoot, options); }); From fbad7d0cc05fab772823158002cf6bb9f4e203df Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 18:45:48 +0800 Subject: [PATCH 03/15] Remove manual flag resolution Replace in favor of native `conflicts()` supported by commander --- packages/cli/src/cmd/serve.ts | 6 ------ 1 file changed, 6 deletions(-) diff --git a/packages/cli/src/cmd/serve.ts b/packages/cli/src/cmd/serve.ts index 1a5e0e6adf..e645bfb381 100755 --- a/packages/cli/src/cmd/serve.ts +++ b/packages/cli/src/cmd/serve.ts @@ -43,12 +43,6 @@ function serve(userSpecifiedRoot: string, options: any) { let rootFolder; try { rootFolder = cliUtil.findRootFolder(userSpecifiedRoot, options.siteConfig); - - if (options.forceReload && options.onePage) { - logger.error('Oops! You shouldn\'t need to use the --force-reload option with --one-page.'); - process.exitCode = 1; - process.exit(); - } } catch (error) { if (_.isError(error)) { logger.error(error.message); From b0851acb4c5c97c4bf9923bfe2b9142f34710dbe Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 20:06:03 +0800 Subject: [PATCH 04/15] Add styling colors to CLI and section headers --- packages/cli/index.ts | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/packages/cli/index.ts b/packages/cli/index.ts index ef8f451bea..9a809a0438 100755 --- a/packages/cli/index.ts +++ b/packages/cli/index.ts @@ -28,7 +28,8 @@ program .showHelpAfterError('(run "markbind --help" to list commands)') .configureHelp({ styleTitle: (str) => chalk.bold.cyan(str), - styleUsage: (str) => chalk.bold.cyan(str), + styleUsage: (str) => chalk.white(str), + styleOptionText: (str) => chalk.yellow(str), }); program @@ -40,27 +41,31 @@ program .version(CLI_VERSION); program + .commandsGroup('Setup Commands') .command('init [root]') .option('-c, --convert', 'convert a GitHub wiki or docs folder to a MarkBind website') .option('-t, --template ', 'initialise markbind with a specified template', 'default') .alias('i') + .summary('init a markbind site') .description('init a markbind website project') .action((root, options) => { init(root, options); }); program + .commandsGroup('Site Commands') .command('serve [root]') .alias('s') + .summary('Build then serve a website from a directory') .description('Build and serve a website from a directory') .optionsGroup('Build Options') .addOption(program.createOption('-f, --force-reload', 'force a full reload of all site files when a file is changed') .conflicts('onePage')) .addOption(program.createOption('-o, --one-page [file]', 'build and serve only a single page in the site initially, ' - + 'building more pages when they are navigated to. Also lazily rebuilds only the page being viewed when' + + 'building more pages when they are navigated to. Also lazily rebuilds only the page being viewed when ' + 'there are changes to the source files (if needed), building others when navigated to')) - .addOption(program.createOption('-b, --background-build', 'when --one-page is specified, enhances one-page serve by building' + .addOption(program.createOption('-b, --background-build', 'when --one-page is specified, enhances one-page serve by building ' + 'remaining pages in the background')) .optionsGroup('Server Options') @@ -82,7 +87,8 @@ program .option('--baseUrl [baseUrl]', 'optional flag which overrides baseUrl in site.json, leave argument empty for empty baseUrl') .option('-s, --site-config ', 'specify the site config file (default: site.json)') - .description('build a website') + .summary('Build a website') + .description('Build a website') .action((userSpecifiedRoot, output, options) => { build(userSpecifiedRoot, output, options); }); @@ -93,7 +99,8 @@ 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 ', 'specify the site config file (default: site.json)') - .description('deploy the latest build of the site to the repo\'s Github pages') + .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) => { deploy(userSpecifiedRoot, options); }); From 82d5952f61f0a49a70598aa1f4592de81aed8a72 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 20:19:43 +0800 Subject: [PATCH 05/15] Apply lint fixes --- packages/cli/index.ts | 46 ++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/packages/cli/index.ts b/packages/cli/index.ts index 9a809a0438..f9e1b2cbc0 100755 --- a/packages/cli/index.ts +++ b/packages/cli/index.ts @@ -27,9 +27,9 @@ program .addHelpText('beforeAll', printHeader()) .showHelpAfterError('(run "markbind --help" to list commands)') .configureHelp({ - styleTitle: (str) => chalk.bold.cyan(str), - styleUsage: (str) => chalk.white(str), - styleOptionText: (str) => chalk.yellow(str), + styleTitle: str => chalk.bold.cyan(str), + styleUsage: str => chalk.white(str), + styleOptionText: str => chalk.yellow(str), }); program @@ -60,23 +60,37 @@ program .description('Build and serve a website from a directory') .optionsGroup('Build Options') - .addOption(program.createOption('-f, --force-reload', 'force a full reload of all site files when a file is changed') - .conflicts('onePage')) - .addOption(program.createOption('-o, --one-page [file]', 'build and serve only a single page in the site initially, ' - + 'building more pages when they are navigated to. Also lazily rebuilds only the page being viewed when ' - + 'there are changes to the source files (if needed), building others when navigated to')) - .addOption(program.createOption('-b, --background-build', 'when --one-page is specified, enhances one-page serve by building ' - + 'remaining pages in the background')) + .addOption( + program.createOption('-f, --force-reload', + 'force a full reload of all site files when a file is changed') + .conflicts('onePage')) + + .addOption( + program.createOption('-o, --one-page [file]', + 'build and serve only a single page in the site initially, ' + + 'building more pages when they are navigated to. Also lazily rebuilds only ' + + 'the page being viewed when there are changes to the source files (if needed), ' + + 'building others when navigated to')) + + .addOption( + program.createOption('-b, --background-build', + 'when --one-page is specified, enhances one-page serve by building ' + + 'remaining pages in the background')) .optionsGroup('Server Options') - .addOption(program.createOption('-n, --no-open', 'do not automatically open the site in browser')) - .addOption(program.createOption('-p, --port ', 'port for server to listen on (Default is 8080)')) - .addOption(program.createOption('-a, --address
', 'specify the server address/host (Default is 127.0.0.1)')) - .addOption(program.createOption('-s, --site-config ', 'specify the site config file (default: site.json)')) + .addOption( + program.createOption('-n, --no-open', 'do not automatically open the site in browser')) + .addOption( + program.createOption('-p, --port ', 'port for server to listen on (Default is 8080)')) + .addOption( + program.createOption('-a, --address
', 'specify the server address/host (Default is 127.0.0.1)')) + .addOption( + program.createOption('-s, --site-config ', '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(new Option('-d, --dev', 'development mode, enabling live & hot reload for frontend source files.') - .hideHelp()) + .addOption( + new Option('-d, --dev', 'development mode, enabling live & hot reload for frontend source files.') + .hideHelp()) .action((userSpecifiedRoot, options) => { serve(userSpecifiedRoot, options); }); From 6f3a23ca730746ed15fc281a848e83b94604b6f8 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 20:28:49 +0800 Subject: [PATCH 06/15] Add specific callout for serve -d --- docs/devGuide/development/workflow.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/devGuide/development/workflow.md b/docs/devGuide/development/workflow.md index 121cc783f2..3134ca52a4 100644 --- a/docs/devGuide/development/workflow.md +++ b/docs/devGuide/development/workflow.md @@ -171,6 +171,17 @@ Hence, if you need to view the latest frontend changes (relating to `packages/co 1. Run `npm run build:web` in the root directory, which builds the above bundles, then run your markbind-cli commandcommand of choice. + + + + +##### `markbind serve -d` + +`markbind serve -d` adds the necessary webpack middlewares to the development server to compile the bundles for `markbind-core-web` and `markbind-vue-components`, and enables live and hot reloading for frontend source files. + +Note that the command is only applicable for local development, and does not work when you install MarkBind from npm, as it relies on developmental dependencies. + +
## Testing From c2f011c2b9663cacbafe587c35805db5333c8f67 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 20:36:07 +0800 Subject: [PATCH 07/15] Fix copilot word nit --- packages/cli/index.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/index.ts b/packages/cli/index.ts index f9e1b2cbc0..408bcf8f80 100755 --- a/packages/cli/index.ts +++ b/packages/cli/index.ts @@ -113,8 +113,8 @@ 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 ', 'specify the site config file (default: site.json)') - .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') + .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) => { deploy(userSpecifiedRoot, options); }); From 4d0c4c890e9cebe7584efc938c4003309974fe71 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 21:45:59 +0800 Subject: [PATCH 08/15] feat: Introduce --verbose CLI option for detailed logging during build and serve --- packages/cli/index.ts | 6 ++++-- packages/cli/src/cmd/build.ts | 4 ++++ packages/cli/src/cmd/serve.ts | 2 ++ packages/cli/src/util/logger.ts | 5 +++++ packages/core/src/Page/index.ts | 1 + 5 files changed, 16 insertions(+), 2 deletions(-) diff --git a/packages/cli/index.ts b/packages/cli/index.ts index 408bcf8f80..803aa13ce5 100755 --- a/packages/cli/index.ts +++ b/packages/cli/index.ts @@ -86,8 +86,9 @@ program program.createOption('-a, --address
', 'specify the server address/host (Default is 127.0.0.1)')) .addOption( program.createOption('-s, --site-config ', '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 ', '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) => { diff --git a/packages/cli/src/cmd/build.ts b/packages/cli/src/cmd/build.ts index 8763fbd5f9..421c3e5cec 100755 --- a/packages/cli/src/cmd/build.ts +++ b/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; diff --git a/packages/cli/src/cmd/serve.ts b/packages/cli/src/cmd/serve.ts index e645bfb381..66160a73bf 100755 --- a/packages/cli/src/cmd/serve.ts +++ b/packages/cli/src/cmd/serve.ts @@ -38,6 +38,8 @@ function questionAsync(question: string): Promise { function serve(userSpecifiedRoot: string, options: any) { if (options.dev) { logger.useDebugConsole(); + } else if (options.verbose) { + logger.useVerboseConsole(); } let rootFolder; diff --git a/packages/cli/src/util/logger.ts b/packages/cli/src/util/logger.ts index 0c30d25daf..4c6f2ea004 100644 --- a/packages/cli/src/util/logger.ts +++ b/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 diff --git a/packages/core/src/Page/index.ts b/packages/core/src/Page/index.ts index e76a343a28..7431c28876 100644 --- a/packages/core/src/Page/index.ts +++ b/packages/core/src/Page/index.ts @@ -518,6 +518,7 @@ export class Page { */ async generate(externalManager: ExternalManager) { this.resetState(); // Reset for live reload + logger.verbose(`Building page: ${this.pageConfig.sourcePath}`); const fileConfig: NodeProcessorConfig = { baseUrl: this.siteConfig.baseUrl, From ca42f5387b15b22681108241cefec6344c616f7a Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 21:47:41 +0800 Subject: [PATCH 09/15] refactor: consolidate logger wrapper functions into single factory and extend to all log levels --- packages/core/src/utils/logger.ts | 51 +++++++++++++------------------ 1 file changed, 21 insertions(+), 30 deletions(-) diff --git a/packages/core/src/utils/logger.ts b/packages/core/src/utils/logger.ts index 29ac2f5578..7b2b58c4d2 100644 --- a/packages/core/src/utils/logger.ts +++ b/packages/core/src/utils/logger.ts @@ -28,48 +28,39 @@ winston.configure({ transports: [consoleTransport], }); -// create a wrapper for error messages -const errorWrap = (input: any) => { +/** + * Creates a wrapper function for a specific Winston log level. + * + * The wrapper ensures that if a progress bar is active, it is interrupted + * before logging and resumed after, preventing the log message from being + * mangled by the progress bar re-rendering. + * + * @param level - The Winston log level (e.g., 'error', 'warn', 'info', 'verbose', 'debug'). + * @returns A function that logs the provided input at the specified level, + * handling progress bar interruptions if necessary. + */ +const createWrapper = (level: string) => (input: any) => { if (progressBar) { progressBar.interruptBegin(); - winston.error(input); + winston.log(level, input); progressBar.interruptEnd(); } else { - winston.error(input); + winston.log(level, input); } }; -// 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 = createWrapper('error'); +const warnWrap = createWrapper('warn'); +const infoWrap = createWrapper('info'); +const verboseWrap = createWrapper('verbose'); +const debugWrap = createWrapper('debug'); export { errorWrap as error, warnWrap as warn, infoWrap as info, - verbose, - debug, + verboseWrap as verbose, + debugWrap as debug, setProgressBar, removeProgressBar, }; From a90732f464345f196f3c9bb5f7b2211f471a9700 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 21:56:58 +0800 Subject: [PATCH 10/15] Shift log closer to source due to default concurrent page generation race condition --- packages/core/src/Page/index.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/core/src/Page/index.ts b/packages/core/src/Page/index.ts index 7431c28876..aef23e787b 100644 --- a/packages/core/src/Page/index.ts +++ b/packages/core/src/Page/index.ts @@ -518,8 +518,6 @@ export class Page { */ async generate(externalManager: ExternalManager) { this.resetState(); // Reset for live reload - logger.verbose(`Building page: ${this.pageConfig.sourcePath}`); - const fileConfig: NodeProcessorConfig = { baseUrl: this.siteConfig.baseUrl, ignore: this.siteConfig.ignore, @@ -594,7 +592,11 @@ 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. + * + * Additionally, we log the page rendered for easier diagnosis if there are vue render warnings + * So that site author can better diagnose page containing vue render warning. */ + logger.verbose(`Rendering page: ${this.pageConfig.sourcePath}`); const vueSsrHtml = await pageVueServerRenderer.renderVuePage(renderFn); this.filterIconAssets(content, vueSsrHtml); if (process.env.TEST_MODE) { From ac7fdccca498bf91bbe6971a58449fe2638def7d Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 22:06:47 +0800 Subject: [PATCH 11/15] refactor: best code has no comments --- packages/core/src/utils/logger.ts | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/packages/core/src/utils/logger.ts b/packages/core/src/utils/logger.ts index 7b2b58c4d2..d4ea55a65f 100644 --- a/packages/core/src/utils/logger.ts +++ b/packages/core/src/utils/logger.ts @@ -28,18 +28,7 @@ winston.configure({ transports: [consoleTransport], }); -/** - * Creates a wrapper function for a specific Winston log level. - * - * The wrapper ensures that if a progress bar is active, it is interrupted - * before logging and resumed after, preventing the log message from being - * mangled by the progress bar re-rendering. - * - * @param level - The Winston log level (e.g., 'error', 'warn', 'info', 'verbose', 'debug'). - * @returns A function that logs the provided input at the specified level, - * handling progress bar interruptions if necessary. - */ -const createWrapper = (level: string) => (input: any) => { +const createLoggerThatInterruptsProgressBar = (level: string) => (input: any) => { if (progressBar) { progressBar.interruptBegin(); winston.log(level, input); @@ -49,11 +38,11 @@ const createWrapper = (level: string) => (input: any) => { } }; -const errorWrap = createWrapper('error'); -const warnWrap = createWrapper('warn'); -const infoWrap = createWrapper('info'); -const verboseWrap = createWrapper('verbose'); -const debugWrap = createWrapper('debug'); +const errorWrap = createLoggerThatInterruptsProgressBar('error'); +const warnWrap = createLoggerThatInterruptsProgressBar('warn'); +const infoWrap = createLoggerThatInterruptsProgressBar('info'); +const verboseWrap = createLoggerThatInterruptsProgressBar('verbose'); +const debugWrap = createLoggerThatInterruptsProgressBar('debug'); export { errorWrap as error, From b170d13f541ff631367f754c316e62061c4b3fe9 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 22:07:34 +0800 Subject: [PATCH 12/15] Fix lint error --- packages/core/src/Page/index.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/packages/core/src/Page/index.ts b/packages/core/src/Page/index.ts index aef23e787b..79b4bd0c18 100644 --- a/packages/core/src/Page/index.ts +++ b/packages/core/src/Page/index.ts @@ -592,9 +592,6 @@ 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. - * - * Additionally, we log the page rendered for easier diagnosis if there are vue render warnings - * So that site author can better diagnose page containing vue render warning. */ logger.verbose(`Rendering page: ${this.pageConfig.sourcePath}`); const vueSsrHtml = await pageVueServerRenderer.renderVuePage(renderFn); From cd37cf4687a00ef03fc46f118f688e0b55320b33 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 22:12:55 +0800 Subject: [PATCH 13/15] Add to deploy command --- packages/cli/index.ts | 1 + packages/cli/src/cmd/deploy.ts | 3 +++ 2 files changed, 4 insertions(+) diff --git a/packages/cli/index.ts b/packages/cli/index.ts index 803aa13ce5..4a594a3325 100755 --- a/packages/cli/index.ts +++ b/packages/cli/index.ts @@ -115,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 ', '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) => { diff --git a/packages/cli/src/cmd/deploy.ts b/packages/cli/src/cmd/deploy.ts index 4ededc67d4..80f0ee19f6 100755 --- a/packages/cli/src/cmd/deploy.ts +++ b/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) { From 8cce038a055073023add4a96ed739a3d61ea07e4 Mon Sep 17 00:00:00 2001 From: gerteck Date: Fri, 13 Mar 2026 22:13:27 +0800 Subject: [PATCH 14/15] Update documentation --- docs/userGuide/cliCommands.md | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/userGuide/cliCommands.md b/docs/userGuide/cliCommands.md index ce5c1951fb..fee910eb03 100644 --- a/docs/userGuide/cliCommands.md +++ b/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 - - 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 ```
@@ -132,6 +137,9 @@ The caveat is that not building all pages during the initial process, or not reb * `-p `, `--port `
Serve the website in the specified port (Default is 8080). +* `-v`, `--verbose`
+ 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`)
{{ icon_example }} `-s otherSite.json` +* `-v`, `--verbose`
+ 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`).
{{ icon_example }} `-s otherSite.json` +* `-v`, `--verbose`
+ 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 }}** From 89f2a0df424fe4bfa66fe05cebc93afd26e85a0e Mon Sep 17 00:00:00 2001 From: gerteck Date: Sat, 14 Mar 2026 00:27:57 +0800 Subject: [PATCH 15/15] Fix copilot nit --- packages/core/src/utils/logger.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/core/src/utils/logger.ts b/packages/core/src/utils/logger.ts index d4ea55a65f..b7d1b4ed29 100644 --- a/packages/core/src/utils/logger.ts +++ b/packages/core/src/utils/logger.ts @@ -28,13 +28,13 @@ winston.configure({ transports: [consoleTransport], }); -const createLoggerThatInterruptsProgressBar = (level: string) => (input: any) => { +const createLoggerThatInterruptsProgressBar = (level: string) => (...args: any[]) => { if (progressBar) { progressBar.interruptBegin(); - winston.log(level, input); + (winston as any).log(level, ...args); progressBar.interruptEnd(); } else { - winston.log(level, input); + (winston as any).log(level, ...args); } };