Skip to content

Repository navigation

README.ja.md

Latest commit

 

History

History
111 lines (80 loc) · 6.9 KB

README.ja.md

File metadata and controls

111 lines (80 loc) · 6.9 KB
Raw

LithoSharp

build NuGet

English | 日本語

C#、Markdown、MDX、Reactと増分ビルドを使える、型安全な.NET向け静的サイト・ドキュメント生成器です。 .NETのコードと一緒に文書を管理し、生成時にコンテンツやリンクを検証して、通常の静的ファイルとして配置できます。

現在の最新版は 2.0.0 です。以下の導入例もこの版を使います。 既存サイトを更新する場合は2.0への移行案内を参照してください。

サンプルサイト

同梱のサイト定義から生成した画面です。標準のDocsとBlogは、ライト・ダーク切り替え、 画面幅に応じたメニュー、キーボード操作に対応します。 SiteThemeOptions.EnableThemeSwitching = false で切り替えを無効にできます。 詳しくはテーマの設定を参照してください。

Docsのライト配色 Blogのダーク配色
サイドバー、本文、目次を表示したDocsサンプル 先頭記事とナビゲーションを表示したBlogサンプル

主な機能

  • 型付きC# content collection、route、reference。厳密なschema検証と、任意のRoslyn source generator・build診断。
  • Markdownと任意のMDX 3。Reactによる生成時HTML、page hydration、明示islandによるselective hydration。
  • Docs、Blog、独立ページ、複数Docs collection、version、locale、sidebar、local search。
  • 依存graph、永続cache、invalidation reason、artifact ownershipによる増分ビルドの確認。
  • routeとownershipを検証したうえでのstaging、output transaction、公開前のrollback。
  • link、anchor、canonical、redirect、SEOに対する構造化診断。
  • XML形式の.NET API文書、OpenAPI 3 JSON、正確なxref、検証済みexampleの取り込み。
  • site、route、artifact、DOM、component、layoutを検証する.NET向けTesting API。
  • fingerprint付きasset、responsive image、C# renderingと信頼するMDX pluginの拡張点。

Quick Start

.NET 10 SDKを用意して実行します。

dotnet new install LithoSharp.ProjectTemplates::2.0.0
dotnet tool install LithoSharp.Tool --version 2.0.0 --tool-path .tools
.tools/lithosharp new docs MyDocs -o MyDocs
.tools/lithosharp build MyDocs -c Release
.tools/lithosharp serve MyDocs -c Release

Windowsの実行ファイルは.tools/lithosharp.exeです。MyDocs/contentを編集し、 DocsSiteFactory.csで設定します。生成したMyDocs/distは静的HTTP hostへ配置できます。 独立したinstall、Markdown、MDX、対話componentの手順はQuick Start全体を参照してください。

既存アプリケーションではdotnet add package LithoSharp --version 2.0.0でライブラリを追加し、 直接呼び出せます。CLI hostは必須ではありません。

使用例

目的 入口
Markdown Docs、typed content、画像 Docs sample
Blog、フィード、検索 Blog sample
MDX、React island、offline navigation MDX sample
versioning、i18n、Blog/Pages、API docs MDXガイドと使用例の案内

必要な環境

.NET 10が必要です。最低対応SDKは10.0.300です。CLIの開発サーバーはSDKに含まれる ASP.NET Core shared frameworkも使います。MarkdownだけならNode.jsとReactは不要です。 MDXはNode.js 24.13.0と明示的なworker restoreが必要です。lockfileはMDX 3.1.1、React 19.2.4、 esbuild 0.28.2を固定しています。本番出力の配信には静的HTTP hostだけで十分です。

VS Code拡張機能

LithoSharp for VS CodeでMarkdown/MDXの診断、見出しによる移動、ビルド、サイトのプレビューを利用できます。手順は拡張機能のガイドを参照してください。

ドキュメント

2.0.0への更新

利用しているLithoSharpのパッケージ、CLI、templateを2.0.0に揃えてください。 2.0への移行案内に従い、Testing APIのDocumentからSnapshotへの非互換変更に対応します。 サイトを再生成し、コンテンツの警告、リンク、独自CSSの表示を確認してください。 MDXの導入は引き続き任意です。Markdownの対応構文も確認してください。

過去版同士の移行手順は更新履歴の資料に保管しています。

既知の制約

MDXとC#のsite codeは信頼するbuild codeとして実行します。HTML safetyはコードのsandboxではありません。 大規模MDXでは多くのinteractive entryを再bundleする場合があります。任意のDocusaurus plugin、 trimming、Native AOTは非対応です。実行環境を選ぶ前に既知の制約を確認してください。

性能

0.3.0で測定した静的ページfixtureでは、selective hydrationによりJSが449,585から15,817 bytes、 hydration rootが1から0になりました。全islandやfallbackの結果ではありません。 10,000ページMDX corpusのcoldは274.30秒、no-opは105.13秒でした。100件と1,000件の 競合比較の要点と、1.0.0候補で再測定したMarkdownの結果も併記しています。 測定条件・制約・再現手順を参照してください。

貢献とライセンス

buildと検証の手順はCONTRIBUTINGを参照してください。 MIT licenseです。LICENSEとthird-party noticesも確認してください。