marksites 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# marksites
+
+Markdownを、GitHub風のスタイルを埋め込んだ単独のHTMLファイルへ変換するTypeScriptライブラリです。
+
+## インストール
+
+```sh
+npm install
+npm run build
+```
+
+## ライブラリとして使う
+
+```ts
+import { markdownToHtml } from "marksites";
+
+const html = markdownToHtml("# Hello", { title: "My page" });
+```
+
+更新日時を表示する場合は、ISO 8601形式で指定します。CLI変換ではMarkdownファイルの最終更新日時が自動的に使用されます。
+
+```ts
+const html = markdownToHtml(markdown, {
+  modifiedAt: "2026-07-17T03:00:00.000Z",
+});
+```
+
+見出しレベル2から6までの目次と、GitHub互換の見出しアンカーが自動生成されます。ファイルツリーはGitHubのFilesペインと同様、画面左端へ接する全高のサイドバーとして常時表示し、本文を中央、`目次`とコメントを画面右側へ配置します。左サイドバーはヘッダーの四角いペインアイコンで折り畳むことができ、閉じると本文が左へ広がります。閉じた場合はページ上部に同形の復帰アイコンと、従来どおりポップオーバーでファイル一覧を開く`ファイル`ボタンを並べます。サイドバーの閉状態は`file-sidebar=closed`、ポップオーバーは`marksites-files=open`、開いたフォルダは短縮IDを値とする`open` GETパラメータでページ間に引き継がれます。ファイルパス直後のアイコンでパスをコピーでき、右端にはMarkdownの更新日時をブラウザのローカルタイムゾーンで`YYYY-MM-DD HH:mm:ss`形式にして表示します。タイムゾーン名やUTCオフセットは表示しません。JavaScript実行前はUTCの日時を同じ形式で表示します。現在位置に対応する見出しもハイライトされます。狭い画面では右サイドバーを本文上部、ファイルサイドバーを必要なときだけ開く固定オーバーレイとして表示します。
+
+左ファイルサイドバーは幅280pxとし、開閉アイコンは枠線なしで表示します。
+
+画面上端には固定ヘッダーを表示します。右上の月・太陽アイコンでライト／ダークモードを切り替え、地球アイコンで生成UIの日本語／英語を切り替えます。Markdown本文、見出し、ファイル名、コメント本文は翻訳対象にしません。選択状態は`theme`と`lang` GETパラメータでページ間に引き継がれます。
+
+```ts
+const html = markdownToHtml(markdown, {
+  tableOfContents: {
+    title: "目次",
+    minDepth: 2,
+    maxDepth: 4,
+  },
+});
+```
+
+目次を無効にする場合は `tableOfContents: false` を指定します。見出しのアンカーIDはそのまま生成されます。
+
+言語名を指定したコードブロックは、`highlight.js` によって自動的にハイライトされます。
+コードブロックには、コードをクリップボードへコピーするボタンと、長い行の折り返しを切り替えるボタンも表示されます。
+
+````markdown
+```typescript
+const greeting: string = "Hello";
+console.log(greeting);
+```
+````
+
+ハイライトを無効にすることもできます。
+
+```ts
+const html = markdownToHtml(markdown, { highlight: false });
+```
+
+## CLIとして使う
+
+```sh
+npx marksites README.md README.html
+```
+
+入力と出力を両方省略すると、カレントディレクトリ配下のMarkdownを`./marksites/`へ変換します。
+
+```sh
+npx marksites
+# npx marksites . marksites と同じ
+```
+
+単一Markdownの出力先を省略した場合も、`./marksites/`へ同じbasenameのHTMLを保存します。
+
+フォルダを指定すると、配下の `.md` と `.markdown` を再帰的に変換します。出力先でも元のフォルダ階層を維持し、各ページの左側にファイル名で絞り込めるファイルツリー、本文上部に現在のファイルパスを示すパンくずを表示します。コメントが1件以上あるファイルには件数バッジを表示し、上位フォルダには配下の有効コメント合計件数を表示します。Markdownファイル間の相対リンクは `.html` へ書き換えられます。
+
+```sh
+npx marksites docs public
+```
+
+ディレクトリ変換の出力先を省略した場合は、カレントディレクトリの`marksites/`へ出力します。
+
+```sh
+npx marksites docs
+# ./marksites/ に出力
+```
+
+プロジェクトルートを対象にする場合、`.git`、`node_modules`、`dist`、`coverage`は探索対象から除外されます。
+
+入力フォルダ配下の`.gitignore`を読み込み、Gitと同じパターン規則で除外されたファイルとフォルダを変換対象から外します。ネストした`.gitignore`と`!`による再包含にも対応します。また、`.marksites-build.json`を持つ既存の生成フォルダと、今回指定された出力フォルダは常に探索対象外です。
+
+2回目以降はMarkdown本文、コメント、ファイル構成、レンダー設定のSHA-256を比較し、影響したHTMLだけを再生成します。管理情報は出力先直下の `.marksites-build.json`、文書ごとのメタデータは各HTMLに隣接する `.<名前>.json` に保存されます。このJSONは再変換時にも上書きされません。現在はコメント情報を格納し、将来は文書固有のほかの情報も管理できるファイルとして扱います。
+
+### コメントを編集する
+
+軽量ローカルサーバーの起動中だけ、本文の選択範囲へコメントを追加・編集・削除できます。
+
+右サイドバーでは目次と現在ページのコメント一覧をタブで切り替えられます。タブにはコメント件数が表示され、コメントを選ぶと本文の対象箇所へ移動します。一覧先頭の追加ボタンから、範囲を選択しない文書全体へのコメントも作成できます。ヘッダーは固定され、各パネルは独立してスクロールします。
+
+```sh
+npx marksites serve docs public/docs
+# 通常は http://127.0.0.1:3000
+```
+
+入力・出力を省略して、カレントディレクトリを`./marksites/`へ変換・配信することもできます。
+
+```sh
+npx marksites serve
+# npx marksites serve . marksites と同じ
+```
+
+`--host`、`--port`、`--open`を指定できます。ポートを省略すると3000を使用し、すでに使用中なら3001、3002の順に空きポートを自動選択します。`--port`を明示した場合は指定ポートだけを使用し、競合時はエラーになります。`--port 0`ではOSに空きポートを割り当てさせることもできます。実際のURLは起動時に表示され、`--open`もそのURLを開きます。
+
+サーバーは起動時に差分変換を行い、アイドル中のファイル監視や定期処理は行いません。停止後もコメントはHTMLへ埋め込まれているため、生成HTMLを`file://`で閲覧できます。この場合、コメントは閲覧専用です。
+
+`--open`はWindows、macOS、Linuxに加えてWSLからWindows側のブラウザを開く処理にも対応します。ブラウザ起動コマンドが見つからない場合もサーバーは停止せず、表示されたURLを手動で開けます。
+
+入力フォルダに`index.md`または`index.markdown`がある場合は、そのページを`/`で表示します。存在しない場合は、変換対象のファイルパスを並べたときの先頭ページを表示します。
+
+詳細な設計と運用上の注意は[ローカルサーバー設計](docs/local-server-design.md)を参照してください。
+
+### Webアプリの静的ファイルとして公開する
+
+Next.jsやVue、ViteなどのWebアプリで公開する場合は、アプリの静的ファイル用ディレクトリ配下を出力先に指定します。
+
+```sh
+npx marksites docs public/docs
+```
+
+例えば `docs/index.md` と `docs/guide.md` は、それぞれ `public/docs/index.html` と `public/docs/guide.html` に変換されます。Webアプリからは `/docs/index.html` と `/docs/guide.html` への通常のリンクとして参照できます。
+
+Webアプリをビルドする前にHTMLを生成するよう、npmスクリプトへ追加できます。
+
+```json
+{
+  "scripts": {
+    "build:docs": "marksites docs public/docs",
+    "build": "npm run build:docs && next build"
+  }
+}
+```
+
+Viteを使用する場合は、`next build` を `vite build` に置き換えます。
+
+## 開発
+
+```sh
+npm test
+```
+
+Markdownの解析には [marked](https://marked.js.org/)、表示スタイルには [github-markdown-css](https://github.com/sindresorhus/github-markdown-css)、コードのシンタックスハイライトには [highlight.js](https://highlightjs.org/) を使用しています。

package/dist/annotations/model.d.ts

@@ -0,0 +1,29 @@
+export interface AnnotationSelection {
+    exact: string;
+    prefix: string;
+    suffix: string;
+    headingId: string | null;
+    startOffset: number;
+    endOffset: number;
+}
+export interface Annotation {
+    id: string;
+    selection: AnnotationSelection;
+    comment: {
+        body: string;
+        author: string | null;
+    };
+    status: "open" | "archived";
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AnnotationDocument {
+    schemaVersion: 1;
+    document: string;
+    revision: number;
+    annotations: Annotation[];
+}
+export declare function emptyAnnotationDocument(document: string): AnnotationDocument;
+export declare function countActiveAnnotations(data: AnnotationDocument): number;
+export declare function validateAnnotationDocument(value: unknown, expectedDocument?: string): AnnotationDocument;
+export declare function validateAnnotation(value: unknown): asserts value is Annotation;

package/dist/annotations/model.js

@@ -0,0 +1,56 @@
+export function emptyAnnotationDocument(document) {
+    return { schemaVersion: 1, document, revision: 0, annotations: [] };
+}
+export function countActiveAnnotations(data) {
+    return data.annotations.filter((annotation) => annotation.status === "open")
+        .length;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function validateAnnotationDocument(value, expectedDocument) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        typeof value.document !== "string" ||
+        !Number.isSafeInteger(value.revision) ||
+        Number(value.revision) < 0 ||
+        !Array.isArray(value.annotations)) {
+        throw new Error("Invalid annotation document");
+    }
+    if (expectedDocument !== undefined && value.document !== expectedDocument) {
+        throw new Error(`Annotation document path must be ${expectedDocument}`);
+    }
+    for (const item of value.annotations)
+        validateAnnotation(item);
+    return value;
+}
+export function validateAnnotation(value) {
+    if (isRecord(value) && value.status === "resolved") {
+        value.status = "archived";
+    }
+    if (!isRecord(value) ||
+        typeof value.id !== "string" ||
+        value.id.length === 0 ||
+        !isRecord(value.selection) ||
+        typeof value.selection.exact !== "string" ||
+        typeof value.selection.prefix !== "string" ||
+        typeof value.selection.suffix !== "string" ||
+        !(typeof value.selection.headingId === "string" ||
+            value.selection.headingId === null) ||
+        !Number.isSafeInteger(value.selection.startOffset) ||
+        !Number.isSafeInteger(value.selection.endOffset) ||
+        Number(value.selection.startOffset) < 0 ||
+        Number(value.selection.endOffset) < Number(value.selection.startOffset) ||
+        !isRecord(value.comment) ||
+        typeof value.comment.body !== "string" ||
+        !(typeof value.comment.author === "string" || value.comment.author === null) ||
+        (value.status !== "open" && value.status !== "archived") ||
+        typeof value.createdAt !== "string" ||
+        typeof value.updatedAt !== "string") {
+        throw new Error("Invalid annotation");
+    }
+    if (Number.isNaN(Date.parse(value.createdAt)) ||
+        Number.isNaN(Date.parse(value.updatedAt))) {
+        throw new Error("Invalid annotation timestamp");
+    }
+}

package/dist/annotations/storage.d.ts

@@ -0,0 +1,4 @@
+import { type AnnotationDocument } from "./model.js";
+export declare function serializeAnnotations(value: AnnotationDocument): string;
+export declare function readAnnotations(path: string, document?: string): Promise<AnnotationDocument>;
+export declare function writeAnnotations(path: string, value: AnnotationDocument): Promise<void>;

package/dist/annotations/storage.js

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { atomicWriteFile } from "../utils/files.js";
+import { emptyAnnotationDocument, validateAnnotationDocument, } from "./model.js";
+export function serializeAnnotations(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export async function readAnnotations(path, document) {
+    let source;
+    try {
+        source = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT" &&
+            document !== undefined) {
+            const value = emptyAnnotationDocument(document);
+            await atomicWriteFile(path, serializeAnnotations(value));
+            return value;
+        }
+        throw error;
+    }
+    try {
+        return validateAnnotationDocument(JSON.parse(source), document);
+    }
+    catch (error) {
+        throw new Error(`Invalid annotation JSON at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function writeAnnotations(path, value) {
+    validateAnnotationDocument(value);
+    await atomicWriteFile(path, serializeAnnotations(value));
+}

package/dist/cli/directory.d.ts

@@ -0,0 +1,4 @@
+export { convertDirectory, convertDirectoryDetailed, } from "../conversion/directory.js";
+export { convertFile } from "../conversion/single-file.js";
+export { BUILD_MANIFEST } from "../conversion/manifest.js";
+export type { ConversionResult } from "../conversion/types.js";

package/dist/cli/directory.js

@@ -0,0 +1,3 @@
+export { convertDirectory, convertDirectoryDetailed, } from "../conversion/directory.js";
+export { convertFile } from "../conversion/single-file.js";
+export { BUILD_MANIFEST } from "../conversion/manifest.js";

package/dist/cli/open-browser.d.ts

@@ -0,0 +1,12 @@
+import { type ChildProcess } from "node:child_process";
+type SpawnBrowser = (command: string, args: string[], options: {
+    detached: true;
+    stdio: "ignore";
+}) => ChildProcess;
+interface BrowserOpenEnvironment {
+    platform?: NodeJS.Platform;
+    environment?: NodeJS.ProcessEnv;
+    spawnBrowser?: SpawnBrowser;
+}
+export declare function openBrowser(url: string, environment?: BrowserOpenEnvironment): Promise<boolean>;
+export {};

package/dist/cli/open-browser.js

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+function browserCommands(url, platform, environment) {
+    if (platform === "win32") {
+        return [{ command: "cmd.exe", args: ["/d", "/s", "/c", "start", "", url] }];
+    }
+    if (platform === "darwin")
+        return [{ command: "open", args: [url] }];
+    const isWsl = Boolean(environment.WSL_DISTRO_NAME || environment.WSL_INTEROP);
+    return isWsl
+        ? [
+            { command: "cmd.exe", args: ["/d", "/s", "/c", "start", "", url] },
+            { command: "xdg-open", args: [url] },
+        ]
+        : [{ command: "xdg-open", args: [url] }];
+}
+function tryCommand(command, spawnBrowser) {
+    return new Promise((resolve) => {
+        const child = spawnBrowser(command.command, command.args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", () => resolve(false));
+        child.once("spawn", () => {
+            child.unref();
+            resolve(true);
+        });
+    });
+}
+export async function openBrowser(url, environment = {}) {
+    const spawnBrowser = environment.spawnBrowser ?? spawn;
+    const commands = browserCommands(url, environment.platform ?? process.platform, environment.environment ?? process.env);
+    for (const command of commands) {
+        if (await tryCommand(command, spawnBrowser))
+            return true;
+    }
+    return false;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { access, readFile, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { convertDirectoryDetailed } from "./conversion/directory.js";
+import { convertFile } from "./conversion/single-file.js";
+import { MARKSITES_RESERVED_PATH } from "./server/constants.js";
+import { startMarksitesServer } from "./server/server.js";
+import { openBrowser } from "./cli/open-browser.js";
+function usage() {
+    console.error("Usage:\n  marksites [input.md|input-directory] [output.html|output-directory]\n  marksites serve [input-directory] [output-directory] [--host HOST] [--port PORT] [--open]");
+    process.exit(1);
+}
+function report(result) {
+    console.log(`Converted ${result.converted}; skipped ${result.skipped}; deleted ${result.deleted}; annotation files created ${result.annotationsCreated}; moved ${result.annotationsMoved}`);
+    for (const path of result.orphanedAnnotations)
+        console.warn(`Orphaned annotation JSON preserved: ${path}`);
+}
+async function serve(args) {
+    const positional = [];
+    let host = "127.0.0.1", port, shouldOpen = false;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === "--open") {
+            shouldOpen = true;
+            continue;
+        }
+        if (argument === "--host" || argument === "--port") {
+            const value = args[++index];
+            if (!value)
+                usage();
+            if (argument === "--host")
+                host = value;
+            else {
+                port = Number(value);
+                if (!Number.isInteger(port) || port < 0 || port > 65535)
+                    throw new Error(`Invalid port: ${value}`);
+            }
+            continue;
+        }
+        if (argument.startsWith("--"))
+            throw new Error(`Unknown option: ${argument}`);
+        positional.push(argument);
+    }
+    if (positional.length > 2)
+        usage();
+    const inputArgument = positional[0] ?? ".";
+    const input = resolve(inputArgument);
+    if (!(await stat(input)).isDirectory())
+        throw new Error(`serve input must be a directory: ${inputArgument}`);
+    const initial = await convertDirectoryDetailed(input, positional[1]);
+    report(initial);
+    const output = initial.outputRoot;
+    try {
+        await access(join(output, MARKSITES_RESERVED_PATH));
+        throw new Error(`Reserved output path exists: ${MARKSITES_RESERVED_PATH}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const manifest = JSON.parse(await readFile(join(output, ".marksites-build.json"), "utf8"));
+    const documents = new Map(Object.entries(manifest.files).map(([document, value]) => [
+        document,
+        value.annotations,
+    ]));
+    const projectId = createHash("sha256")
+        .update(input)
+        .digest("hex")
+        .slice(0, 16);
+    const outputs = Object.values(manifest.files)
+        .map((value) => value.output)
+        .sort((left, right) => left.localeCompare(right, "en"));
+    const entryPath = outputs.includes("index.html") ? "index.html" : outputs[0];
+    const server = await startMarksitesServer({
+        outputRoot: output,
+        entryPath,
+        host,
+        port,
+        fallbackPort: port === undefined,
+        projectId,
+        projectName: basename(input),
+        documents,
+        onAnnotationsChange: async () => {
+            await convertDirectoryDetailed(input, output);
+        },
+    });
+    console.log(`marksites server: ${server.url}`);
+    if (shouldOpen) {
+        const opened = await openBrowser(server.url);
+        if (!opened) {
+            console.warn(`Could not open a browser automatically. Open ${server.url} manually.`);
+        }
+    }
+    await new Promise((done, fail) => {
+        let closing = false;
+        const close = () => {
+            if (closing)
+                return;
+            closing = true;
+            server.close().then(done, fail);
+        };
+        process.once("SIGINT", close);
+        process.once("SIGTERM", close);
+    });
+}
+async function main() {
+    if (process.argv[2] === "serve")
+        return serve(process.argv.slice(3));
+    const inputArgument = process.argv[2] ?? ".";
+    const input = resolve(inputArgument);
+    const inputStat = await stat(input);
+    const outputArgument = process.argv[3];
+    if (inputStat.isDirectory()) {
+        report(await convertDirectoryDetailed(input, outputArgument));
+        return;
+    }
+    if (!inputStat.isFile())
+        throw new Error(`Input is not a file or directory: ${inputArgument}`);
+    console.log(`Created ${await convertFile(input, outputArgument)}`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/conversion/directory.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionResult } from "./types.js";
+export declare function convertDirectoryDetailed(input: string, outputArgument?: string): Promise<ConversionResult>;
+export declare function convertDirectory(input: string, outputArgument?: string): Promise<number>;