host-mdx 2.2.0 → 2.3.0

package/README.md

@@ -5,47 +5,71 @@ A cli tool to create and serve a static html website from a given mdx directory
 
 ## 🛠️ Usage
 
+### With npx:
+```bash
+npx host-mdx --input-path="path/to/input" --output-path="path/to/output"
+```
+
+List of all available options:
 ```
-host-mdx [options]
+Usage: host-mdx [options]
 
 Options:
---create-only, -c     Only create the html website from mdx does not host
---help, -h            Shows all available options
---input-path=...      The path at which all mdx files are stored
---output-path=...     The path to which all html files will be generated
---port=...            Localhost port number on which to host 
---track-changes, -t   Tracks any changes made & auto reloads
---verobse, -v         Shows additional log messages
+--concurrency=<num>       Limit number of files to concurrently process (Optional, default: 1)
+--create-only, -c         Only creates the html website from mdx does not host
+--help, -h                Shows all available options
+--input-path=<path>       The path at which all mdx files are stored
+--output-path=<path>      The path to which all html files will be generated
+--port=<num>              Localhost port number on which to host 
+--track-changes, -t       Tracks any changes & auto reloads, -t=hard for hard reload
+--verbose, -v             Shows additional log messages
 ```
 
 > If `--input-path` is not provided it will default to `./` i.e. current working directory\
 > If `--output-path` is not provided a temp folder will be created automatically & deleted upon exit
 
-You can add a file by the name `.hostmdxignore` at the root of your project to filter out which files/folders to skip while generating html
-(similar to [.gitignore](https://git-scm.com/docs/gitignore))
 
-You can also add a file by the name `host-mdx.js` at the root of your input folder as a config file with access to the following:
+
+### With import/require:
 
 ```js
-onSiteCreateStart(inputPath, outputPath)
-onSiteCreateEnd(inputPath, outputPath, wasInterrupted)
-onFileCreateStart(inputPath, outputPath, inFilePath, outFilePath)
-onFileCreateEnd(inputPath, outputPath, inFilePath, outFilePath, result)
-modBundleMDXSettings(inputPath, outputPath, settings)
-modGlobalArgs(inputPath, outputPath, globalArgs)
-toTriggerRecreate(event, path)
+import { HostMdx } from "host-mdx";
+// const { HostMdx } = require("host-mdx");
+
+const inputPath = "/home/mrm/Desktop/website-mdx"
+const outputPath = "/home/mrm/Desktop/website-html"
+const configs = {
+   toBeVerbose: true, 
+   port:3000, 
+   trackChanges:1
+}
+const hostMdx = new HostMdx(inputPath, outputPath, configs);
+hostMdx.start();
 ```
 
-> **Note:** Any changes made to `host-mdx.js` or any new package added requires complete restart otherwise changes will not reflect due to [this bug](https://github.com/nodejs/node/issues/49442)
 
-Default global variables you can use inside any .mdx files:
+### Additional:
+
+You can add a file by the name `.hostmdxignore` at the root of your project to filter out which files/folders to skip while generating html
+(similar to [.gitignore](https://git-scm.com/docs/gitignore))
+
+You can also add a file by the name `host-mdx.js` at the root of your input folder as a config file (Look at the example below for all available options)
+
 
+> **Note:**  
+> 1. Any config properties passed from npx or import e.g. `port`, `toBeVerbose`, `trackChanges`, etc will override `host-mdx.js` export values
+> 1. Any changes made to `host-mdx.js` or any new package added requires complete restart otherwise changes will not reflect due to [this bug](https://github.com/nodejs/node/issues/49442)
+
+<br/>
+
+Default global variables you can use inside any .mdx files:  
 ```
 hostmdxCwd 
 hostmdxInputPath 
 hostmdxOutputPath
 ```
 
+
 ## 📖 Example
 
 Command:
@@ -58,6 +82,7 @@ Input Directory:
 
 ```
 my-website-template/
+├─ 404.mdx
 ├─ index.mdx
 ├─ .hostmdxignore
 ├─ host-mdx.js
@@ -90,42 +115,68 @@ static/temp.jpg
 `host-mdx.js` file content:
 
 ```js
-export function onSiteCreateStart(inputPath, outputPath) {
-   console.log("onSiteCreateStart", inputPath, outputPath)
+export async function onHostStarting(inputPath, outputPath, port) {
+   console.log("onHostStarting");
 }
-export function onSiteCreateEnd(inputPath, outputPath, wasSuccessful) {
-   console.log("onSiteCreateEnd", inputPath, outputPath, wasSuccessful)
+export async function onHostStarted(inputPath, outputPath, port) {
+   console.log("onHostStarted");
 }
-export function onFileCreateStart(inputFilePath, outputFilePath) {
-   console.log("onFileCreateStart", inputFilePath, outputFilePath)
+export async function onHostEnded(inputPath, outputPath, port) {
+   console.log("onHostEnded");
 }
-export function onFileCreateEnd(inputFilePath, outputFilePath) {
-   console.log("onFileCreateEnd", inputFilePath, outputFilePath)
+export async function onSiteCreateStart(inputPath, outputPath) {
+   console.log("onSiteCreateStart");
 }
-export function onHostStart(port) {
-   console.log("onHostStart", port)
+export async function onSiteCreateEnd(inputPath, outputPath, wasInterrupted) {
+   console.log("onSiteCreateEnd");
 }
-export function onHostEnd(port) {
-   console.log("onHostEnd", port)
+export async function onFileCreateStart(inputFilePath, outputFilePath, inFilePath, outFilePath) {
+   console.log("onFileCreateStart");
 }
-export function modBundleMDXSettings(inputPath, outputPath, settings) {
-   // Modify settings ...
-   return settings
+export async function onFileCreateEnd(inputFilePath, outputFilePath, inFilePath, outFilePath, result) {
+   // `result = undefined` if file is not .mdx
+   // `result.html` contains stringified HTML
+   // `result.exports` contains exports from mdx
+   console.log("onFileCreateEnd");
 }
-export function toTriggerRecreate(event, path) {
+export async function toIgnore(inputPath, outputPath, path) {
    const isGOutputStream = /\.goutputstream-\w+$/.test(path);
    if (isGOutputStream) {
-      return false;
+      return true;
    }
    
-   return true;
+   return false;
+}
+export async function modMDXCode(inputPath, outputPath, inFilePath, outFilePath, code){
+   // Modify code ...
+   return code;
+}
+export async function modGlobalArgs(inputPath, outputPath, globalArgs){
+   // Modify globalArgs ...
+   return globalArgs;
 }
+export async function modBundleMDXSettings(inputPath, outputPath, settings) {
+   // Modify settings ...
+   return settings;
+}
+export async function modRebuildPaths(inputPath, outputPath, rebuildPaths) {
+   // Modify rebuildPaths ...
+   return rebuildPaths;
+}
+export const chokidarOptions = {
+   awaitWriteFinish: true
+}
+export const port = 3000;
+export const trackChanges = 1;  // 0=no-tracking, 1=soft-reload, 2=hard-reload
+export const toBeVerbose = true;
+export const concurrency = 10;  // Lowest possible value: 1
 ```
 
 Output Directory:
 
 ```
 my-website/
+├─ 404.html
 ├─ index.html
 ├─ about/
 │  └─ index.html
@@ -141,6 +192,7 @@ my-website/
 
 The site will now be visible in the browser at `localhost:3113`
 
+
 ## 🔑 License
 
 MIT © [Manas Ravindra Makde](https://manasmakde.github.io/)

package/cli.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+import path from "path";
+import * as readline from "readline";
+import { HostMdx, createSite, TrackChanges, log } from "./index.js";
+
+
+// Flags
+const CONCURRENCY_FLAG = "--concurrency"
+const CREATE_FLAG = "--create-only";
+const CREATE_SHORT_FLAG = "-c";
+const HELP_FLAG = "--help";
+const HELP_SHORT_FLAG = "-h";
+const INPUT_PATH_FLAG = "--input-path";
+const OUTPUT_PATH_FLAG = "--output-path";
+const PORT_FLAG = "--port";
+const TRACK_CHANGES_FLAG = "--track-changes";
+const TRACK_CHANGES_SHORT_FLAG = "-t";
+const VERBOSE_FLAG = "--verbose";
+const VERBOSE_SHORT_FLAG = "-v";
+
+
+// Properties
+const SOFT_RELOAD_ARG = "soft"
+const HARD_RELOAD_ARG = "hard"
+const HELP_MESSAGE = `Usage: host-mdx [options]
+
+Options:
+${CONCURRENCY_FLAG}=<num>       Limit number of files to concurrently process (Optional, default: 1)
+${CREATE_FLAG}, ${CREATE_SHORT_FLAG}         Only creates the html website from mdx does not host
+${HELP_FLAG}, ${HELP_SHORT_FLAG}                Shows all available options
+${INPUT_PATH_FLAG}=<path>       The path at which all mdx files are stored
+${OUTPUT_PATH_FLAG}=<path>      The path to which all html files will be generated
+${PORT_FLAG}=<num>              Localhost port number on which to host 
+${TRACK_CHANGES_FLAG}, ${TRACK_CHANGES_SHORT_FLAG}       Tracks any changes & auto reloads, ${TRACK_CHANGES_SHORT_FLAG}=${HARD_RELOAD_ARG} for hard reload
+${VERBOSE_FLAG}, ${VERBOSE_SHORT_FLAG}             Shows additional log messages
+`;
+
+
+// Utility Methods
+function getInputPathFromArgs(rawArgs) {
+    let inputPath = rawArgs.find(val => val.startsWith(INPUT_PATH_FLAG));
+    let inputPathProvided = inputPath !== undefined;
+    inputPath = inputPathProvided ? inputPath.split('=')?.[1] : "";
+    return inputPath !== "" ? path.resolve(inputPath) : inputPath;  // To ensure input path is absolute
+}
+function getOutputPathFromArgs(rawArgs) {
+    let outputPath = rawArgs.find(val => val.startsWith(OUTPUT_PATH_FLAG));
+    let outputPathProvided = outputPath !== undefined;
+    outputPath = outputPathProvided ? outputPath.split('=')?.[1] : "";
+    return outputPath !== "" ? path.resolve(outputPath) : outputPath;  // To ensure input path is absolute
+}
+function getPortFromArgs(rawArgs) {
+    let port = rawArgs.find(val => val.startsWith(PORT_FLAG));
+    let portProvided = port !== undefined;
+    return portProvided ? Number(port.split('=')[1]) : undefined;
+}
+function getTrackChangesFromArgs(rawArgs) {
+    // If flag not passed do not track changes
+    let trackChanges = rawArgs.find(val => (val.startsWith(TRACK_CHANGES_FLAG) || val.startsWith(TRACK_CHANGES_SHORT_FLAG)));
+    if (trackChanges == undefined) {
+        return undefined;
+    }
+
+
+    // Check for argument passed (if any) 
+    let trackChangesSplit = trackChanges?.split('=') ?? [];
+    let arg = trackChangesSplit?.[1];
+    if (arg === HARD_RELOAD_ARG) {
+        return TrackChanges.HARD;
+    }
+    else if (arg === SOFT_RELOAD_ARG) {
+        return TrackChanges.SOFT;
+    }
+
+
+    return TrackChanges.SOFT;
+}
+function getConcurrencyFromArgs(rawArgs) {
+    let concurrency = rawArgs.find(val => val.startsWith(CONCURRENCY_FLAG));
+    let concurrencyProvided = concurrency !== undefined;
+    return concurrencyProvided ? Number(concurrency.split('=')[1]) : undefined;
+}
+function listenForKey(reloadCallback, hardReloadCallback, exitCallback) {
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.on("keypress", (chunk, key) => {
+        if (key && key.shift && key.name == 'r') {
+            hardReloadCallback();
+        }
+        else if (key && key.name == 'r') {
+            reloadCallback();
+        }
+        else if (key && key.sequence == '\x03') {
+            exitCallback();
+        }
+    });
+}
+
+
+// Main Methods
+export async function main() {
+
+    // Get all arguments
+    const rawArgs = process.argv.slice(2);
+
+
+    // Help flag check, Print out help message & return if passed 
+    if (rawArgs.includes(HELP_FLAG) || rawArgs.includes(HELP_SHORT_FLAG)) {
+        console.log(HELP_MESSAGE)
+        return;
+    }
+
+
+    // Assign input path
+    let inputPath = getInputPathFromArgs(rawArgs);
+
+
+    // Assign output path
+    let outputPath = getOutputPathFromArgs(rawArgs);
+
+
+    // Assign verbose
+    let toBeVerbose = rawArgs.includes(VERBOSE_FLAG) || rawArgs.includes(VERBOSE_SHORT_FLAG);
+
+
+    // Assign concurrency
+    let concurrency = getConcurrencyFromArgs(rawArgs);
+
+
+    // Assign to create only, Return if passed
+    let toCreateOnly = rawArgs.includes(CREATE_FLAG) || rawArgs.includes(CREATE_SHORT_FLAG);
+    if (toCreateOnly) {
+        try {
+            await createSite(inputPath, outputPath, null, undefined, { toBeVerbose });
+        }
+        catch (err) {
+            process.exitCode = 1;  // Exit with error code if not created successfully
+            log(`Failed to create site!\n${err?.stack}`);
+        }
+
+        return;
+    }
+
+
+    // Assign port
+    let port = getPortFromArgs(rawArgs);
+
+
+    // Assign tracking changes
+    let trackChanges = getTrackChangesFromArgs(rawArgs);
+
+
+    // Start hosting
+    let configs = {
+        ...(port !== undefined && { port }),
+        ...(concurrency !== undefined && { concurrency }),
+        ...(trackChanges !== undefined && { trackChanges }),
+        ...(toBeVerbose && { toBeVerbose }),
+    }
+    let hostMdx = new HostMdx(inputPath, outputPath, configs);
+    let hasHostingStarted = await hostMdx.start();
+    if (!hasHostingStarted) {
+        return;
+    }
+
+
+    // Assign cleanup function
+    const cleanup = async () => {
+        process.stdin.setRawMode(false);
+        await hostMdx.stop();
+        process.exit(0);  // Without this 'Ctrl + c' does not work DO NOT REMOVE
+    }
+
+
+    // Watch for key press
+    listenForKey(
+        async () => await hostMdx?.recreateSite(),
+        async () => await hostMdx?.recreateSite(true),
+        cleanup
+    );
+
+
+    // Watch for quit
+    process.on("exit", cleanup);
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+
+
+    // Log key press instructions
+    log(`(Press 'r' to reload, 'Shift + r' to hard reload, 'Ctrl+c' to exit)`);
+}
+
+
+main()