linq2db · sdanyliv · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Documentation site for all LinqToDB projects, hosted at [linq2db.github.io](https://linq2db.github.io). Built with a **custom DocFX binary** (`docfx/docfx`) — not the standard NuGet/dotnet tool version. The custom build adds `globalPrefix` support to handle namespace conflicts across EF Core versions (dotnet/docfx#8966).
+
+## Build Commands
+
+```bash
+# Update submodules to latest release (required before first build)
+./submodules.cmd          # runs: git submodule update --remote --merge
+
+# Local build — generates static site in _site/
+./local.cmd               # runs build.ps1 with deploy=$false
+
+# Manual build
+powershell ./build.ps1 -deploy $false    # build only
+powershell ./build.ps1 -deploy $true     # build + deploy (needs GITHUB_PAT env var)
+```
+
+Requires **.NET SDK 10.0** (see `global.json`). The build pre-compiles `LinqToDB.FSharp` as a DocFX workaround before running `./docfx/docfx source/docfx.json`.
+
+## Documentation Structure
+
+- **`source/index.md`** — Landing page with hero, interactive SQL demo, navigation cards
+- **`source/documentation/`** — Structured guides (Markdown + `toc.yml` per section)
+  - `get-started/` — Installation and setup guides
+  - `general/` — Core concepts (connections, interceptors, metrics, database support)
+  - `sql/` — SQL features (bulk copy, CTEs, MERGE, joins, window functions)
+  - `how-to/` — Task-oriented guides
+  - `project/` — Contributing, issue reporting
+- **`source/articles/`** — Blog/news content (release notes)
+- **`source/api/`** — Auto-generated API docs (output of DocFX metadata extraction, not hand-edited)
+- **`source/templates/custom/`** — CSS/JS overrides for DocFX modern template
+- **`_site/`** — Generated static HTML output (gitignored)
+
+## Landing Page SQL Demo
+
+The landing page has a tabbed demo showing C# LINQ → generated SQL. See **`tools/sql-demo/README.md`** for full maintenance guide. Key points:
+
+- SQL is pre-generated using `ToSqlQuery()` from the linq2db library
+- Test file: `tools/sql-demo/SqlDemoGenerator.cs` — copy to `linq2db/Tests/Tests.Playground/` to run
+- Tabs are pure CSS (radio inputs + `:checked` selectors), no JavaScript
+- Use `&#10;` instead of blank lines inside `<pre>` blocks (DocFX wraps blank lines in `<p>` tags)
+
+## Key Configuration Files
+
+- **`source/docfx.json`** — Main DocFX config: 17 metadata sources (API namespaces) + build settings
+- **`source/toc.yml`** — Top-level navigation (Documentation, Articles, API)
+- **`source/filter.yml`** — API filtering rules
+
+## Submodules
+
+Source code for API documentation lives in `submodules/`:
+- **`linq2db`** (release branch) — Main ORM library, F# extensions, tools, scaffold, remote packages
+- **`LinqToDB.Identity`** (master) — ASP.NET Identity provider
+- **`linq2db.EntityFrameworkCore`** — EF Core 3/8/9/10 integration
+- **`IdentityServer4.LinqToDB`** — IdentityServer4 integration
+
+Run `./submodules.cmd` after cloning or when API docs need updating.
+
+## CI/CD (Azure Pipelines)
+
+- **`azure-pipelines.yml`** — Triggers on master push: builds and deploys to linq2db.github.io
+- **`azure-pipelines.build.yml`** — Triggers on PRs: build-only validation
+
+Both use Windows 2022 VM with .NET SDK 10.x.
+
+## Editor Conventions
+
+Per `.editorconfig`: tab indentation (size 4), CRLF line endings, final newline required.
diff --git a/source/articles/index.md b/source/articles/index.md
@@ -0,0 +1,19 @@
+---
+title: Articles
+_disableAffix: true
+_disableNextArticle: true
+---
+
+# Articles
+
+<div class="row g-4 my-4">
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-megaphone"></i> Release Notes</h4>
+<p class="card-text">Release history, changelogs, and project roadmap.</p>
+<a href="https://github.com/linq2db/linq2db/wiki/Releases-and-Roadmap" class="stretched-link"></a>
+</div>
+</div>
+</div>
+</div>
diff --git a/source/articles/toc.yml b/source/articles/toc.yml
@@ -1,18 +1,2 @@
 - name: Release Notes
   href: https://github.com/linq2db/linq2db/wiki/Releases-and-Roadmap
-- name: Get Started
-  href: get-started/toc.yml
-- name: General Topics
-  href: general/toc.yml
-- name: SQL
-  href: sql/toc.yml
-- name: How To
-  href: how-to/toc.yml
-- name: CLI Scaffold Tool
-  href: CLI.md
-- name: T4 Templates (Obsoleted)
-  href: T4.md
-- name: FAQ
-  href: FAQ.md
-- name: Project
-  href: project/toc.yml
diff --git a/source/docfx.json b/source/docfx.json
@@ -220,6 +220,7 @@
 				"files": [
 					"api/**/*.{md,yml}",
 					"articles/**/*.{md,yml}",
+					"documentation/**/*.{md,yml}",
 					"toc.yml",
 					"*.md"
 				]
@@ -231,7 +232,7 @@
 					"images/**",
 					"**.png",
 					"**.jpg",
-					"articles/cli-help.txt",
+					"documentation/cli-help.txt",
 					".nojekyll"
 				]
 			}
@@ -247,7 +248,15 @@
 			"_appFaviconPath": "images/icon.ico",
 			"_enableSearch": true,
 			"_disableNewTab": false,
-			"_disableContribution": true
+			"_gitContribute": {
+				"repo": "https://github.com/linq2db/docs",
+				"branch": "master"
+			}
+		},
+		"fileMetadata": {
+			"_disableContribution": {
+				"api/**/**.yml": true
+			}
 		},
 		"fileMetadataFiles": [],
 		"template": [

diff --git a/source/articles/CLI.md → source/documentation/CLI.md b/source/articles/CLI.md → source/documentation/CLI.md
diff --git a/source/articles/FAQ.md → source/documentation/FAQ.md b/source/articles/FAQ.md → source/documentation/FAQ.md
diff --git a/source/articles/T4.md → source/documentation/T4.md b/source/articles/T4.md → source/documentation/T4.md
diff --git a/source/articles/cli-help.txt → source/documentation/cli-help.txt b/source/articles/cli-help.txt → source/documentation/cli-help.txt
diff --git a/...icles/general/Managing-data-connection.md → ...ation/general/Managing-data-connection.md b/...icles/general/Managing-data-connection.md → ...ation/general/Managing-data-connection.md
diff --git a/source/articles/general/Video.md → source/documentation/general/Video.md b/source/articles/general/Video.md → source/documentation/general/Video.md
diff --git a/source/articles/general/databases.md → source/documentation/general/databases.md b/source/articles/general/databases.md → source/documentation/general/databases.md
diff --git a/source/articles/general/interceptors.md → source/documentation/general/interceptors.md b/source/articles/general/interceptors.md → source/documentation/general/interceptors.md
diff --git a/source/articles/general/metrics.md → source/documentation/general/metrics.md b/source/articles/general/metrics.md → source/documentation/general/metrics.md
diff --git a/source/articles/general/toc.yml → source/documentation/general/toc.yml b/source/articles/general/toc.yml → source/documentation/general/toc.yml
diff --git a/...cles/get-started/asp-dotnet-core/index.md → ...tion/get-started/asp-dotnet-core/index.md b/...cles/get-started/asp-dotnet-core/index.md → ...tion/get-started/asp-dotnet-core/index.md
diff --git a/...es/get-started/full-dotnet/existing-db.md → ...on/get-started/full-dotnet/existing-db.md b/...es/get-started/full-dotnet/existing-db.md → ...on/get-started/full-dotnet/existing-db.md
diff --git a/...full-dotnet/static/output-existing-db.png → ...full-dotnet/static/output-existing-db.png b/...full-dotnet/static/output-existing-db.png → ...full-dotnet/static/output-existing-db.png
diff --git a/source/articles/get-started/install/index.md → ...ocumentation/get-started/install/index.md b/source/articles/get-started/install/index.md → ...ocumentation/get-started/install/index.md
diff --git a/source/articles/get-started/toc.yml → source/documentation/get-started/toc.yml b/source/articles/get-started/toc.yml → source/documentation/get-started/toc.yml
diff --git a/...linq2db-convert-custom-net-code-to-sql.md → ...linq2db-convert-custom-net-code-to-sql.md b/...linq2db-convert-custom-net-code-to-sql.md → ...linq2db-convert-custom-net-code-to-sql.md
diff --git a/source/articles/how-to/toc.yml → source/documentation/how-to/toc.yml b/source/articles/how-to/toc.yml → source/documentation/how-to/toc.yml
diff --git a/...-mapvalue-attribute-to-control-mapping.md → ...-mapvalue-attribute-to-control-mapping.md b/...-mapvalue-attribute-to-control-mapping.md → ...-mapvalue-attribute-to-control-mapping.md
diff --git a/source/documentation/index.md b/source/documentation/index.md
@@ -0,0 +1,69 @@
+---
+title: Documentation
+_disableAffix: true
+_disableNextArticle: true
+---
+
+# Linq To DB Documentation
+
+<div class="row g-4 my-4">
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-rocket-takeoff"></i> Get Started</h4>
+<p class="card-text">Install Linq To DB and create your first project. Guides for ASP.NET Core and existing databases.</p>
+<a href="get-started/install/index.md" class="stretched-link"></a>
+</div>
+</div>
+</div>
+
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-book"></i> General Topics</h4>
+<p class="card-text">Database support, managing connections, interceptors, metrics, and core concepts.</p>
+<a href="general/databases.md" class="stretched-link"></a>
+</div>
+</div>
+</div>
+
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-database"></i> SQL</h4>
+<p class="card-text">Join operators, CTEs, Bulk Copy, Window Functions, MERGE operations, and Query Extensions.</p>
+<a href="sql/Join-Operators.md" class="stretched-link"></a>
+</div>
+</div>
+</div>
+
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-tools"></i> How-To Guides</h4>
+<p class="card-text">Practical guides for custom SQL conversions, attribute mapping, and common tasks.</p>
+<a href="how-to/teach-linq2db-convert-custom-net-code-to-sql.md" class="stretched-link"></a>
+</div>
+</div>
+</div>
+
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-terminal"></i> CLI Scaffold Tool</h4>
+<p class="card-text">Generate data model from existing database using the command-line scaffold tool.</p>
+<a href="CLI.md" class="stretched-link"></a>
+</div>
+</div>
+</div>
+
+<div class="col-md-6 col-lg-4">
+<div class="card h-100 doc-card">
+<div class="card-body">
+<h4 class="card-title"><i class="bi bi-question-circle"></i> FAQ</h4>
+<p class="card-text">Frequently asked questions and common issues.</p>
+<a href="FAQ.md" class="stretched-link"></a>
+</div>
+</div>
+</div>
+</div>
diff --git a/source/articles/links.md → source/documentation/links.md b/source/articles/links.md → source/documentation/links.md
diff --git a/source/articles/project/Issue-reporting.md → .../documentation/project/Issue-reporting.md b/source/articles/project/Issue-reporting.md → .../documentation/project/Issue-reporting.md
diff --git a/source/articles/project/contrib.md → source/documentation/project/contrib.md b/source/articles/project/contrib.md → source/documentation/project/contrib.md
diff --git a/source/articles/project/toc.yml → source/documentation/project/toc.yml b/source/articles/project/toc.yml → source/documentation/project/toc.yml
diff --git a/source/articles/sql/Bulk-Copy.md → source/documentation/sql/Bulk-Copy.md b/source/articles/sql/Bulk-Copy.md → source/documentation/sql/Bulk-Copy.md
diff --git a/source/articles/sql/CTE.md → source/documentation/sql/CTE.md b/source/articles/sql/CTE.md → source/documentation/sql/CTE.md
diff --git a/source/articles/sql/Join-Operators.md → source/documentation/sql/Join-Operators.md b/source/articles/sql/Join-Operators.md → source/documentation/sql/Join-Operators.md
diff --git a/source/articles/sql/Query-Extensions.md → source/documentation/sql/Query-Extensions.md b/source/articles/sql/Query-Extensions.md → source/documentation/sql/Query-Extensions.md
diff --git a/.../Window-Functions-(Analytic-Functions).md → .../Window-Functions-(Analytic-Functions).md b/.../Window-Functions-(Analytic-Functions).md → .../Window-Functions-(Analytic-Functions).md
diff --git a/...rticles/sql/merge/Merge-API-Background.md → ...ntation/sql/merge/Merge-API-Background.md b/...rticles/sql/merge/Merge-API-Background.md → ...ntation/sql/merge/Merge-API-Background.md
diff --git a/...ticles/sql/merge/Merge-API-Description.md → ...tation/sql/merge/Merge-API-Description.md b/...ticles/sql/merge/Merge-API-Description.md → ...tation/sql/merge/Merge-API-Description.md
diff --git a/...articles/sql/merge/Merge-API-Migration.md → ...entation/sql/merge/Merge-API-Migration.md b/...articles/sql/merge/Merge-API-Migration.md → ...entation/sql/merge/Merge-API-Migration.md
diff --git a/source/articles/sql/merge/Merge-API.md → source/documentation/sql/merge/Merge-API.md b/source/articles/sql/merge/Merge-API.md → source/documentation/sql/merge/Merge-API.md
diff --git a/source/articles/sql/merge/toc.yml → source/documentation/sql/merge/toc.yml b/source/articles/sql/merge/toc.yml → source/documentation/sql/merge/toc.yml
diff --git a/source/articles/sql/toc.yml → source/documentation/sql/toc.yml b/source/articles/sql/toc.yml → source/documentation/sql/toc.yml
diff --git a/source/documentation/toc.yml b/source/documentation/toc.yml
@@ -0,0 +1,16 @@
+- name: Get Started
+  href: get-started/toc.yml
+- name: General Topics
+  href: general/toc.yml
+- name: SQL
+  href: sql/toc.yml
+- name: How To
+  href: how-to/toc.yml
+- name: CLI Scaffold Tool
+  href: CLI.md
+- name: T4 Templates (Obsoleted)
+  href: T4.md
+- name: FAQ
+  href: FAQ.md
+- name: Project
+  href: project/toc.yml