@songmu/mdhq 0.0.4 → 0.0.6

package/README.md

@@ -21,6 +21,7 @@ mdhq get https://example.com/article
 mdhq get https://example.com/article https://example.com/another-article
 cat urls.txt | mdhq get
 mdhq get --update https://example.com/article
+mdhq get --assets https://example.com/article
 mdhq get --no-assets https://example.com/article
 mdhq get --json --header 'Cookie: session=value' https://example.com/article
 mdhq list
@@ -29,8 +30,8 @@ mdhq root
 ```
 
 `mdhq get` accepts multiple URLs as arguments or one URL per line on standard
-input; both sources are merged. It prints one absolute Markdown path per URL
-to stdout by default. Warnings are written to stderr. `--json` writes one
+input; both sources are merged. It prints one root-relative Markdown path per
+URL to stdout by default. Warnings are written to stderr. `--json` writes one
 compact JSON result object per URL as JSON Lines. Results are written as soon
 as each URL finishes, so parallel requests can produce output in completion
 order rather than input order. If a later request fails, results already
@@ -102,7 +103,8 @@ const saved = await getPage({
 
 `convertHtml` performs extraction without fetching or writing files.
 `getPage` fetches, converts, optionally localizes images, adds frontmatter,
-and saves the document. Set `assets: false` or use `--no-assets` to keep
+and saves the document. Use `--assets` or `--no-assets` to override the
+configured asset behavior. Set `assets: false` or use `--no-assets` to keep
 absolute image URLs without creating `_assets`.
 
 Saved frontmatter uses Obsidian Web Clipper-compatible names such as `title`,

package/dist/cli.js

@@ -26,6 +26,13 @@ function parseHeaders(values) {
         };
     });
 }
+function toRootRelative(root, target) {
+    const relative = path.relative(root, target);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return target;
+    }
+    return relative;
+}
 async function readStdinUrls(stdin) {
     if (!stdin || stdin.isTTY) {
         return [];
@@ -65,6 +72,7 @@ export function createProgram(io = process) {
         .description("Fetch and save web pages.")
         .argument("[urls...]")
         .option("--root <path>", "storage root")
+        .option("--assets", "download images")
         .option("--no-assets", "do not download images")
         .option("--update", "update an existing page")
         .option("--user-agent <value>", "HTTP User-Agent")
@@ -78,6 +86,8 @@ export function createProgram(io = process) {
         if (requestedUrls.length === 0) {
             throw new MdhqError("INVALID_URL", "At least one URL is required");
         }
+        const loaded = await loadConfig();
+        const root = resolveRoot(options.root, loaded.config);
         const scheduler = new RequestScheduler();
         let nextIndex = 0;
         const worker = async () => {
@@ -90,15 +100,22 @@ export function createProgram(io = process) {
                 }
                 const result = await getPage({
                     url,
-                    ...(options.root ? { root: options.root } : {}),
-                    ...(options.assets === false ? { assets: false } : {}),
+                    root,
+                    ...(options.assets !== undefined ? { assets: options.assets } : {}),
                     update: options.update ?? false,
                     ...(options.userAgent ? { userAgent: options.userAgent } : {}),
                     headers: parseHeaders(options.header),
                     scheduler,
                     onWarning: (warning) => io.stderr.write(`warning: ${warning.message}\n`)
                 });
-                io.stdout.write(`${options.json ? JSON.stringify(result) : result.path}\n`);
+                const relativeResult = {
+                    ...result,
+                    path: toRootRelative(root, result.path),
+                    assets: result.assets.map((asset) => asset.path === undefined
+                        ? asset
+                        : { ...asset, path: toRootRelative(root, asset.path) })
+                };
+                io.stdout.write(`${options.json ? JSON.stringify(relativeResult) : relativeResult.path}\n`);
             }
         };
         const failures = [];

package/docs/configuration.md

@@ -106,10 +106,11 @@ Otherwise configuration overrides the built-in default.
 The CLI `--user-agent` option is passed as `GetPageOptions.userAgent` and
 therefore overrides configuration `userAgent`.
 
-The CLI `--no-assets` option passes `GetPageOptions.assets: false` and
-therefore overrides configuration `assets`. When asset localization is
-disabled, image destinations remain absolute URLs, the result contains no
-asset entries, and mdhq does not create `_assets`.
+The CLI `--assets` and `--no-assets` options pass
+`GetPageOptions.assets: true` and `GetPageOptions.assets: false`,
+respectively, and therefore override configuration `assets`. When asset
+localization is disabled, image destinations remain absolute URLs, the result
+contains no asset entries, and mdhq does not create `_assets`.
 
 Generic CLI `--header` values and library `headers` values are appended after
 mdhq creates its `Accept` and User-Agent headers. A generic `User-Agent` or

package/docs/specification.md

@@ -39,17 +39,18 @@ input. Both sources are merged, and up to eight URLs are processed in parallel.
 | `--header <header>` | Add an HTTP header. The option is repeatable and uses `Name: value` syntax. |
 | `--json` | Write one result per line as JSON Lines instead of only the Markdown path. |
 
-Without `--json`, stdout receives one absolute Markdown path per requested URL,
-with each path followed by a newline. Each result is written as soon as that
-URL finishes, so parallel requests can produce output in completion order
-rather than input order.
+Without `--json`, stdout receives one Markdown path per requested URL, relative
+to the effective storage root, with each path followed by a newline. Each
+result is written as soon as that URL finishes, so parallel requests can
+produce output in completion order rather than input order.
 Warnings are written to stderr.
 
 With `--json`, stdout contains one compact JSON object per requested URL,
-also written as soon as the URL finishes. Each line has this shape:
+also written as soon as the URL finishes. Markdown and asset paths are relative
+to the effective storage root. Each line has this shape:
 
 ```jsonl
-{"requestedUrl":"https://example.com/start","sourceUrl":"https://example.com/article","path":"/data/mdhq/example.com/article.md","status":"saved","assets":[],"warnings":[]}
+{"requestedUrl":"https://example.com/start","sourceUrl":"https://example.com/article","path":"example.com/article.md","status":"saved","assets":[],"warnings":[]}
 ```
 
 `status` is one of:
@@ -506,10 +507,11 @@ For images:
 
 Asset localization is enabled by default. It can be disabled with the
 top-level configuration field `assets: false`, library option
-`GetPageOptions.assets: false`, or CLI option `--no-assets`. The library
-option and CLI option take precedence over configuration. When disabled,
-HTTP(S) image destinations are kept as absolute URLs, the result `assets`
-array is empty, and `_assets` is not created.
+`GetPageOptions.assets: false`, or CLI option `--no-assets`. The CLI options
+`--assets` and `--no-assets` explicitly enable or disable localization and
+take precedence over configuration, as does the library option. When
+disabled, HTTP(S) image destinations are kept as absolute URLs, the result
+`assets` array is empty, and `_assets` is not created.
 
 mdhq does not rewrite ordinary links to other locally stored Markdown
 files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@songmu/mdhq",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Save web pages as Markdown in a ghq-inspired filesystem layout.",
   "type": "module",
   "bin": {