@riebeckite/plugin-docs 0.0.31 → 0.0.33

package/README.md

@@ -8,6 +8,10 @@ router or recalculating public URLs from filesystem paths.
 
 [日本語](./README_ja.md)
 
+## Live example
+
+This page is a Docs entry. The Documentation sidebar on the right, the previous/next links below the article, and the [Docs index](/docs/) all come from this plugin.
+
 ## Installation
 
 ```sh
@@ -85,7 +89,7 @@ outside-root content does not appear in the sidebar or previous/next sequence.
 
 ## Exports
 
-- `docs(options)` / `docsPlugin(options)` — plugin factory
+- `docs(options)` / `docs(options)` — plugin factory
 - `buildDocsNavigation(entries, options)` — build the framework-independent model
 - `flattenDocsNavigation(items)` — derive the previous/next sequence
 - `renderDocsSidebar(...)` and `renderDocsPrevNext(...)` — server HTML renderers

package/README_ja.md

@@ -3,11 +3,15 @@
 <!-- Generated from docs/docs/plugins/docs.ja.md. Edit the canonical documentation in docs/docs/plugins and run `pnpm docs:sync`. -->
 
 Riebeckite の Markdown コンテンツから、Docs 用のサイドバーと前後ページリンクを
-ビルド時に生成するプラグインです。Docs 専用の router は追加せず、公開 URL も
+ビルド時に生成するプラグインです。Docs 専用のルーターは追加せず、公開 URL も
 ファイルシステムのパスから再計算しません。
 
 [English](./README.md)
 
+## 実行例
+
+このページは Docs のエントリです。右側の Documentation サイドバー、記事下の前後リンク、[Docs の一覧](/ja/docs/) はすべてこのプラグインが生成しています。
+
 ## インストール
 
 ```sh
@@ -34,7 +38,7 @@ export default defineConfig({
 `root` は Docs として扱うコンテンツサブツリーです。`root: "docs"` の場合、
 `content/docs/` 配下だけが対象になり、`notes/` や `blog/` には Docs の UI を出しません。
 
-## Frontmatter
+## frontmatter
 
 ```yaml
 ---
@@ -47,12 +51,12 @@ sidebar:
 ---
 ```
 
-対応するメタデータは次の通りです。
+対応するメタデータは次のとおりです。
 
 - `label`: ナビゲーションに表示する名前。未指定なら `title`、さらに未指定ならファイル名。
-- `order`: 明示的な並び順。未指定の項目は明示された order のあとを title、path の順に並びます。
+- `order`: 明示的な並び順。指定のない項目は、`order` を持つ項目の後に、タイトル、パスの順で並びます。
 - `hidden`: サイドバーと前後ページリンクから除外します。
-- `collapsed`: Theme やクライアント側の拡張のために `data-docs-collapsed` として出力します。
+- `collapsed`: Theme やクライアント側の拡張で使えるよう、`data-docs-collapsed` として出力します。
 
 これらのフィールドはすべて任意です。`sidebar` frontmatter のないページも
 ナビゲーションに表示されます。階層はフォルダ構造に従い、ラベルは `title`、
@@ -60,27 +64,27 @@ sidebar:
 設定ではなくコンテンツ側に置きます。上書きしたいフィールドだけを指定し、それ
 以外は Vault に手を入れないでください。
 
-## Theme との統合
+## 出力と Theme の統合
 
-Plugin は React ライクな JSX コンポーネントをサイト統合に提供します。
+プラグインは、サイトへ組み込むための React 風の JSX コンポーネントを提供します。
 
 - `<DocsSidebar items={...} currentPermalink? label? />` は `details.rb-docs-sidebar-details` と `nav.rb-docs-sidebar` を描画
 - `<DocsPrevNext previous? next? />` は `nav.rb-docs-prev-next` を描画
 
-クライアント `initDocsSidebar` がサイドバーを畳めるようにします。
+クライアント側の `initDocsSidebar` を使うと、サイドバーを折りたためます。
 
 ## l10n と公開の境界
 
 `@riebeckite/plugin-l10n` のメタデータがある場合、現在の言語に対応する項目だけで
-ナビゲーションを作ります。URL は manifest の解決済み permalink をそのまま使うため、
-permalink / alias / rename / l10n の責務を壊しません。
+ナビゲーションを作ります。URL はマニフェストの解決済みパーマリンクをそのまま使うため、
+パーマリンク、エイリアス、リネーム、l10n の扱いはコンテンツ側の責務のままです。
 
 公開対象の項目だけを含めます。draft、private、excluded、hidden、root 外のコンテンツは
-サイドバーと前後ページリンクに出ません。
+サイドバーと前後ページリンクに表示されません。
 
 ## エクスポート
 
-- `docs(options)` / `docsPlugin(options)`: プラグインファクトリ
+- `docs(options)` / `docs(options)`: プラグインファクトリ
 - `buildDocsNavigation(entries, options)`: フレームワークに依存しないナビゲーションモデル
 - `flattenDocsNavigation(items)`: 前後ページリンク用の並び
 - `renderDocsSidebar(...)` / `renderDocsPrevNext(...)`: サーバー側の HTML レンダラー

package/dist/client.js

@@ -1,10 +1,9 @@
 // src/docs-sidebar.client.ts
 var COLLAPSIBLE_PROPERTY = "--rb-docs-sidebar-collapsible";
-function initDocsSidebar() {
+function initDocsSidebar(context = {}) {
+  const root = context.root ?? document;
   const details = Array.from(
-    document.querySelectorAll(
-      "[data-docs-sidebar-details]"
-    )
+    root.querySelectorAll("[data-docs-sidebar-details]")
   );
   const first = details[0];
   if (!first) return;
@@ -22,6 +21,7 @@ function initDocsSidebar() {
     apply(next);
   };
   window.addEventListener("resize", sync, { passive: true });
+  return () => window.removeEventListener("resize", sync);
 }
 function isCollapsible(element) {
   return getComputedStyle(element).getPropertyValue(COLLAPSIBLE_PROPERTY).trim() !== "0";

package/dist/components/docs-sidebar.d.ts

@@ -3,6 +3,7 @@ export type DocsSidebarProps = {
     readonly items?: readonly DocsNavigationItem[];
     readonly currentPermalink?: string;
     readonly label?: string;
+    readonly placement?: "inline" | "article-rail";
 };
 declare const DocsSidebar: (props: Readonly<DocsSidebarProps>) => Promise<import("hono/utils/html").HtmlEscapedString>;
 export default DocsSidebar;

package/dist/components/docs-sidebar.js

@@ -175,7 +175,7 @@ var DocsSidebar = (async (props) => {
   const label = props.label ?? options?.sidebar?.label ?? "Docs navigation";
   if (items.length === 0) return html``;
   const permalink = currentPermalink ?? "";
-  return /* @__PURE__ */ jsxs("details", { class: "rb-docs-sidebar-details", "data-docs-sidebar-details": true, open: true, children: [
+  const sidebar = /* @__PURE__ */ jsxs("details", { class: "rb-docs-sidebar-details", "data-docs-sidebar-details": true, open: true, children: [
     /* @__PURE__ */ jsx("summary", { class: "rb-docs-sidebar-summary", children: label }),
     /* @__PURE__ */ jsx("nav", { class: "rb-docs-sidebar", "aria-label": label, "data-docs-sidebar": true, children: /* @__PURE__ */ jsx(
       DocsSidebarItems,
@@ -186,6 +186,7 @@ var DocsSidebar = (async (props) => {
       }
     ) })
   ] });
+  return props.placement === "article-rail" ? /* @__PURE__ */ jsx("aside", { class: "rb-docs-sidebar-rail", children: sidebar }) : sidebar;
 });
 function DocsSidebarItems({
   items,

package/dist/index.d.ts

@@ -10,4 +10,3 @@ export { renderDocsPrevNext, renderDocsSidebar } from "./src/render.js";
 export type { DocsNavigationItem, DocsOptions, DocsSidebarFrontmatter, ResolvedDocsOptions, } from "./src/types.js";
 export declare const DOCS_PLUGIN_NAME = "docs";
 export declare function docs(options: DocsOptions): import("@riebeckite/core").RiebeckitePlugin<DocsOptions>;
-export declare const docsPlugin: typeof docs;

package/dist/index.js

@@ -261,7 +261,7 @@ var DocsSidebar = (async (props) => {
   const label = props.label ?? options?.sidebar?.label ?? "Docs navigation";
   if (items.length === 0) return html2``;
   const permalink = currentPermalink ?? "";
-  return /* @__PURE__ */ jsxs2("details", { class: "rb-docs-sidebar-details", "data-docs-sidebar-details": true, open: true, children: [
+  const sidebar = /* @__PURE__ */ jsxs2("details", { class: "rb-docs-sidebar-details", "data-docs-sidebar-details": true, open: true, children: [
     /* @__PURE__ */ jsx2("summary", { class: "rb-docs-sidebar-summary", children: label }),
     /* @__PURE__ */ jsx2("nav", { class: "rb-docs-sidebar", "aria-label": label, "data-docs-sidebar": true, children: /* @__PURE__ */ jsx2(
       DocsSidebarItems,
@@ -272,6 +272,7 @@ var DocsSidebar = (async (props) => {
       }
     ) })
   ] });
+  return props.placement === "article-rail" ? /* @__PURE__ */ jsx2("aside", { class: "rb-docs-sidebar-rail", children: sidebar }) : sidebar;
 });
 function DocsSidebarItems({
   items,
@@ -344,11 +345,10 @@ function findDocsOptions2(plugins) {
 
 // src/docs-sidebar.client.ts
 var COLLAPSIBLE_PROPERTY = "--rb-docs-sidebar-collapsible";
-function initDocsSidebar() {
+function initDocsSidebar(context = {}) {
+  const root = context.root ?? document;
   const details = Array.from(
-    document.querySelectorAll(
-      "[data-docs-sidebar-details]"
-    )
+    root.querySelectorAll("[data-docs-sidebar-details]")
   );
   const first = details[0];
   if (!first) return;
@@ -366,6 +366,7 @@ function initDocsSidebar() {
     apply(next);
   };
   window.addEventListener("resize", sync, { passive: true });
+  return () => window.removeEventListener("resize", sync);
 }
 function isCollapsible(element) {
   return getComputedStyle(element).getPropertyValue(COLLAPSIBLE_PROPERTY).trim() !== "0";
@@ -455,12 +456,14 @@ function docs(options) {
       createClientEntry(
         DOCS_PLUGIN_NAME,
         "@riebeckite/plugin-docs/client",
-        "initDocsSidebar"
+        "initDocsSidebar",
+        void 0,
+        void 0,
+        "context"
       )
     ]
   });
 }
-var docsPlugin = docs;
 function validateDocsOptions(options) {
   const issues = [];
   if (!options || typeof options !== "object") {
@@ -483,7 +486,6 @@ export {
   docs_sidebar_default as DocsSidebar,
   buildDocsNavigation,
   docs,
-  docsPlugin,
   flattenDocsNavigation,
   getDocsNavigation,
   getDocsPrevNext,

package/dist/src/docs-sidebar.client.d.ts

@@ -1 +1,5 @@
-export declare function initDocsSidebar(): void;
+type ClientContext = {
+    root?: ParentNode;
+};
+export declare function initDocsSidebar(context?: ClientContext): () => void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-docs",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,13 +27,13 @@
     "./style.css": "./style.css"
   },
   "dependencies": {
-    "hono": "^4.12.25",
-    "@riebeckite/core": "0.0.31",
-    "@riebeckite/ui": "0.0.31"
+    "@riebeckite/core": "0.0.33",
+    "@riebeckite/ui": "0.0.33",
+    "hono": "^4.12.25"
   },
   "devDependencies": {
-    "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.31"
+    "@riebeckite/test": "0.0.33",
+    "tsx": "^4.22.4"
   },
   "publishConfig": {
     "access": "public"

package/style.css

@@ -2,6 +2,43 @@
   --rb-docs-sidebar-collapsible: 1;
 }
 
+.rb-docs-sidebar-rail {
+  display: none;
+}
+
+@media (min-width: 48rem) {
+  .rb-docs-sidebar-rail {
+    display: block;
+    min-width: 0;
+    margin-block: var(--rb-space-4);
+  }
+}
+
+@media (min-width: 88rem) {
+  :is(:root, .rb-theme-root)[data-article-layout="article"]
+    .rb-docs-sidebar-rail {
+    display: block;
+    grid-column: 1;
+    grid-row: 1;
+    position: sticky;
+    top: var(--rb-docs-rail-top);
+    align-self: start;
+    width: var(--rb-layout-sidebar);
+    max-height: var(--rb-docs-rail-max-block-size);
+    margin-block: 0;
+    margin-inline-start: calc(
+      -1 *
+      var(--rb-layout-sidebar) -
+      var(--rb-layout-gap)
+    );
+    overflow: auto;
+    padding-block: 0;
+    padding-inline-end: 1rem;
+    border-inline-end: 1px solid
+      color-mix(in oklab, currentColor 18%, transparent);
+  }
+}
+
 .rb-docs-sidebar-details > .rb-docs-sidebar-summary {
   cursor: pointer;
   font-size: 0.95rem;