@cosense-toolbox/astro 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qaynam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# @cosense-toolbox/astro
+
+Cosense (旧 Scrapbox) の記法で書いた `.csn` / `.csnx` を、Astro のページと content collection で使うための統合。
+中身は [`@cosense-toolbox/cosense-x`](../cosense-x) のコンパイラ。
+
+> **beta**：公開 API はまだ変わりうる。
+
+動く例は [`examples/astro-blog`](../../examples/astro-blog) にある。
+
+## 設定
+
+```js
+// astro.config.mjs
+import svelte from "@astrojs/svelte"
+import cosense from "@cosense-toolbox/astro"
+import { defineConfig } from "astro/config"
+
+export default defineConfig({
+  integrations: [
+    svelte(),
+    cosense({
+      components: "./src/components/cosense.ts",
+      pageUrl: (page) => `/posts/${encodeURIComponent(page.slug)}/`,
+      tagUrl: (tag) => `/tags/${encodeURIComponent(tag)}/`,
+      lint: { unresolvedLinks: "error" },
+    }),
+  ],
+})
+```
+
+| オプション            | 内容                                                                                                                                                                        |
+| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `components`          | すべてのページに渡すコンポーネントを default export するモジュールの、プロジェクトのルートからのパス                                                                        |
+| `pageUrl`             | リンク先のページの URL。`{ id, title, slug }` を受け取る。`id` はプロジェクトのルートからのパス                                                                             |
+| `tagUrl` `projectUrl` | `compile` の同名のオプションと同じ                                                                                                                                          |
+| `unresolvedLinks`     | サイトに無いページへのリンクの出し方。`'text'` (既定) はテキスト、`'link'` はタイトルから作った URL へのリンクにする                                                        |
+| `lint`                | ビルドの前にリンク切れを調べる。`{ unresolvedLinks?, frontmatter? }`。省略すると調べない。[下を参照](#リンク切れを調べる)                                                   |
+| `parseOptions`        | パースの設定。parser の `parse` のオプション (`extensions` など) がそのまま渡る                                                                                             |
+| `renderOptions`       | 描画の設定。parser の `toHast` のオプション (`extensions` `handlers` `classNames` `showPads` `iconImageUrl`) と `title` がそのまま渡る。色付けは `syntaxHighlight` で決める |
+| `rehypePlugins`       | `compile` の同名のオプションと同じ                                                                                                                                          |
+| `syntaxHighlight`     | コードブロックの色付け。既定の `'astro'` は `markdown.shikiConfig` に従う。`false` で無効、関数で自前の色付け。[下を参照](#コードブロックの色付け)                          |
+| `assets`              | Cosense 上の画像とファイルを、ビルド時に取ってきてサイトの中に置く。`{ pat?, origin?, links? }`、または `false` で無効。既定は有効                                          |
+
+## リンク切れを調べる
+
+`lint` を渡すと、ビルドの前と、開発サーバーの起動時・ページを変えたときに、`srcDir` の下の `.csn` / `.csnx` を読み、サイトに無いページへの `[リンク]` を調べる。開発中は `'error'` でも止めず、ログに出すだけにする。
+判定はエディタの診断 ([`@cosense-toolbox/lsp`](../lsp)) と `csn-lsp check` と同じ関数で、パースにはこの統合の
+`parseOptions` を使う。エディタで警告されるものと、ビルドで止まるものが一致する。
+
+| `lint` のオプション | 内容                                                                                                             | 既定        |
+| :------------------ | :--------------------------------------------------------------------------------------------------------------- | :---------- |
+| `unresolvedLinks`   | `'off'` / `'hint'` / `'information'` / `'warning'` / `'error'`。`'error'` ならビルドを止め、それ以外はログに出す | `'warning'` |
+| `frontmatter`       | 1 行目の `---` を frontmatter (YAML) として飛ばすか                                                              | `true`      |
+
+ページの題名はファイルの 1 行目で、大文字小文字と、空白と `_` の違いは無視して比べる。`#タグ` と
+`[/別プロジェクト/ページ]` は調べない。
+
+## Cosense 上の画像とファイル
+
+Cosense にアップロードした画像やファイル (`https://scrapbox.io/files/…`) とアイコン (`/api/pages/…/icon`) は、ビルド時に取ってきて `{base}/_cosense/` に置き、HTML の URL をそこに差し替える。
+
+- これらのファイルは別のサイトの `<img>` からは読めない (`Cross-Origin-Resource-Policy: same-origin`)
+- リダイレクト先の URL は数分で切れる
+- そのため、静的なサイトで表示するにはサイトの中に置くしかない
+
+```js
+cosense({
+  // 非公開プロジェクトの画像を取るときは PAT を渡す。Cosense への要求にだけ付ける
+  assets: { pat: process.env.COSENSE_PAT },
+})
+```
+
+- `.csn` / `.csnx` の中の画像は自動で差し替える
+- ファイル名は `{元の URL のハッシュ}.{拡張子}`。アイコンは `{ハッシュ}_{ユーザー名}.{拡張子}`
+  - 同じ URL は何度ビルドしても同じ名前になる
+  - ハッシュから元の URL は分からないので、非公開プロジェクトのファイル ID は出ない
+- 取ってきたファイルは Astro のキャッシュのディレクトリに残す
+  - アップロードしたファイルは中身が変わらないので、次のビルドでは取り直さない
+  - アイコンは差し替えられることがあるので、ビルドのたびに取り直す
+  - 出力先には、そのビルドで使ったファイルだけを写す
+- 取れなかったファイルは警告を出し、元の URL のまま出す
+- dev サーバーでは、同じパスで配信する
+- **非公開プロジェクトの画像も、公開するサイトに置かれる**。公開してよいものだけを書くこと
+
+リンクした Cosense のファイル (`[https://scrapbox.io/files/x.zip]` など、`<a href>` になるもの) は、既定では元の URL のまま出す。
+公開プロジェクトならクリックして開ける (Cross-Origin-Resource-Policy は画面の遷移には効かない)。
+非公開プロジェクトのファイルは見に来た人が開けないので、`links: 'download'` で画像と同じくサイトに置く。
+
+```js
+cosense({
+  assets: { pat: process.env.COSENSE_PAT, links: "download" },
+})
+```
+
+`toHtml` などで自分で描画するページは、`virtual:cosense-x/assets` の `localizeCosenseAssets` に HTML を通す。
+アイコンの URL は `cosenseIconUrl` で作る。
+
+```astro
+---
+import { cosenseIconUrl, fetchPageText } from "@cosense-toolbox/cosense-x/fetch"
+import { parse } from "@cosense-toolbox/parser"
+import { toHtml } from "@cosense-toolbox/parser/html"
+import { localizeCosenseAssets } from "virtual:cosense-x/assets"
+
+const project = "help-jp"
+const text = await fetchPageText(project, "ブラケティング")
+const html = await localizeCosenseAssets(
+  toHtml(parse(text), { iconImageUrl: (icon) => cosenseIconUrl(project, icon.user) }),
+)
+---
+
+<article class="cosense" set:html={html} />
+```
+
+差し替えられるのは、ページをビルド時に描画するとき (静的なページと prerender) と dev サーバーだけ。実行時に描画する SSR では元の URL のまま返す。
+
+## コードブロックの色付け
+
+`.csn` / `.csnx` のコードブロック (`code:hello.js`) は、`.md` / `.mdx` と同じく Astro の `markdown.syntaxHighlight` と `markdown.shikiConfig` の設定で shiki が色付けする。
+`components` に登録しなくてよい。
+
+```js
+export default defineConfig({
+  markdown: { shikiConfig: { theme: "github-light" } },
+  integrations: [cosense()],
+})
+```
+
+- 言語はファイル名の拡張子から決める。`code:hello.js` なら `js`、`code:python` なら `python`
+- shiki が知らない言語と `excludeLangs` の言語は、色付けせずに出す
+- `theme` / `themes` / `defaultColor` / `langs` / `langAlias` / `transformers` を使う。`wrap` は使わない。長い行は `@cosense-toolbox/style` が折り返す
+- `markdown.syntaxHighlight` が `'prism'` のときは色付けしない (相当するものが無い)
+
+`syntaxHighlight: false` で色付けをやめる。関数を渡すと、shiki の代わりにそれで色付けする。形は `compile` の `renderOptions.highlight` と同じ。
+
+```js
+cosense({
+  syntaxHighlight: (code, language) => myHighlighter(code, language), // hast か null を返す
+})
+```
+
+`toHtml` で自分で描画するページは、`toHtml` の `highlight` に shiki を直接渡す。
+テーマなどの設定を 1 つのファイルにまとめ、`astro.config.mjs` とページの両方から読むと、`.md` / `.csn` と見た目が揃う。
+
+```ts
+// src/shiki.ts
+import type { HastHighlighter } from "@cosense-toolbox/parser/html"
+import type { ShikiConfig } from "astro"
+import { createHighlighter } from "shiki"
+
+export const shikiConfig = { theme: "github-light" } satisfies Partial<ShikiConfig>
+
+/** toHtml は highlight を同期で呼ぶので、使う言語は先に読み込んでおく */
+export const createCodeHighlight = async (langs: string[]): Promise<HastHighlighter> => {
+  const shiki = await createHighlighter({ themes: [shikiConfig.theme], langs })
+  // shiki の hast はそのまま返してよい。<pre><code> は剥がされ、テーマの色はコードブロックに移る
+  return (code, lang) =>
+    shiki.getLoadedLanguages().includes(lang)
+      ? shiki.codeToHast(code, { lang, theme: shikiConfig.theme })
+      : null // 読み込んでいない言語は色付けしない
+}
+```
+
+```js
+// astro.config.mjs
+import { shikiConfig } from "./src/shiki.ts"
+
+export default defineConfig({
+  markdown: { shikiConfig },
+  integrations: [cosense()],
+})
+```
+
+```astro
+---
+import { parse } from "@cosense-toolbox/parser"
+import { toHtml } from "@cosense-toolbox/parser/html"
+import { createCodeHighlight } from "../shiki"
+
+const highlight = await createCodeHighlight(["js", "ts"])
+const html = toHtml(parse(text), { highlight })
+---
+
+<article class="cosense" set:html={html} />
+```
+
+### 行番号
+
+`@cosense-toolbox/parser/html` の `codeLineNumbers()` を描画の拡張 (`renderOptions.extensions`) に渡すと、コードブロックの本体行に行番号 (`data-line`) が付く。
+番号の表示は `@cosense-toolbox/style` と `@cosense-toolbox/tailwind` が持っていて、行の左の余白に出す。本文の位置は変わらず、コピーしたときに番号は入らない。
+
+```js
+// astro.config.mjs
+import { codeLineNumbers } from "@cosense-toolbox/parser/html"
+
+cosense({ renderOptions: { extensions: [codeLineNumbers()] } })
+```
+
+`toHtml` で描画するページは、`toHtml(page, { extensions: [codeLineNumbers()] })` のように渡す。
+
+- 番号の色は `--cosense-line-number` で変えられる
+- エディタと同じく、本文の左に番号の欄を取る。欄の幅はブロックの最後の番号の桁数で決まり、同じブロックの行はそろう
+- shiki で色付けしたブロックも、色付けしないブロックと同じく 1 行ずつの要素になるので番号が付く
+- 行をまたぐ出力を返すハイライタ (highlight.js など) でひと塊になったブロックには付かない
+
+### テーブルのセル
+
+セルの中は Cosense Web と同じく、リンクの記法だけを読む。行と同じく記法を読みたいときはパースの拡張 `tableCellNotation()` を、セルの中の `\n` のような文字の並びを改行にしたいときは描画の拡張 `tableCellLineBreaks()` を渡す。
+
+```js
+// astro.config.mjs
+import { tableCellLineBreaks } from "@cosense-toolbox/parser/html"
+import { tableCellNotation } from "@cosense-toolbox/parser/extensions"
+
+cosense({
+  parseOptions: { extensions: [tableCellNotation()] },
+  renderOptions: { extensions: [tableCellLineBreaks("\\n")] },
+})
+```
+
+## content collection
+
+```ts
+// src/content.config.ts
+import { defineCollection } from "astro:content"
+import { glob } from "astro/loaders"
+
+const posts = defineCollection({
+  loader: glob({ pattern: "**/*.{csn,csnx}", base: "./src/content/posts" }),
+})
+
+export const collections = { posts }
+```
+
+`data` には frontmatter に加えて `title` / `slug` / `description` / `image` / `tags` / `draft` が入る。
+Cosense では 1 行目がタイトルなので、frontmatter に書かなくても `title` がある。
+`slug` が entry の id になる。
+
+```astro
+---
+import { render } from "astro:content"
+const { Content } = await render(post)
+---
+
+<Content />
+```
+
+## ページ
+
+`src/pages` に `.csn` / `.csnx` を置くと、そのままページになる。
+frontmatter の `layout` にレイアウトの `.astro` を指定すると、本文をその default のスロットに入れる。
+レイアウトには `frontmatter` と `metadata` が props で渡る。
+
+```
+---
+layout: ../layouts/Page.astro
+---
+このサイトについて
+本文
+```
+
+## リンクグラフ
+
+`virtual:cosense-x/graph` から、`src` の下のすべての `.csn` / `.csnx` のリンクグラフを読める。
+グラフの id は、content collection の entry の `filePath` と同じ形 (プロジェクトのルートからのパス)。
+
+```astro
+---
+import graph from "virtual:cosense-x/graph"
+const backlinks = graph.backlinks[post.filePath]
+const twoHop = graph.twoHop[post.filePath]
+---
+```
+
+## コンポーネント
+
+`.csnx` の `<Name />` の行には、`components` に指定したモジュールか、`<Content components={...} />` で渡したものが使われる。
+Astro の中で描画されるので、Svelte などのコンポーネントも渡せる。
+
+ブラウザで動かすための `client:*` ディレクティブは `.astro` の中でしか付けられない。
+`.astro` のコンポーネントで包んでから渡す。
+
+```astro
+---
+// CounterIsland.astro
+import Counter from "./Counter.svelte"
+---
+
+<Counter client:load {...Astro.props} />
+```
+
+## 仕組み
+
+- `.csn` / `.csnx` を Vite のプラグインで JS にする。`jsxImportSource` は `astro`
+- リンクの解決には全ページのタイトルが要る。そのため、ビルドの最初に `src` の下を全部読んで索引を作る。dev サーバーでは、どれか 1 ページが変わると索引を作り直して再読み込みする
+- 描画には `astro:jsx` レンダラを使う。`@astrojs/mdx` と同じものなので、両方入れてもぶつからない
+- ページの拡張子と content collection の形式の登録には、`@astrojs/mdx` も使っている Astro の非公開のフック (`addPageExtension` / `addContentEntryType`) を使っている。Astro の更新で動かなくなる可能性がある
+
+## ライセンス
+
+MIT。

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+import { Graph, GraphPage, TwoHopGroup } from "@cosense-toolbox/cosense-x/graph";
+import { Effect, Option } from "effect";
+import "@cosense-toolbox/cosense-x/fetch";
+import { CheckSiteOptions } from "@cosense-toolbox/lsp/check";
+import { CompileOptions, HastHighlighter, RenderOptions } from "@cosense-toolbox/cosense-x";
+import { AstroIntegration } from "astro";
+import "@cosense-toolbox/parser";
+import "vite";
+//#region src/highlight.d.ts
+/**
+ * `.csn` / `.csnx` のコードブロックの色付け。
+ * `'astro'` は `markdown.syntaxHighlight` / `markdown.shikiConfig` に従い、関数なら自分で色付けする。
+ */
+type SyntaxHighlightOption = "astro" | false | HastHighlighter;
+/**
+ * 利用者が統合に渡す描画の設定。色付けは統合が `syntaxHighlight` から作って渡すので含めない。
+ */
+type AstroRenderOptions = Omit<RenderOptions, "highlight">;
+//#endregion
+//#region src/lint.d.ts
+interface CosenseLintOptions {
+  /**
+   * サイトに無いページへのリンクの知らせ方。`'error'` ならビルドを止める。
+   * `'off'` / `'hint'` / `'information'` / `'warning'` / `'error'`。
+   *
+   * @defaultValue `'warning'`
+   */
+  readonly unresolvedLinks?: CheckSiteOptions["unresolvedLinks"];
+  /**
+   * 1 行目の `---` を frontmatter (YAML) として飛ばすか。
+   *
+   * @defaultValue `true`
+   */
+  readonly frontmatter?: boolean;
+}
+//#endregion
+//#region src/vite-plugin.d.ts
+interface AstroCompileOptions extends Omit<CompileOptions, "filePath" | "format" | "index" | "jsxImportSource" | "elementAttributeNameCase" | "renderOptions" | "unresolved"> {
+  /**
+   * サイトに無いページへのリンクの出し方。`'text'` はテキストにする (非公開のページの名前が
+   * URL に漏れない)。`'link'` はタイトルから作った URL へのリンクにする。
+   * リンク切れを知らせるのは `lint` の役目。
+   *
+   * @defaultValue `'text'`
+   */
+  readonly unresolvedLinks?: "text" | "link";
+  /**
+   * 描画の設定。parser の `toHast` のオプションがそのまま渡る
+   * (`extensions` / `handlers` / `classNames` / `showPads` / `iconImageUrl` / `title`)。
+   * コードブロックの色付けは `syntaxHighlight` で決める。
+   */
+  readonly renderOptions?: AstroRenderOptions;
+}
+//#endregion
+//#region src/index.d.ts
+interface CosenseAssetsOptions {
+  /**
+   * Cosense の Personal Access Token。非公開プロジェクトの画像を取ってくるときに渡す。
+   * Cosense への要求にだけ付け、リダイレクト先 (Google Cloud Storage や Gyazo) には送らない。
+   *
+   * @example `process.env.COSENSE_PAT`
+   */
+  readonly pat?: string;
+  /** Cosense の origin。 @defaultValue `https://scrapbox.io` */
+  readonly origin?: string;
+  /**
+   * リンクした Cosense のファイル (`[https://scrapbox.io/files/x.zip]` など) の扱い。画像は常に取ってくる。
+   * `'keep'` は元の URL のまま (公開プロジェクトならクリックで開ける)、`'download'` は取ってきてサイトに置く。
+   * 非公開プロジェクトのファイルは `'download'` でないと、見に来た人が開けない。
+   *
+   * @defaultValue `'keep'`
+   */
+  readonly links?: "keep" | "download";
+}
+interface CosenseIntegrationOptions extends AstroCompileOptions {
+  /**
+   * すべてのページに渡すコンポーネントを default export するモジュール (プロジェクトのルートからのパス)。
+   * `.csnx` の `<Name />` や、`a` などの要素の差し替えに使う。
+   * `<Content components={...} />` で渡したものがあれば、そちらが優先する。
+   *
+   * @example `'./src/components/cosense.ts'`
+   */
+  readonly components?: string;
+  /**
+   * Cosense 上の画像やファイル (`/files/…` とアイコン) を、ビルド時に取ってきてサイトの中
+   * (`{base}/_cosense/`) に置く。`false` なら元の URL のまま出す。
+   *
+   * Cosense のファイルは別のサイトからは読めず、リダイレクト先の URL も数分で切れるので、
+   * 静的なサイトで表示するにはこうするしかない。非公開プロジェクトの画像も公開されることになる点に注意。
+   *
+   * @defaultValue `{}` (有効)
+   */
+  readonly assets?: CosenseAssetsOptions | false;
+  /**
+   * コードブロックの色付け。
+   *
+   * - `'astro'`: `.md` / `.mdx` と同じく、Astro の `markdown.syntaxHighlight` と `markdown.shikiConfig` に従う。
+   *   shiki のときだけ色付けし、prism には対応していない
+   * - `false`: 色付けしない
+   * - 関数: `(code, language) => hast | null` で自分で色付けする
+   *
+   * @defaultValue `'astro'`
+   */
+  readonly syntaxHighlight?: SyntaxHighlightOption;
+  /**
+   * ビルドの前に、`srcDir` の下のページのリンク切れを調べる。エディタの診断
+   * (`@cosense-toolbox/lsp`) と同じ判定で、`unresolvedLinks: 'error'` ならビルドを止める。
+   * 省略すると調べない。
+   *
+   * @example `{ unresolvedLinks: 'error' }`
+   */
+  readonly lint?: CosenseLintOptions;
+}
+declare function cosense(options?: CosenseIntegrationOptions): AstroIntegration;
+//#endregion
+export { CosenseAssetsOptions, CosenseIntegrationOptions, type Graph, type GraphPage, type TwoHopGroup, cosense as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/highlight.ts","../src/lint.ts","../src/vite-plugin.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;KAkBY,0CAA0C;;;;KAkG1C,qBAAqB,KAAK;;;UCxGrB;;;;;;;WAON,kBAAkB;;;;;;WAMlB;;;;UCqBM,4BAA4B,KAC3C;;;;;;;;WAgBS;;;;;;WAMA,gBAAgB;;;;UC9BV;;;;;;;WAON;;WAEA;;;;;;;;WAQA;;UAGM,kCAAkC;;;;;;;;WAQxC;;;;;;;;;;WAUA,SAAS;;;;;;;;;;;WAWT,kBAAkB;;;;;;;;WAQlB,OAAO;;iBA4FM,QAAQ,UAAS,4BAAiC"}