From 7d33543d8578df4eee3537d9c3cde3de76f38393 Mon Sep 17 00:00:00 2001
From: Andrzej Ratajczak <andrzej.ratajczak98@gmail.com>
Date: Sat, 21 Aug 2021 12:17:13 +0200
Subject: [PATCH 1/4] Add script for docs preprocessing for static site

---
 .github/workflows/ci.yaml                     |   3 +
 .github/workflows/scaladoc.yaml               |   3 +
 .../docs/reference/changed-features.md        |   9 ++
 .../changed-features/compiler-plugins.md      |   6 +-
 .../changed-features/eta-expansion-spec.md    |   4 +-
 .../changed-features/eta-expansion.md         |  10 +-
 .../implicit-conversions-spec.md              |  10 +-
 .../changed-features/implicit-conversions.md  |   8 +-
 .../changed-features/implicit-resolution.md   |   7 +-
 .../reference/changed-features/imports.md     |   6 +-
 .../changed-features/interpolation-escapes.md |   4 +-
 .../changed-features/lazy-vals-init.md        |   8 +-
 .../changed-features/main-functions.md        |  10 +-
 .../changed-features/match-syntax.md          |   8 +-
 .../changed-features/numeric-literals.md      |   9 ++
 .../reference/changed-features/operators.md   |  10 +-
 .../changed-features/overload-resolution.md   |   8 +-
 .../changed-features/pattern-bindings.md      |   6 +-
 .../changed-features/pattern-matching.md      |   8 +-
 .../changed-features/structural-types-spec.md |   6 +-
 .../changed-features/structural-types.md      |   8 +-
 .../changed-features/type-checking.md         |   9 ++
 .../changed-features/type-inference.md        |   6 +-
 .../changed-features/vararg-splices.md        |   8 +-
 .../reference/changed-features/wildcards.md   |   6 +-
 .../docs/reference/contextual.md              |  85 +++++++++++++++
 .../contextual/by-name-context-parameters.md  |   6 +-
 .../reference/contextual/context-bounds.md    |   6 +-
 .../contextual/context-functions-spec.md      |   6 +-
 .../reference/contextual/context-functions.md |   8 +-
 .../docs/reference/contextual/conversions.md  |   6 +-
 .../reference/contextual/derivation-macro.md  |  10 +-
 .../docs/reference/contextual/derivation.md   |  10 +-
 .../reference/contextual/extension-methods.md |  12 ++-
 .../reference/contextual/given-imports.md     |   6 +-
 .../docs/reference/contextual/givens.md       |  12 ++-
 .../contextual/multiversal-equality.md        |   8 +-
 .../contextual/relationship-implicits.md      |   6 +-
 .../right-associative-extension-methods.md    |   4 +-
 .../docs/reference/contextual/type-classes.md |  10 +-
 .../reference/contextual/using-clauses.md     |  12 ++-
 .../docs/reference/dropped-features.md        |   9 ++
 .../reference/dropped-features/auto-apply.md  |   6 +-
 .../dropped-features/class-shadowing-spec.md  |   4 +-
 .../dropped-features/class-shadowing.md       |   8 +-
 .../dropped-features/delayed-init.md          |   8 +-
 .../reference/dropped-features/do-while.md    |   8 +-
 .../dropped-features/early-initializers.md    |   8 +-
 .../dropped-features/existential-types.md     |   6 +-
 .../reference/dropped-features/limit22.md     |  10 +-
 .../docs/reference/dropped-features/macros.md |  12 ++-
 .../dropped-features/nonlocal-returns.md      |   6 +-
 .../dropped-features/package-objects.md       |   6 +-
 .../dropped-features/procedure-syntax.md      |   6 +-
 .../reference/dropped-features/symlits.md     |   6 +-
 .../dropped-features/this-qualifier.md        |   6 +-
 .../dropped-features/type-projection.md       |   6 +-
 .../dropped-features/weak-conformance-spec.md |   4 +-
 .../dropped-features/weak-conformance.md      |   8 +-
 .../dropped-features/wildcard-init.md         |   6 +-
 .../docs/reference/dropped-features/xml.md    |   6 +-
 docs-for-scalalang/docs/reference/enums.md    |   9 ++
 .../docs/reference/enums/adts.md              |  14 +--
 .../docs/reference/enums/desugarEnums.md      |   8 +-
 .../docs/reference/enums/enums.md             |   8 +-
 .../docs/reference/experimental/canthrow.md   |   7 +-
 .../experimental/erased-defs-spec.md          |   3 +-
 .../reference/experimental/erased-defs.md     |   7 +-
 .../experimental/named-typeargs-spec.md       |   3 +-
 .../reference/experimental/named-typeargs.md  |   0
 .../experimental/numeric-literals.md          |   0
 .../docs/reference/experimental/overview.md   |   0
 .../docs/reference/features-classification.md |  81 +++++++-------
 .../docs/reference/language-versions.md       |  36 +++++++
 .../docs/reference/metaprogramming.md         |  20 ++--
 .../metaprogramming/compiletime-ops.md        |  14 +--
 .../docs/reference/metaprogramming/inline.md  |   8 +-
 .../reference/metaprogramming/macros-spec.md  |   8 +-
 .../docs/reference/metaprogramming/macros.md  |  16 +--
 .../reference/metaprogramming/reflection.md   |  12 ++-
 .../reference/metaprogramming/simple-smp.md   |   5 +-
 .../docs/reference/metaprogramming/staging.md |   8 +-
 .../metaprogramming/tasty-inspect.md          |   6 +-
 .../docs/reference/new-types.md               |   9 ++
 .../dependent-function-types-spec.md          |   8 +-
 .../new-types/dependent-function-types.md     |  10 +-
 .../new-types/intersection-types-spec.md      |   4 +-
 .../reference/new-types/intersection-types.md |  10 +-
 .../docs/reference/new-types/match-types.md   |   6 +-
 .../new-types/polymorphic-function-types.md   |   8 +-
 .../reference/new-types/type-lambdas-spec.md  |   6 +-
 .../docs/reference/new-types/type-lambdas.md  |   8 +-
 .../reference/new-types/union-types-spec.md   |   6 +-
 .../docs/reference/new-types/union-types.md   |   8 +-
 .../docs/reference/other-new-features.md      |   9 ++
 .../other-new-features/control-syntax.md      |   6 +-
 .../creator-applications.md                   |   6 +-
 .../other-new-features/experimental-defs.md   |   0
 .../other-new-features/explicit-nulls.md      |  14 +--
 .../reference/other-new-features/export.md    |   8 +-
 .../indentation-experimental.md               |   3 +-
 .../other-new-features/indentation.md         |  10 +-
 .../other-new-features/kind-polymorphism.md   |   6 +-
 .../reference/other-new-features/matchable.md |   8 +-
 .../other-new-features/named-typeargs.md      |   3 +-
 .../other-new-features/opaques-details.md     |   6 +-
 .../reference/other-new-features/opaques.md   |   8 +-
 .../other-new-features/open-classes.md        |   6 +-
 .../parameter-untupling-spec.md               |   4 +-
 .../other-new-features/parameter-untupling.md |   8 +-
 .../other-new-features/safe-initialization.md |   6 +-
 .../other-new-features/targetName.md          |   6 +-
 .../threadUnsafe-annotation.md                |   6 +-
 .../other-new-features/trait-parameters.md    |   8 +-
 .../other-new-features/transparent-traits.md  |  10 +-
 .../reference/other-new-features/type-test.md |   6 +-
 .../docs/reference/overview.md                | 102 +++++++++---------
 .../docs/reference/soft-modifier.md           |   5 +-
 .../docs/reference/syntax.md                  |  25 ++---
 .../docs/usage/scaladoc/blog.md               |  11 +-
 .../docs/usage/scaladoc/docstrings.md         |  11 +-
 .../docs/usage/scaladoc/index.md              |  11 ++
 .../docs/usage/scaladoc/linking.md            |   9 +-
 .../docs/usage/scaladoc/search-engine.md      |  86 +++++++++++++++
 .../docs/usage/scaladoc/settings.md           |  12 ++-
 .../docs/usage/scaladoc/site-versioning.md    |  11 +-
 .../docs/usage/scaladoc/static-site.md        |  67 ++++++------
 .../changed-features/numeric-literals.md      |   7 --
 .../changed-features/type-checking.md         |   7 --
 docs/docs/reference/contextual/motivation.md  |  83 --------------
 docs/docs/usage/scaladoc/index.md             |  26 -----
 project/scripts/processDocs.sc                |  49 +++++++++
 132 files changed, 972 insertions(+), 579 deletions(-)
 create mode 100644 docs-for-scalalang/docs/reference/changed-features.md
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/compiler-plugins.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/eta-expansion-spec.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/eta-expansion.md (79%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/implicit-conversions-spec.md (93%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/implicit-conversions.md (90%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/implicit-resolution.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/imports.md (92%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/interpolation-escapes.md (85%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/lazy-vals-init.md (93%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/main-functions.md (85%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/match-syntax.md (88%)
 create mode 100644 docs-for-scalalang/docs/reference/changed-features/numeric-literals.md
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/operators.md (93%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/overload-resolution.md (92%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/pattern-bindings.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/pattern-matching.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/structural-types-spec.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/structural-types.md (97%)
 create mode 100644 docs-for-scalalang/docs/reference/changed-features/type-checking.md
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/type-inference.md (67%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/vararg-splices.md (89%)
 rename {docs => docs-for-scalalang}/docs/reference/changed-features/wildcards.md (95%)
 create mode 100644 docs-for-scalalang/docs/reference/contextual.md
 rename {docs => docs-for-scalalang}/docs/reference/contextual/by-name-context-parameters.md (93%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/context-bounds.md (92%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/context-functions-spec.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/context-functions.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/conversions.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/derivation-macro.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/derivation.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/extension-methods.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/given-imports.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/givens.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/multiversal-equality.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/relationship-implicits.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/right-associative-extension-methods.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/type-classes.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/contextual/using-clauses.md (92%)
 create mode 100644 docs-for-scalalang/docs/reference/dropped-features.md
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/auto-apply.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/class-shadowing-spec.md (89%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/class-shadowing.md (78%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/delayed-init.md (80%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/do-while.md (75%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/early-initializers.md (57%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/existential-types.md (90%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/limit22.md (57%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/macros.md (67%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/nonlocal-returns.md (80%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/package-objects.md (93%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/procedure-syntax.md (77%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/symlits.md (71%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/this-qualifier.md (81%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/type-projection.md (82%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/weak-conformance-spec.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/weak-conformance.md (89%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/wildcard-init.md (79%)
 rename {docs => docs-for-scalalang}/docs/reference/dropped-features/xml.md (89%)
 create mode 100644 docs-for-scalalang/docs/reference/enums.md
 rename {docs => docs-for-scalalang}/docs/reference/enums/adts.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/enums/desugarEnums.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/enums/enums.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/canthrow.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/erased-defs-spec.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/erased-defs.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/named-typeargs-spec.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/named-typeargs.md (100%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/numeric-literals.md (100%)
 rename {docs => docs-for-scalalang}/docs/reference/experimental/overview.md (100%)
 rename {docs => docs-for-scalalang}/docs/reference/features-classification.md (74%)
 create mode 100644 docs-for-scalalang/docs/reference/language-versions.md
 rename docs/docs/reference/metaprogramming/toc.md => docs-for-scalalang/docs/reference/metaprogramming.md (76%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/compiletime-ops.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/inline.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/macros-spec.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/macros.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/reflection.md (92%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/simple-smp.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/staging.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/metaprogramming/tasty-inspect.md (92%)
 create mode 100644 docs-for-scalalang/docs/reference/new-types.md
 rename {docs => docs-for-scalalang}/docs/reference/new-types/dependent-function-types-spec.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/dependent-function-types.md (84%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/intersection-types-spec.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/intersection-types.md (90%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/match-types.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/polymorphic-function-types.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/type-lambdas-spec.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/type-lambdas.md (69%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/union-types-spec.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/new-types/union-types.md (87%)
 create mode 100644 docs-for-scalalang/docs/reference/other-new-features.md
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/control-syntax.md (91%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/creator-applications.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/experimental-defs.md (100%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/explicit-nulls.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/export.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/indentation-experimental.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/indentation.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/kind-polymorphism.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/matchable.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/named-typeargs.md (69%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/opaques-details.md (94%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/opaques.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/open-classes.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/parameter-untupling-spec.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/parameter-untupling.md (81%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/safe-initialization.md (98%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/targetName.md (96%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/threadUnsafe-annotation.md (71%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/trait-parameters.md (91%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/transparent-traits.md (88%)
 rename {docs => docs-for-scalalang}/docs/reference/other-new-features/type-test.md (97%)
 rename {docs => docs-for-scalalang}/docs/reference/overview.md (70%)
 rename {docs => docs-for-scalalang}/docs/reference/soft-modifier.md (95%)
 rename {docs => docs-for-scalalang}/docs/reference/syntax.md (98%)
 rename {docs => docs-for-scalalang}/docs/usage/scaladoc/blog.md (77%)
 rename docs/docs/usage/scaladoc/scaladocDocstrings.md => docs-for-scalalang/docs/usage/scaladoc/docstrings.md (97%)
 create mode 100644 docs-for-scalalang/docs/usage/scaladoc/index.md
 rename docs/docs/usage/scaladoc/linkingDocumentation.md => docs-for-scalalang/docs/usage/scaladoc/linking.md (96%)
 create mode 100644 docs-for-scalalang/docs/usage/scaladoc/search-engine.md
 rename {docs => docs-for-scalalang}/docs/usage/scaladoc/settings.md (95%)
 rename {docs => docs-for-scalalang}/docs/usage/scaladoc/site-versioning.md (90%)
 rename docs/docs/usage/scaladoc/staticSite.md => docs-for-scalalang/docs/usage/scaladoc/static-site.md (77%)
 delete mode 100644 docs/docs/reference/changed-features/numeric-literals.md
 delete mode 100644 docs/docs/reference/changed-features/type-checking.md
 delete mode 100644 docs/docs/reference/contextual/motivation.md
 delete mode 100644 docs/docs/usage/scaladoc/index.md
 create mode 100644 project/scripts/processDocs.sc

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 1f60ab5b0236..c6604631362c 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -490,6 +490,9 @@ jobs:
       - name: Add SBT proxy repositories
         run: cp -vf .github/workflows/repositories /root/.sbt/ ; true
 
+      - name: Copy docs
+        run: ./bin/scala project/scripts/processDocs.sc 
+
       - name: Generate Website
         run: |
           ./project/scripts/genDocs -doc-snapshot
diff --git a/.github/workflows/scaladoc.yaml b/.github/workflows/scaladoc.yaml
index dbe0628751c1..843c11992de8 100644
--- a/.github/workflows/scaladoc.yaml
+++ b/.github/workflows/scaladoc.yaml
@@ -52,6 +52,9 @@ jobs:
       - name: Generate testcases documentation
         run: ./project/scripts/sbt scaladoc/generateTestcasesDocumentation
 
+      - name: Copy docs
+        run: ./bin/scala project/scripts/processDocs.sc 
+
       - name: Generate Scala 3 documentation
         run: ./project/scripts/sbt scaladoc/generateScalaDocumentation
 
diff --git a/docs-for-scalalang/docs/reference/changed-features.md b/docs-for-scalalang/docs/reference/changed-features.md
new file mode 100644
index 000000000000..c23a9031bef0
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/changed-features.md
@@ -0,0 +1,9 @@
+---
+title: "Other Changed Features"
+type: chapter
+num: 51
+previous-page: /scala3/reference/other-new-features/type-test
+next-page: /scala3/reference/changed-features/numeric-literals
+---
+
+The following pages document the features that have changed in Scala 3, compared to Scala 2.
diff --git a/docs/docs/reference/changed-features/compiler-plugins.md b/docs-for-scalalang/docs/reference/changed-features/compiler-plugins.md
similarity index 96%
rename from docs/docs/reference/changed-features/compiler-plugins.md
rename to docs-for-scalalang/docs/reference/changed-features/compiler-plugins.md
index 2a446e9cfb84..c77796d71df1 100644
--- a/docs/docs/reference/changed-features/compiler-plugins.md
+++ b/docs-for-scalalang/docs/reference/changed-features/compiler-plugins.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Compiler Plugins"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/compiler-plugins.html
+type: section
+num: 67
+previous-page: /scala3/reference/changed-features/eta-expansion
+next-page: /scala3/reference/changed-features/lazy-vals-init
 ---
 
 Compiler plugins are supported by Dotty (and Scala 3) since 0.9. There are two notable changes
diff --git a/docs/docs/reference/changed-features/eta-expansion-spec.md b/docs-for-scalalang/docs/reference/changed-features/eta-expansion-spec.md
similarity index 96%
rename from docs/docs/reference/changed-features/eta-expansion-spec.md
rename to docs-for-scalalang/docs/reference/changed-features/eta-expansion-spec.md
index 67f7606d5b15..78d021003cc4 100644
--- a/docs/docs/reference/changed-features/eta-expansion-spec.md
+++ b/docs-for-scalalang/docs/reference/changed-features/eta-expansion-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Automatic Eta Expansion - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/eta-expansion-spec.html
 ---
 
 ## Motivation
diff --git a/docs/docs/reference/changed-features/eta-expansion.md b/docs-for-scalalang/docs/reference/changed-features/eta-expansion.md
similarity index 79%
rename from docs/docs/reference/changed-features/eta-expansion.md
rename to docs-for-scalalang/docs/reference/changed-features/eta-expansion.md
index 2ae9af870a55..91516edca5a5 100644
--- a/docs/docs/reference/changed-features/eta-expansion.md
+++ b/docs-for-scalalang/docs/reference/changed-features/eta-expansion.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Automatic Eta Expansion"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/eta-expansion.html
+type: section
+num: 66
+previous-page: /scala3/reference/changed-features/pattern-matching
+next-page: /scala3/reference/changed-features/compiler-plugins
 ---
 
 The conversion of _methods_ into _functions_ has been improved and happens automatically for methods with one or more parameters.
@@ -36,7 +38,7 @@ rather than `next _`.
 The reason for excluding nullary methods from automatic eta expansion
 is that Scala implicitly inserts the `()` argument, which would
 conflict with eta expansion. Automatic `()` insertion is
-[limited](../dropped-features/auto-apply.md) in Scala 3, but the fundamental ambiguity
+[limited](../dropped-features/auto-apply.html) in Scala 3, but the fundamental ambiguity
 remains.
 
-[More details](eta-expansion-spec.md)
+[More details](eta-expansion-spec.html)
diff --git a/docs/docs/reference/changed-features/implicit-conversions-spec.md b/docs-for-scalalang/docs/reference/changed-features/implicit-conversions-spec.md
similarity index 93%
rename from docs/docs/reference/changed-features/implicit-conversions-spec.md
rename to docs-for-scalalang/docs/reference/changed-features/implicit-conversions-spec.md
index 47cfd941bf02..32bb641dbf74 100644
--- a/docs/docs/reference/changed-features/implicit-conversions-spec.md
+++ b/docs-for-scalalang/docs/reference/changed-features/implicit-conversions-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Implicit Conversions - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-conversions-spec.html
 ---
 
 ## Implementation
@@ -82,7 +82,7 @@ implicit val myConverter: Int => String = _.toString
 implicit val myConverter: Conversion[Int, String] = _.toString
 ```
 
-Note that implicit conversions are also affected by the [changes to implicit resolution](implicit-resolution.md) between Scala 2 and Scala 3.
+Note that implicit conversions are also affected by the [changes to implicit resolution](implicit-resolution.html) between Scala 2 and Scala 3.
 
 ## Motivation for the changes
 
@@ -109,9 +109,9 @@ will report a type error, because `Map` isn't an instance of
 Implicit values that are used as views should see their type changed to `Conversion`.
 
 For the migration of implicit conversions that are affected by the
-changes to implicit resolution, refer to the [Changes in Implicit Resolution](implicit-resolution.md) for more information.
+changes to implicit resolution, refer to the [Changes in Implicit Resolution](implicit-resolution.html) for more information.
 
 ## Reference
 
-For more information about implicit resolution, see [Changes in Implicit Resolution](implicit-resolution.md).
+For more information about implicit resolution, see [Changes in Implicit Resolution](implicit-resolution.html).
 Other details are available in [PR #2065](https://github.com/lampepfl/dotty/pull/2065).
diff --git a/docs/docs/reference/changed-features/implicit-conversions.md b/docs-for-scalalang/docs/reference/changed-features/implicit-conversions.md
similarity index 90%
rename from docs/docs/reference/changed-features/implicit-conversions.md
rename to docs-for-scalalang/docs/reference/changed-features/implicit-conversions.md
index 2ee2583d3cd8..39b4cde31e63 100644
--- a/docs/docs/reference/changed-features/implicit-conversions.md
+++ b/docs-for-scalalang/docs/reference/changed-features/implicit-conversions.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Implicit Conversions"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-conversions.html
+type: section
+num: 60
+previous-page: /scala3/reference/changed-features/implicit-resolution
+next-page: /scala3/reference/changed-features/overload-resolution
 ---
 
 An _implicit conversion_, also called _view_, is a conversion that
@@ -61,4 +63,4 @@ implicitly[Ordering[A]] // Ok, will use the implicit conversion from
                         // `A` to `Int` and the `Ordering` for `Int`.
 ```
 
-[More details](implicit-conversions-spec.md)
+[More details](implicit-conversions-spec.html)
diff --git a/docs/docs/reference/changed-features/implicit-resolution.md b/docs-for-scalalang/docs/reference/changed-features/implicit-resolution.md
similarity index 98%
rename from docs/docs/reference/changed-features/implicit-resolution.md
rename to docs-for-scalalang/docs/reference/changed-features/implicit-resolution.md
index 8cb20fd51141..22d6ba7d1fca 100644
--- a/docs/docs/reference/changed-features/implicit-resolution.md
+++ b/docs-for-scalalang/docs/reference/changed-features/implicit-resolution.md
@@ -1,8 +1,11 @@
 ---
-layout: doc-page
 title: "Changes in Implicit Resolution"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-resolution.html
+type: section
+num: 59
+previous-page: /scala3/reference/changed-features/type-inference
+next-page: /scala3/reference/changed-features/implicit-conversions
 ---
+
 This section describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Scala 3.
 Implicit resolution uses a new algorithm which caches implicit results
 more aggressively for performance. There are also some changes that
diff --git a/docs/docs/reference/changed-features/imports.md b/docs-for-scalalang/docs/reference/changed-features/imports.md
similarity index 92%
rename from docs/docs/reference/changed-features/imports.md
rename to docs-for-scalalang/docs/reference/changed-features/imports.md
index 7d364ce68b92..39568769a270 100644
--- a/docs/docs/reference/changed-features/imports.md
+++ b/docs-for-scalalang/docs/reference/changed-features/imports.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Imports"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/imports.html
+type: section
+num: 56
+previous-page: /scala3/reference/changed-features/wildcards
+next-page: /scala3/reference/changed-features/type-checking
 ---
 
 The syntax of wildcard and renaming imports (and exports) has changed.
diff --git a/docs/docs/reference/changed-features/interpolation-escapes.md b/docs-for-scalalang/docs/reference/changed-features/interpolation-escapes.md
similarity index 85%
rename from docs/docs/reference/changed-features/interpolation-escapes.md
rename to docs-for-scalalang/docs/reference/changed-features/interpolation-escapes.md
index d5b3a82d94cc..c61ef9828178 100644
--- a/docs/docs/reference/changed-features/interpolation-escapes.md
+++ b/docs-for-scalalang/docs/reference/changed-features/interpolation-escapes.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Escapes in interpolations"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/interpolation-escapes.html
 ---
 
 In Scala 2 there is no straightforward way to represent a single quote character `"` in a single quoted interpolation. A `\` character can't be used for that because interpolators themselves decide how to handle escaping, so the parser doesn't know whether the `"` should be escaped or used as a terminator.
diff --git a/docs/docs/reference/changed-features/lazy-vals-init.md b/docs-for-scalalang/docs/reference/changed-features/lazy-vals-init.md
similarity index 93%
rename from docs/docs/reference/changed-features/lazy-vals-init.md
rename to docs-for-scalalang/docs/reference/changed-features/lazy-vals-init.md
index 10abbb80a2be..a065cebb2a49 100644
--- a/docs/docs/reference/changed-features/lazy-vals-init.md
+++ b/docs-for-scalalang/docs/reference/changed-features/lazy-vals-init.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
-title: Lazy Vals initialization
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/lazy-vals-init.html
+title: Lazy Vals Initialization
+type: section
+num: 68
+previous-page: /scala3/reference/changed-features/compiler-plugins
+next-page: /scala3/reference/changed-features/main-functions
 ---
 
 Scala 3 implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)
diff --git a/docs/docs/reference/changed-features/main-functions.md b/docs-for-scalalang/docs/reference/changed-features/main-functions.md
similarity index 85%
rename from docs/docs/reference/changed-features/main-functions.md
rename to docs-for-scalalang/docs/reference/changed-features/main-functions.md
index 9d166492d962..6f035278ed05 100644
--- a/docs/docs/reference/changed-features/main-functions.md
+++ b/docs-for-scalalang/docs/reference/changed-features/main-functions.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Main Methods"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/main-functions.html
+type: section
+num: 69
+previous-page: /scala3/reference/changed-features/lazy-vals-init
+next-page: /scala3/reference/dropped-features
 ---
 
 Scala 3 offers a new way to define programs that can be invoked from the command line:
@@ -57,7 +59,7 @@ The Scala compiler generates a program from a `@main` method `f` as follows:
  - The class has a static method `main` with the usual signature. It takes an `Array[String]`
    as argument and returns `Unit`.
  - The generated `main` method calls method `f` with arguments converted using
-   methods in the [`scala.util.CommandLineParser`](https://dotty.epfl.ch/api/scala/util/CommandLineParser$.html) object.
+   methods in the [`scala.util.CommandLineParser`](https://scala-lang.org/api/3.x/scala/util/CommandLineParser$.html) object.
 
 For instance, the `happyBirthDay` method above would generate additional code equivalent to the following class:
 
@@ -85,5 +87,5 @@ object happyBirthday extends App:
   ...
 ```
 
-The previous functionality of `App`, which relied on the "magic" [`DelayedInit`](../dropped-features/delayed-init.md) trait, is no longer available. [`App`](https://dotty.epfl.ch/api/scala/App.html) still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build
+The previous functionality of `App`, which relied on the "magic" [`DelayedInit`]({% link _scala3-reference/dropped-features/delayed-init.md %}) trait, is no longer available. [`App`](https://scala-lang.org/api/3.x/scala/App.html) still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build
 between Scala 2 and Scala 3, it is recommended to use an explicit `main` method with an `Array[String]` argument instead.
diff --git a/docs/docs/reference/changed-features/match-syntax.md b/docs-for-scalalang/docs/reference/changed-features/match-syntax.md
similarity index 88%
rename from docs/docs/reference/changed-features/match-syntax.md
rename to docs-for-scalalang/docs/reference/changed-features/match-syntax.md
index f7a7c17075d3..7ebc85b6d003 100644
--- a/docs/docs/reference/changed-features/match-syntax.md
+++ b/docs-for-scalalang/docs/reference/changed-features/match-syntax.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Match Expressions"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/match-syntax.html
+type: section
+num: 62
+previous-page: /scala3/reference/changed-features/overload-resolution
+next-page: /scala3/reference/changed-features/vararg-splices
 ---
 
 The syntactical precedence of match expressions has been changed.
@@ -47,7 +49,7 @@ The syntactical precedence of match expressions has been changed.
 
 The new syntax of match expressions is as follows.
 
-```ebnf
+```
 InfixExpr    ::=  ...
                |  InfixExpr MatchClause
 SimpleExpr   ::=  ...
diff --git a/docs-for-scalalang/docs/reference/changed-features/numeric-literals.md b/docs-for-scalalang/docs/reference/changed-features/numeric-literals.md
new file mode 100644
index 000000000000..8a21d97bd4a4
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/changed-features/numeric-literals.md
@@ -0,0 +1,9 @@
+---
+title: "Numeric Literals"
+type: section
+num: 52
+previous-page: /scala3/reference/changed-features
+next-page: /scala3/reference/changed-features/structural-types
+---
+
+[Document was moved](../experimental/numeric-literals.md)
\ No newline at end of file
diff --git a/docs/docs/reference/changed-features/operators.md b/docs-for-scalalang/docs/reference/changed-features/operators.md
similarity index 93%
rename from docs/docs/reference/changed-features/operators.md
rename to docs-for-scalalang/docs/reference/changed-features/operators.md
index 495eb8c5ede9..5e05c6bfbcae 100644
--- a/docs/docs/reference/changed-features/operators.md
+++ b/docs-for-scalalang/docs/reference/changed-features/operators.md
@@ -1,13 +1,15 @@
 ---
-layout: doc-page
 title: "Rules for Operators"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/operators.html
+type: section
+num: 54
+previous-page: /scala3/reference/changed-features/structural-types
+next-page: /scala3/reference/changed-features/wildcards
 ---
 
 The rules for infix operators have changed in some parts:
 
 First, an alphanumeric method can be used as an infix operator only if its definition carries an `infix` modifier. Second, it is recommended (but not enforced) to
-augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.md). Finally,
+augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.html). Finally,
 a syntax change allows infix operators to be written on the left in a multi-line expression.
 
 ## The `infix` Modifier
@@ -97,7 +99,7 @@ or if the `-source future` option is given in Dotty/Scala 3.
 
 ## The `@targetName` Annotation
 
-It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.md) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
+It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.html) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
 
  - It helps interoperability between Scala and other languages. One can call
    a Scala-defined symbolic operator from another language using its target name,
diff --git a/docs/docs/reference/changed-features/overload-resolution.md b/docs-for-scalalang/docs/reference/changed-features/overload-resolution.md
similarity index 92%
rename from docs/docs/reference/changed-features/overload-resolution.md
rename to docs-for-scalalang/docs/reference/changed-features/overload-resolution.md
index e6c929f7a2ef..6b203299707f 100644
--- a/docs/docs/reference/changed-features/overload-resolution.md
+++ b/docs-for-scalalang/docs/reference/changed-features/overload-resolution.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Overload Resolution"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/overload-resolution.html
+type: section
+num: 61
+previous-page: /scala3/reference/changed-features/implicit-conversions
+next-page: /scala3/reference/changed-features/match-syntax
 ---
 
 Overload resolution in Scala 3 improves on Scala 2 in two ways.
@@ -42,7 +44,7 @@ resolution yields several competing alternatives when `n >= 1` parameter lists a
 into account, then resolution re-tried using `n + 1` argument lists.
 
 This change is motivated by the new language feature
-[extension methods](../contextual/extension-methods.md), where emerges the need to do
+[extension methods](../contextual/extension-methods.html), where emerges the need to do
 overload resolution based on additional argument blocks.
 
 ## Parameter Types of Function Values
diff --git a/docs/docs/reference/changed-features/pattern-bindings.md b/docs-for-scalalang/docs/reference/changed-features/pattern-bindings.md
similarity index 94%
rename from docs/docs/reference/changed-features/pattern-bindings.md
rename to docs-for-scalalang/docs/reference/changed-features/pattern-bindings.md
index 978bff2d7d7e..307ff6387cce 100644
--- a/docs/docs/reference/changed-features/pattern-bindings.md
+++ b/docs-for-scalalang/docs/reference/changed-features/pattern-bindings.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Pattern Bindings"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html
+type: section
+num: 64
+previous-page: /scala3/reference/changed-features/vararg-splices
+next-page: /scala3/reference/changed-features/pattern-matching
 ---
 
 In Scala 2, pattern bindings in `val` definitions and `for` expressions are
diff --git a/docs/docs/reference/changed-features/pattern-matching.md b/docs-for-scalalang/docs/reference/changed-features/pattern-matching.md
similarity index 96%
rename from docs/docs/reference/changed-features/pattern-matching.md
rename to docs-for-scalalang/docs/reference/changed-features/pattern-matching.md
index b9115fe93233..2216d145a80d 100644
--- a/docs/docs/reference/changed-features/pattern-matching.md
+++ b/docs-for-scalalang/docs/reference/changed-features/pattern-matching.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Option-less pattern matching"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-matching.html
+type: section
+num: 65
+previous-page: /scala3/reference/changed-features/pattern-bindings
+next-page: /scala3/reference/changed-features/eta-expansion
 ---
 
 The implementation of pattern matching in Scala 3 was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
@@ -241,4 +243,4 @@ Abstract type testing with `ClassTag` is replaced with `TypeTest` or the alias `
 - pattern `_: X` for an abstract type requires a `TypeTest` in scope
 - pattern `x @ X()` for an unapply that takes an abstract type requires a `TypeTest` in scope
 
-[More details on `TypeTest`](../other-new-features/type-test.md)
+[More details on `TypeTest`](../other-new-features/type-test.html)
diff --git a/docs/docs/reference/changed-features/structural-types-spec.md b/docs-for-scalalang/docs/reference/changed-features/structural-types-spec.md
similarity index 97%
rename from docs/docs/reference/changed-features/structural-types-spec.md
rename to docs-for-scalalang/docs/reference/changed-features/structural-types-spec.md
index 5c99afbcc1bb..eb7e653a780a 100644
--- a/docs/docs/reference/changed-features/structural-types-spec.md
+++ b/docs-for-scalalang/docs/reference/changed-features/structural-types-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Programmatic Structural Types - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/structural-types-spec.html
 ---
 
 ## Syntax
@@ -81,7 +81,7 @@ and `Rs` are structural refinement declarations, and given `v.a` of type `U`, we
 
 Note that `v`'s static type does not necessarily have to conform to `Selectable`, nor does it need to have `selectDynamic` and `applyDynamic` as members. It suffices that there is an implicit
 conversion that can turn `v` into a `Selectable`, and the selection methods could also be available as
-[extension methods](../contextual/extension-methods.md).
+[extension methods](../contextual/extension-methods.html).
 
 ## Limitations of Structural Types
 
diff --git a/docs/docs/reference/changed-features/structural-types.md b/docs-for-scalalang/docs/reference/changed-features/structural-types.md
similarity index 97%
rename from docs/docs/reference/changed-features/structural-types.md
rename to docs-for-scalalang/docs/reference/changed-features/structural-types.md
index 904525a4655d..fe20a3aa5483 100644
--- a/docs/docs/reference/changed-features/structural-types.md
+++ b/docs-for-scalalang/docs/reference/changed-features/structural-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Programmatic Structural Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/structural-types.html
+type: section
+num: 53
+previous-page: /scala3/reference/changed-features/numeric-literals
+next-page: /scala3/reference/changed-features/operators
 ---
 
 ## Motivation
@@ -189,4 +191,4 @@ differences.
   `java.lang.Class` arguments indicating the method's formal parameter types.
   `Dynamic` comes with `updateDynamic`.
 
-[More details](structural-types-spec.md)
+[More details](structural-types-spec.html)
diff --git a/docs-for-scalalang/docs/reference/changed-features/type-checking.md b/docs-for-scalalang/docs/reference/changed-features/type-checking.md
new file mode 100644
index 000000000000..81ca345a6c7e
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/changed-features/type-checking.md
@@ -0,0 +1,9 @@
+---
+title: "Changes in Type Checking"
+type: section
+num: 57
+previous-page: /scala3/reference/changed-features/imports
+next-page: /scala3/reference/changed-features/type-inference
+---
+
+*** **TO BE FILLED IN** ***
diff --git a/docs/docs/reference/changed-features/type-inference.md b/docs-for-scalalang/docs/reference/changed-features/type-inference.md
similarity index 67%
rename from docs/docs/reference/changed-features/type-inference.md
rename to docs-for-scalalang/docs/reference/changed-features/type-inference.md
index 020878444914..873c91831210 100644
--- a/docs/docs/reference/changed-features/type-inference.md
+++ b/docs-for-scalalang/docs/reference/changed-features/type-inference.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Type Inference"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/type-inference.html
+type: section
+num: 58
+previous-page: /scala3/reference/changed-features/type-checking
+next-page: /scala3/reference/changed-features/implicit-resolution
 ---
 
 For more information, see the two presentations
diff --git a/docs/docs/reference/changed-features/vararg-splices.md b/docs-for-scalalang/docs/reference/changed-features/vararg-splices.md
similarity index 89%
rename from docs/docs/reference/changed-features/vararg-splices.md
rename to docs-for-scalalang/docs/reference/changed-features/vararg-splices.md
index d5a3b8eb6ab4..efa7f034acea 100644
--- a/docs/docs/reference/changed-features/vararg-splices.md
+++ b/docs-for-scalalang/docs/reference/changed-features/vararg-splices.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Vararg Splices"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/vararg-splices.html
+type: section
+num: 63
+previous-page: /scala3/reference/changed-features/match-syntax
+next-page: /scala3/reference/changed-features/pattern-bindings
 ---
 
 The syntax of vararg splices in patterns and function arguments has changed. The new syntax uses a postfix `*`,  analogously to how a vararg parameter is declared.
@@ -24,7 +26,7 @@ The old syntax for splice arguments will be phased out.
 
 ## Syntax
 
-```ebnf
+```
 ArgumentPatterns  ::=  ‘(’ [Patterns] ‘)’
                     |  ‘(’ [Patterns ‘,’] Pattern2 ‘*’ ‘)’
 
diff --git a/docs/docs/reference/changed-features/wildcards.md b/docs-for-scalalang/docs/reference/changed-features/wildcards.md
similarity index 95%
rename from docs/docs/reference/changed-features/wildcards.md
rename to docs-for-scalalang/docs/reference/changed-features/wildcards.md
index de0b83339c22..fdf69fdcd954 100644
--- a/docs/docs/reference/changed-features/wildcards.md
+++ b/docs-for-scalalang/docs/reference/changed-features/wildcards.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: Wildcard Arguments in Types
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/wildcards.html
+type: section
+num: 55
+previous-page: /scala3/reference/changed-features/operators
+next-page: /scala3/reference/changed-features/imports
 ---
 
 The syntax of wildcard arguments in types has changed from `_` to `?`. Example:
diff --git a/docs-for-scalalang/docs/reference/contextual.md b/docs-for-scalalang/docs/reference/contextual.md
new file mode 100644
index 000000000000..1dfc5e6baa97
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/contextual.md
@@ -0,0 +1,85 @@
+---
+title: "Contextual Abstractions"
+type: chapter
+num: 13
+previous-page: /scala3/reference/enums/desugarEnums
+next-page: /scala3/reference/contextual/givens
+---
+
+### Critique of the Status Quo
+
+Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them.
+
+Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g [Rust's traits](https://doc.rust-lang.org/rust-by-example/trait.html) or [Swift's protocol extensions](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID521). Design proposals are also on the table for Kotlin as [compile time dependency resolution](https://github.com/Kotlin/KEEP/blob/e863b25f8b3f2e9b9aaac361c6ee52be31453ee0/proposals/compile-time-dependency-resolution.md), for C# as [Shapes and Extensions](https://github.com/dotnet/csharplang/issues/164)
+or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as [Coq](https://coq.inria.fr/refman/language/extensions/implicit-arguments.html) or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html).
+
+Even though these designs use widely different terminology, they are all variants of the core idea of _term inference_. Given a type, the compiler synthesizes a "canonical" term that has that type. Scala embodies the idea in a purer form than most other languages: An implicit parameter directly leads to an inferred argument term that could also be written down explicitly. By contrast, type class based designs are less direct since they hide term inference behind some form of type classification and do not offer the option of writing the inferred quantities (typically, dictionaries) explicitly.
+
+Given that term inference is where the industry is heading, and given that Scala has it in a very pure form, how come implicits are not more popular? In fact, it's fair to say that implicits are at the same time Scala's most distinguished and most controversial feature. I believe this is due to a number of aspects that together make implicits harder to learn than necessary and also make it harder to prevent abuses.
+
+Particular criticisms are:
+
+1. Being very powerful, implicits are easily over-used and mis-used. This observation holds in almost all cases when we talk about _implicit conversions_, which, even though conceptually different, share the same syntax with other implicit definitions. For instance, regarding the two definitions
+
+    ```scala
+    implicit def i1(implicit x: T): C[T] = ...
+    implicit def i2(x: T): C[T] = ...
+    ```
+
+   the first of these is a conditional implicit _value_, the second an implicit _conversion_. Conditional implicit values are a cornerstone for expressing type classes, whereas most applications of implicit conversions have turned out to be of dubious value. The problem is that many newcomers to the language start with defining implicit conversions since they are easy to understand and seem powerful and convenient. Scala 3 will put under a language flag both definitions and applications of "undisciplined" implicit conversions between types defined elsewhere. This is a useful step to push back against overuse of implicit conversions. But the problem remains that syntactically, conversions and values just look too similar for comfort.
+
+2. Another widespread abuse is over-reliance on implicit imports. This often leads to inscrutable type errors that go away with the right import incantation, leaving a feeling of frustration. Conversely, it is hard to see what implicits a program uses since implicits can hide anywhere in a long list of imports.
+
+3. The syntax of implicit definitions is too minimal. It consists of a single modifier, `implicit`, that can be attached to a large number of language constructs. A problem with this for newcomers is that it conveys mechanism instead of intent. For instance, a type class instance is an implicit object or val if unconditional and an implicit def with implicit parameters referring to some class if conditional. This describes precisely what the implicit definitions translate to -- just drop the `implicit` modifier, and that's it! But the cues that define intent are rather indirect and can be easily misread, as demonstrated by the definitions of `i1` and `i2` above.
+
+4. The syntax of implicit parameters also has shortcomings. While implicit _parameters_ are designated specifically, arguments are not. Passing an argument to an implicit parameter looks like a regular application `f(arg)`. This is problematic because it means there can be confusion regarding what parameter gets instantiated in a call. For instance, in
+
+   ```scala
+   def currentMap(implicit ctx: Context): Map[String, Int]
+   ```
+
+   one cannot write `currentMap("abc")` since the string `"abc"` is taken as explicit argument to the implicit `ctx` parameter. One has to write `currentMap.apply("abc")` instead, which is awkward and irregular. For the same reason, a method definition can only have one implicit parameter section and it must always come last. This restriction not only reduces orthogonality, but also prevents some useful program constructs, such as a method with a regular parameter whose type depends on an implicit value. Finally, it's also a bit annoying that implicit parameters must have a name, even though in many cases that name is never referenced.
+
+5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but tools like [Scaladoc](https://docs.scala-lang.org/overviews/scaladoc/overview.html) that are based on static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Scala 3 compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
+
+None of the shortcomings is fatal, after all implicits are very widely used, and many libraries and applications rely on them. But together, they make code using implicits a lot more cumbersome and less clear than it could be.
+
+Historically, many of these shortcomings come from the way implicits were gradually "discovered" in Scala. Scala originally had only implicit conversions with the intended use case of "extending" a class or trait after it was defined, i.e. what is expressed by implicit classes in later versions of Scala. Implicit parameters and instance definitions came later in 2006 and we picked similar syntax since it seemed convenient. For the same reason, no effort was made to distinguish implicit imports or arguments from normal ones.
+
+Existing Scala programmers by and large have gotten used to the status quo and see little need for change. But for newcomers this status quo presents a big hurdle. I believe if we want to overcome that hurdle, we should take a step back and allow ourselves to consider a radically new design.
+
+### The New Design
+
+The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes:
+
+1. [Given Instances](./contextual/givens.html) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
+
+2. [Using Clauses](./contextual/using-clauses.html) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition.
+
+3. ["Given" Imports](./contextual/given-imports.html) are a new class of import selectors that specifically import
+   givens and nothing else.
+
+4. [Implicit Conversions](./contextual/conversions.html) are now expressed as given instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out.
+
+This section also contains pages describing other language features that are related to context abstraction. These are:
+
+- [Context Bounds](./contextual/context-bounds.html), which carry over unchanged.
+- [Extension Methods](./contextual/extension-methods.html) replace implicit classes in a way that integrates better with type classes.
+- [Implementing Type Classes](./contextual/type-classes.html) demonstrates how some common type classes can be implemented using the new constructs.
+- [Type Class Derivation](./contextual/derivation.html) introduces constructs to automatically derive type class instances for ADTs.
+- [Multiversal Equality](./contextual/multiversal-equality.html) introduces a special type class to support type safe equality.
+- [Context Functions](./contextual/context-functions.html) provide a way to abstract over context parameters.
+- [By-Name Context Parameters](./contextual/by-name-context-parameters.html) are an essential tool to define recursive synthesized values without looping.
+- [Relationship with Scala 2 Implicits](./contextual/relationship-implicits.html) discusses the relationship between old-style implicits and new-style givens and how to migrate from one to the other.
+
+Overall, the new design achieves a better separation of term inference from the rest of the language: There is a single way to define givens instead of a multitude of forms all taking an `implicit` modifier. There is a single way to introduce implicit parameters and arguments instead of conflating implicit with normal arguments. There is a separate way to import givens that does not allow them to hide in a sea of normal imports. And there is a single way to define an implicit conversion which is clearly marked as such and does not require special syntax.
+
+This design thus avoids feature interactions and makes the language more consistent and orthogonal. It will make implicits easier to learn and harder to abuse. It will greatly improve the clarity of the 95% of Scala programs that use implicits. It has thus the potential to fulfil the promise of term inference in a principled way that is also accessible and friendly.
+
+Could we achieve the same goals by tweaking existing implicits? After having tried for a long time, I believe now that this is impossible.
+
+- First, some of the problems are clearly syntactic and require different syntax to solve them.
+- Second, there is the problem how to migrate. We cannot change the rules in mid-flight. At some stage of language evolution we need to accommodate both the new and the old rules. With a syntax change, this is easy: Introduce the new syntax with new rules, support the old syntax for a while to facilitate cross compilation, deprecate and phase out the old syntax at some later time. Keeping the same syntax does not offer this path, and in fact does not seem to offer any viable path for evolution
+- Third, even if we would somehow succeed with migration, we still have the problem
+  how to teach this. We cannot make existing tutorials go away. Almost all existing tutorials start with implicit conversions, which will go away; they use normal imports, which will go away, and they explain calls to methods with implicit parameters by expanding them to plain applications, which will also go away. This means that we'd have
+  to add modifications and qualifications to all existing literature and courseware, likely causing more confusion with beginners instead of less. By contrast, with a new syntax there is a clear criterion: Any book or courseware that mentions `implicit` is outdated and should be updated.
diff --git a/docs/docs/reference/contextual/by-name-context-parameters.md b/docs-for-scalalang/docs/reference/contextual/by-name-context-parameters.md
similarity index 93%
rename from docs/docs/reference/contextual/by-name-context-parameters.md
rename to docs-for-scalalang/docs/reference/contextual/by-name-context-parameters.md
index 8e8427f7457f..c1777b625912 100644
--- a/docs/docs/reference/contextual/by-name-context-parameters.md
+++ b/docs-for-scalalang/docs/reference/contextual/by-name-context-parameters.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "By-Name Context Parameters"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/by-name-context-parameters.html
+type: section
+num: 25
+previous-page: /scala3/reference/contextual/conversions
+next-page: /scala3/reference/contextual/relationship-implicits
 ---
 
 Context parameters can be declared by-name to avoid a divergent inferred expansion. Example:
diff --git a/docs/docs/reference/contextual/context-bounds.md b/docs-for-scalalang/docs/reference/contextual/context-bounds.md
similarity index 92%
rename from docs/docs/reference/contextual/context-bounds.md
rename to docs-for-scalalang/docs/reference/contextual/context-bounds.md
index e336f00cc463..5c7ea5cd5936 100644
--- a/docs/docs/reference/contextual/context-bounds.md
+++ b/docs-for-scalalang/docs/reference/contextual/context-bounds.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Context Bounds"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-bounds.html
+type: section
+num: 17
+previous-page: /scala3/reference/contextual/using-clauses
+next-page: /scala3/reference/contextual/given-imports
 ---
 
 A context bound is a shorthand for expressing the common pattern of a context parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:
diff --git a/docs/docs/reference/contextual/context-functions-spec.md b/docs-for-scalalang/docs/reference/contextual/context-functions-spec.md
similarity index 95%
rename from docs/docs/reference/contextual/context-functions-spec.md
rename to docs-for-scalalang/docs/reference/contextual/context-functions-spec.md
index bca56acad58d..9267eea23f49 100644
--- a/docs/docs/reference/contextual/context-functions-spec.md
+++ b/docs-for-scalalang/docs/reference/contextual/context-functions-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Context Functions - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-functions-spec.html
 ---
 
 ## Syntax
@@ -66,7 +66,7 @@ itself a context function literal. This is analogous to the automatic
 insertion of `scala.Function0` around expressions in by-name argument position.
 
 Context function types generalize to `N > 22` in the same way that function types do, see [the corresponding
-documentation](../dropped-features/limit22.md).
+documentation](../dropped-features/limit22.html).
 
 ## Examples
 
diff --git a/docs/docs/reference/contextual/context-functions.md b/docs-for-scalalang/docs/reference/contextual/context-functions.md
similarity index 96%
rename from docs/docs/reference/contextual/context-functions.md
rename to docs-for-scalalang/docs/reference/contextual/context-functions.md
index c556a0cadf8f..1b930b3c8dfc 100644
--- a/docs/docs/reference/contextual/context-functions.md
+++ b/docs-for-scalalang/docs/reference/contextual/context-functions.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Context Functions"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-functions.html
+type: section
+num: 23
+previous-page: /scala3/reference/contextual/multiversal-equality
+next-page: /scala3/reference/contextual/conversions
 ---
 
 _Context functions_ are functions with (only) context parameters.
@@ -151,4 +153,4 @@ val s =
 For more information, see the [blog article](https://www.scala-lang.org/blog/2016/12/07/implicit-function-types.html),
 (which uses a different syntax that has been superseded).
 
-[More details](./context-functions-spec.md)
+[More details](./context-functions-spec.html)
diff --git a/docs/docs/reference/contextual/conversions.md b/docs-for-scalalang/docs/reference/contextual/conversions.md
similarity index 95%
rename from docs/docs/reference/contextual/conversions.md
rename to docs-for-scalalang/docs/reference/contextual/conversions.md
index 9928719663e2..5a222515adea 100644
--- a/docs/docs/reference/contextual/conversions.md
+++ b/docs-for-scalalang/docs/reference/contextual/conversions.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Implicit Conversions"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/conversions.html
+type: section
+num: 24
+previous-page: /scala3/reference/contextual/context-functions
+next-page: /scala3/reference/contextual/by-name-context-parameters
 ---
 
 Implicit conversions are defined by given instances of the `scala.Conversion` class.
diff --git a/docs/docs/reference/contextual/derivation-macro.md b/docs-for-scalalang/docs/reference/contextual/derivation-macro.md
similarity index 95%
rename from docs/docs/reference/contextual/derivation-macro.md
rename to docs-for-scalalang/docs/reference/contextual/derivation-macro.md
index 47c1ee0d2e55..c9c657d7804f 100644
--- a/docs/docs/reference/contextual/derivation-macro.md
+++ b/docs-for-scalalang/docs/reference/contextual/derivation-macro.md
@@ -1,10 +1,10 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "How to write a type class `derived` method using macros"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/derivation-macro.html
 ---
 
-In the main [derivation](./derivation.md) documentation page, we explained the
+In the main [derivation](./derivation.html) documentation page, we explained the
 details behind `Mirror`s and type class derivation. Here we demonstrate how to
 implement a type class `derived` method using macros only. We follow the same
 example of deriving `Eq` instances and for simplicity we support a `Product`
@@ -98,7 +98,7 @@ One additional difference with the body of `derived` here as opposed to the one
 with `inline` is that with macros we need to synthesize the body of the code during the
 macro-expansion time. That is the rationale behind the `eqProductBody` function.
 Assuming that we calculate the equality of two `Person`s defined with a case
-class that holds a name of type [`String`](https://dotty.epfl.ch/api/scala/Predef$.html#String)
+class that holds a name of type [`String`](https://scala-lang.org/api/3.x/scala/Predef$.html#String-0)
 and an age of type `Int`, the equality check we want to generate is the following:
 
 ```scala
@@ -109,7 +109,7 @@ and an age of type `Int`, the equality check we want to generate is the followin
 
 ## Calling the derived method inside the macro
 
-Following the rules in [Macros](../metaprogramming/toc.md) we create two methods.
+Following the rules in [Macros](../metaprogramming.html) we create two methods.
 One that hosts the top-level splice `eqv` and one that is the implementation.
 Alternatively and what is shown below is that we can call the `eqv` method
 directly. The `eqGen` can trigger the derivation.
diff --git a/docs/docs/reference/contextual/derivation.md b/docs-for-scalalang/docs/reference/contextual/derivation.md
similarity index 98%
rename from docs/docs/reference/contextual/derivation.md
rename to docs-for-scalalang/docs/reference/contextual/derivation.md
index 0a4a6b30968c..d7ec09c3705c 100644
--- a/docs/docs/reference/contextual/derivation.md
+++ b/docs-for-scalalang/docs/reference/contextual/derivation.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Type Class Derivation"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/derivation.html
+type: section
+num: 21
+previous-page: /scala3/reference/contextual/type-classes
+next-page: /scala3/reference/contextual/multiversal-equality
 ---
 
 Type class derivation is a way to automatically generate given instances for type classes which satisfy some simple
@@ -336,7 +338,7 @@ inline def derived[A](using gen: K0.Generic[A]): Eq[A] =
 The framework described here enables all three of these approaches without mandating any of them.
 
 For a brief discussion on how to use macros to write a type class `derived`
-method please read more at [How to write a type class `derived` method using macros](./derivation-macro.md).
+method please read more at [How to write a type class `derived` method using macros](./derivation-macro.html).
 
 ### Deriving instances elsewhere
 
@@ -354,7 +356,7 @@ hand side of this definition in the same way as an instance defined in ADT compa
 
 ### Syntax
 
-```ebnf
+```
 Template          ::=  InheritClauses [TemplateBody]
 EnumDef           ::=  id ClassConstr InheritClauses EnumBody
 InheritClauses    ::=  [‘extends’ ConstrApps] [‘derives’ QualId {‘,’ QualId}]
diff --git a/docs/docs/reference/contextual/extension-methods.md b/docs-for-scalalang/docs/reference/contextual/extension-methods.md
similarity index 97%
rename from docs/docs/reference/contextual/extension-methods.md
rename to docs-for-scalalang/docs/reference/contextual/extension-methods.md
index 46300ac1079f..06364baa507f 100644
--- a/docs/docs/reference/contextual/extension-methods.md
+++ b/docs-for-scalalang/docs/reference/contextual/extension-methods.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Extension Methods"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html
+type: section
+num: 19
+previous-page: /scala3/reference/contextual/given-imports
+next-page: /scala3/reference/contextual/type-classes
 ---
 
 Extension methods allow one to add methods to a type after the type is defined. Example:
@@ -61,7 +63,7 @@ the right-associative operator `+:` to an extension method. This is analogous
 to the implementation of right binding operators as normal methods. The Scala
 compiler preprocesses an infix operation `x +: xs` to `xs.+:(x)`, so the extension
 method ends up being applied to the sequence as first argument (in other words, the
-two swaps cancel each other out). See [here for details](./right-associative-extension-methods.md).
+two swaps cancel each other out). See [here for details](./right-associative-extension-methods.html).
 
 ### Generic Extensions
 
@@ -283,9 +285,9 @@ def position(s: String)(ch: Char, n: Int): Int =
 ### Syntax
 
 Here are the syntax changes for extension methods and collective extensions relative
-to the [current syntax](../syntax.md).
+to the [current syntax](../syntax.html).
 
-```ebnf
+```
 BlockStat         ::=  ... | Extension
 TemplateStat      ::=  ... | Extension
 TopStat           ::=  ... | Extension
diff --git a/docs/docs/reference/contextual/given-imports.md b/docs-for-scalalang/docs/reference/contextual/given-imports.md
similarity index 96%
rename from docs/docs/reference/contextual/given-imports.md
rename to docs-for-scalalang/docs/reference/contextual/given-imports.md
index 3e3bc3d275cc..7e498415888e 100644
--- a/docs/docs/reference/contextual/given-imports.md
+++ b/docs-for-scalalang/docs/reference/contextual/given-imports.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Importing Givens"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/given-imports.html
+type: section
+num: 18
+previous-page: /scala3/reference/contextual/context-bounds
+next-page: /scala3/reference/contextual/extension-methods
 ---
 
 A special form of import wildcard selector is used to import given instances. Example:
diff --git a/docs/docs/reference/contextual/givens.md b/docs-for-scalalang/docs/reference/contextual/givens.md
similarity index 97%
rename from docs/docs/reference/contextual/givens.md
rename to docs-for-scalalang/docs/reference/contextual/givens.md
index fba3effdd495..0ca25c068c93 100644
--- a/docs/docs/reference/contextual/givens.md
+++ b/docs-for-scalalang/docs/reference/contextual/givens.md
@@ -1,11 +1,13 @@
 ---
-layout: doc-page
 title: "Given Instances"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/givens.html
+type: section
+num: 15
+previous-page: /scala3/reference/contextual
+next-page: /scala3/reference/contextual/using-clauses
 ---
 
 Given instances (or, simply, "givens") define "canonical" values of certain types
-that serve for synthesizing arguments to [context parameters](./using-clauses.md). Example:
+that serve for synthesizing arguments to [context parameters](./using-clauses.html). Example:
 
 ```scala
 trait Ord[T]:
@@ -34,7 +36,7 @@ a given for the type `Ord[Int]` whereas `listOrd[T]` defines givens
 for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]`
 themselves. The `using` clause in `listOrd` defines a condition: There must be a
 given of type `Ord[T]` for a given of type `Ord[List[T]]` to exist.
-Such conditions are expanded by the compiler to [context parameters](./using-clauses.md).
+Such conditions are expanded by the compiler to [context parameters](./using-clauses.html).
 
 ## Anonymous Givens
 
@@ -151,7 +153,7 @@ is created for each reference.
 
 Here is the syntax for given instances:
 
-```ebnf
+```
 TmplDef             ::=  ...
                      |   ‘given’ GivenDef
 GivenDef            ::=  [GivenSig] StructuralInstance
diff --git a/docs/docs/reference/contextual/multiversal-equality.md b/docs-for-scalalang/docs/reference/contextual/multiversal-equality.md
similarity index 98%
rename from docs/docs/reference/contextual/multiversal-equality.md
rename to docs-for-scalalang/docs/reference/contextual/multiversal-equality.md
index 1af1786374bc..19b44c654494 100644
--- a/docs/docs/reference/contextual/multiversal-equality.md
+++ b/docs-for-scalalang/docs/reference/contextual/multiversal-equality.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Multiversal Equality"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/multiversal-equality.html
+type: section
+num: 22
+previous-page: /scala3/reference/contextual/derivation
+next-page: /scala3/reference/contextual/context-functions
 ---
 
 Previously, Scala had universal equality: Two values of any types
@@ -104,7 +106,7 @@ Instead of defining `CanEqual` instances directly, it is often more convenient t
 class Box[T](x: T) derives CanEqual
 ```
 
-By the usual rules of [type class derivation](./derivation.md),
+By the usual rules of [type class derivation](./derivation.html),
 this generates the following `CanEqual` instance in the companion object of `Box`:
 
 ```scala
diff --git a/docs/docs/reference/contextual/relationship-implicits.md b/docs-for-scalalang/docs/reference/contextual/relationship-implicits.md
similarity index 98%
rename from docs/docs/reference/contextual/relationship-implicits.md
rename to docs-for-scalalang/docs/reference/contextual/relationship-implicits.md
index 4a23e781bd70..9be698affdd8 100644
--- a/docs/docs/reference/contextual/relationship-implicits.md
+++ b/docs-for-scalalang/docs/reference/contextual/relationship-implicits.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Relationship with Scala 2 Implicits"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/relationship-implicits.html
+type: section
+num: 26
+previous-page: /scala3/reference/contextual/by-name-context-parameters
+next-page: /scala3/reference/metaprogramming
 ---
 
 Many, but not all, of the new contextual abstraction features in Scala 3 can be mapped to Scala 2's implicits. This page gives a rundown on the relationships between new and old features.
diff --git a/docs/docs/reference/contextual/right-associative-extension-methods.md b/docs-for-scalalang/docs/reference/contextual/right-associative-extension-methods.md
similarity index 95%
rename from docs/docs/reference/contextual/right-associative-extension-methods.md
rename to docs-for-scalalang/docs/reference/contextual/right-associative-extension-methods.md
index 7c2cf6b02675..b77e6dccdd78 100644
--- a/docs/docs/reference/contextual/right-associative-extension-methods.md
+++ b/docs-for-scalalang/docs/reference/contextual/right-associative-extension-methods.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Right-Associative Extension Methods: Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/right-associative-extension-methods.html
 ---
 
 The most general form of leading parameters of an extension method is as follows:
diff --git a/docs/docs/reference/contextual/type-classes.md b/docs-for-scalalang/docs/reference/contextual/type-classes.md
similarity index 97%
rename from docs/docs/reference/contextual/type-classes.md
rename to docs-for-scalalang/docs/reference/contextual/type-classes.md
index c4648b3baf28..4c80e7b53b14 100644
--- a/docs/docs/reference/contextual/type-classes.md
+++ b/docs-for-scalalang/docs/reference/contextual/type-classes.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Implementing Type classes"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/type-classes.html
+type: section
+num: 20
+previous-page: /scala3/reference/contextual/extension-methods
+next-page: /scala3/reference/contextual/derivation
 ---
 
 A _type class_ is an abstract, parameterized type that lets you add new behavior to any closed data type without using sub-typing. This can be useful in multiple use-cases, for example:
@@ -98,7 +100,7 @@ assertTransformation(List("a1", "b1"), List("a", "b"), elt => s"${elt}1")
 ```
 
 That's a first step, but in practice we probably would like the `map` function to be a method directly accessible on the type `F`. So that we can call `map` directly on instances of `F`, and get rid of the `summon[Functor[F]]` part.
-As in the previous example of Monoids, [`extension` methods](extension-methods.md) help achieving that. Let's re-define the `Functor` type class with extension methods.
+As in the previous example of Monoids, [`extension` methods](extension-methods.html) help achieving that. Let's re-define the `Functor` type class with extension methods.
 
 ```scala
 trait Functor[F[_]]:
@@ -235,7 +237,7 @@ given configDependentMonad: Monad[ConfigDependent] with
 end configDependentMonad
 ```
 
-The type `ConfigDependent` can be written using [type lambdas](../new-types/type-lambdas.md):
+The type `ConfigDependent` can be written using [type lambdas](../new-types/type-lambdas.html):
 
 ```scala
 type ConfigDependent = [Result] =>> Config => Result
diff --git a/docs/docs/reference/contextual/using-clauses.md b/docs-for-scalalang/docs/reference/contextual/using-clauses.md
similarity index 92%
rename from docs/docs/reference/contextual/using-clauses.md
rename to docs-for-scalalang/docs/reference/contextual/using-clauses.md
index e8a077ccdc0a..4f98c760ffef 100644
--- a/docs/docs/reference/contextual/using-clauses.md
+++ b/docs-for-scalalang/docs/reference/contextual/using-clauses.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Using Clauses"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual/using-clauses.html
+type: section
+num: 16
+previous-page: /scala3/reference/contextual/givens
+next-page: /scala3/reference/contextual/context-bounds
 ---
 
 Functional programming tends to express most dependencies as simple function parameterization.
@@ -9,7 +11,7 @@ This is clean and powerful, but it sometimes leads to functions that take many p
 functions. Context parameters can help here since they enable the compiler to synthesize
 repetitive arguments instead of the programmer having to write them explicitly.
 
-For example, with the [given instances](./givens.md) defined previously,
+For example, with the [given instances](./givens.html) defined previously,
 a `max` function that works for any arguments for which an ordering exists can be defined as follows:
 
 ```scala
@@ -64,7 +66,7 @@ class GivenIntBox2(using givenInt: Int):
   //def n = summon[Int]     // ambiguous
 ```
 
-The `given` member is importable as explained in the section on [importing `given`s](./given-imports.md):
+The `given` member is importable as explained in the section on [importing `given`s](./given-imports.html):
 
 ```scala
 val b = GivenIntBox(using 23)
@@ -142,7 +144,7 @@ def summon[T](using x: T): x.type = x
 
 ## Syntax
 
-Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](../syntax.md). `using` is a soft keyword, recognized only at the start of a parameter or argument list. It can be used as a normal identifier everywhere else.
+Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](../syntax.html). `using` is a soft keyword, recognized only at the start of a parameter or argument list. It can be used as a normal identifier everywhere else.
 
 ```
 ClsParamClause      ::=  ... | UsingClsParamClause
diff --git a/docs-for-scalalang/docs/reference/dropped-features.md b/docs-for-scalalang/docs/reference/dropped-features.md
new file mode 100644
index 000000000000..b2fb1fbe9fe2
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/dropped-features.md
@@ -0,0 +1,9 @@
+---
+title: "Dropped Features"
+type: chapter
+num: 70
+previous-page: /scala3/reference/changed-features/main-functions
+next-page: /scala3/reference/dropped-features/delayed-init
+---
+
+The following pages document the features of Scala 2 that have been dropped in Scala 3.
diff --git a/docs/docs/reference/dropped-features/auto-apply.md b/docs-for-scalalang/docs/reference/dropped-features/auto-apply.md
similarity index 95%
rename from docs/docs/reference/dropped-features/auto-apply.md
rename to docs-for-scalalang/docs/reference/dropped-features/auto-apply.md
index c5424ffff22d..8670850f7903 100644
--- a/docs/docs/reference/dropped-features/auto-apply.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/auto-apply.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Auto-Application"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/auto-apply.html
+type: section
+num: 83
+previous-page: /scala3/reference/dropped-features/symlits
+next-page: /scala3/reference/dropped-features/weak-conformance
 ---
 
 Previously an empty argument list `()` was implicitly inserted when
diff --git a/docs/docs/reference/dropped-features/class-shadowing-spec.md b/docs-for-scalalang/docs/reference/dropped-features/class-shadowing-spec.md
similarity index 89%
rename from docs/docs/reference/dropped-features/class-shadowing-spec.md
rename to docs-for-scalalang/docs/reference/dropped-features/class-shadowing-spec.md
index 98acff828cd3..d1d5d4b34bb4 100644
--- a/docs/docs/reference/dropped-features/class-shadowing-spec.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/class-shadowing-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Dropped: Class Shadowing - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/class-shadowing-spec.html
 ---
 
 Spec diff: in section [5.1.4 Overriding](https://www.scala-lang.org/files/archive/spec/2.13/05-classes-and-objects.html#Overriding), add *M' must not be a class*.
diff --git a/docs/docs/reference/dropped-features/class-shadowing.md b/docs-for-scalalang/docs/reference/dropped-features/class-shadowing.md
similarity index 78%
rename from docs/docs/reference/dropped-features/class-shadowing.md
rename to docs-for-scalalang/docs/reference/dropped-features/class-shadowing.md
index 839b40253169..b3a4ab2dc1ad 100644
--- a/docs/docs/reference/dropped-features/class-shadowing.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/class-shadowing.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Class Shadowing"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/class-shadowing.html
+type: section
+num: 79
+previous-page: /scala3/reference/dropped-features/early-initializers
+next-page: /scala3/reference/dropped-features/limit22
 ---
 
 Scala 2 so far allowed patterns like this:
@@ -30,4 +32,4 @@ other, but classes in Scala 2 cannot be overridden. To keep things clean
 (and its internal operations consistent) the Scala 3 compiler forces you
 to rename the inner classes so that their names are different.
 
-[More details](./class-shadowing-spec.md)
+[More details](./class-shadowing-spec.html)
diff --git a/docs/docs/reference/dropped-features/delayed-init.md b/docs-for-scalalang/docs/reference/dropped-features/delayed-init.md
similarity index 80%
rename from docs/docs/reference/dropped-features/delayed-init.md
rename to docs-for-scalalang/docs/reference/dropped-features/delayed-init.md
index 875ccec5132e..5673db5dfb8e 100644
--- a/docs/docs/reference/dropped-features/delayed-init.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/delayed-init.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: DelayedInit"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/delayed-init.html
+type: section
+num: 71
+previous-page: /scala3/reference/dropped-features
+next-page: /scala3/reference/dropped-features/macros
 ---
 
 The special handling of the `DelayedInit` trait is no longer supported.
@@ -27,4 +29,4 @@ object Hello:
 ```
 
 On the other hand, Scala 3 offers a convenient alternative to such "program" objects
-with [`@main` methods](../changed-features/main-functions.md).
+with [`@main` methods](../changed-features/main-functions.html).
diff --git a/docs/docs/reference/dropped-features/do-while.md b/docs-for-scalalang/docs/reference/dropped-features/do-while.md
similarity index 75%
rename from docs/docs/reference/dropped-features/do-while.md
rename to docs-for-scalalang/docs/reference/dropped-features/do-while.md
index 5f5ca5feeea2..3fd59430ac3b 100644
--- a/docs/docs/reference/dropped-features/do-while.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/do-while.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Do-While"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/do-while.html
+type: section
+num: 75
+previous-page: /scala3/reference/dropped-features/type-projection
+next-page: /scala3/reference/dropped-features/procedure-syntax
 ---
 
 The syntax construct
@@ -38,4 +40,4 @@ do print(".")
 ### Why Drop The Construct?
 
  - `do-while` is used relatively rarely and it can be expressed faithfully using just `while`. So there seems to be little point in having it as a separate syntax construct.
- - Under the [new syntax rules](../other-new-features/control-syntax.md) `do` is used as a statement continuation, which would clash with its meaning as a statement introduction.
+ - Under the [new syntax rules](../other-new-features/control-syntax.html) `do` is used as a statement continuation, which would clash with its meaning as a statement introduction.
diff --git a/docs/docs/reference/dropped-features/early-initializers.md b/docs-for-scalalang/docs/reference/dropped-features/early-initializers.md
similarity index 57%
rename from docs/docs/reference/dropped-features/early-initializers.md
rename to docs-for-scalalang/docs/reference/dropped-features/early-initializers.md
index cb2ffea94376..18d97640b12f 100644
--- a/docs/docs/reference/dropped-features/early-initializers.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/early-initializers.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Early Initializers"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/early-initializers.html
+type: section
+num: 78
+previous-page: /scala3/reference/dropped-features/package-objects
+next-page: /scala3/reference/dropped-features/class-shadowing
 ---
 
 Early initializers of the form
@@ -11,6 +13,6 @@ class C extends { ... } with SuperClass ...
 ```
 
 have been dropped. They were rarely used, and mostly to compensate for the lack of
-[trait parameters](../other-new-features/trait-parameters.md), which are now directly supported in Scala 3.
+[trait parameters](../other-new-features/trait-parameters.html), which are now directly supported in Scala 3.
 
 For more information, see [SLS §5.1.6](https://www.scala-lang.org/files/archive/spec/2.13/05-classes-and-objects.html#early-definitions).
diff --git a/docs/docs/reference/dropped-features/existential-types.md b/docs-for-scalalang/docs/reference/dropped-features/existential-types.md
similarity index 90%
rename from docs/docs/reference/dropped-features/existential-types.md
rename to docs-for-scalalang/docs/reference/dropped-features/existential-types.md
index 4d7d9e2f8c10..df624cbd0721 100644
--- a/docs/docs/reference/dropped-features/existential-types.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/existential-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Existential Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/existential-types.html
+type: section
+num: 73
+previous-page: /scala3/reference/dropped-features/macros
+next-page: /scala3/reference/dropped-features/type-projection
 ---
 
 Existential types using `forSome` (as in
diff --git a/docs/docs/reference/dropped-features/limit22.md b/docs-for-scalalang/docs/reference/dropped-features/limit22.md
similarity index 57%
rename from docs/docs/reference/dropped-features/limit22.md
rename to docs-for-scalalang/docs/reference/dropped-features/limit22.md
index ffbf6eb196dc..2e21efec58f6 100644
--- a/docs/docs/reference/dropped-features/limit22.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/limit22.md
@@ -1,17 +1,19 @@
 ---
-layout: doc-page
 title: "Dropped: Limit 22"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/limit22.html
+type: section
+num: 80
+previous-page: /scala3/reference/dropped-features/class-shadowing
+next-page: /scala3/reference/dropped-features/xml
 ---
 
 The limits of 22 for the maximal number of parameters of function types and the
 maximal number of fields in tuple types have been dropped.
 
 * Functions can now have an arbitrary number of parameters. Functions beyond
-  [`scala.Function22`](https://www.scala-lang.org/api/current/scala/Function22.html) are erased to a new trait [`scala.runtime.FunctionXXL`](https://dotty.epfl.ch/api/scala/runtime/FunctionXXL.html).
+  [`scala.Function22`](https://www.scala-lang.org/api/current/scala/Function22.html) are erased to a new trait [`scala.runtime.FunctionXXL`](https://scala-lang.org/api/3.x/scala/runtime/FunctionXXL.html).
 
 * Tuples can also have an arbitrary number of fields. Tuples beyond [`scala.Tuple22`](https://www.scala-lang.org/api/current/scala/Tuple22.html)
-  are erased to a new class [`scala.runtime.TupleXXL`](https://dotty.epfl.ch/api/scala/runtime/TupleXXL.html) (which extends the trait [`scala.Product`](https://dotty.epfl.ch/api/scala/Product.html)). Furthermore, they support generic
+  are erased to a new class [`scala.runtime.TupleXXL`](https://scala-lang.org/api/3.x/scala/runtime/TupleXXL.html) (which extends the trait [`scala.Product`](https://scala-lang.org/api/3.x/scala/Product.html)). Furthermore, they support generic
   operation such as concatenation and indexing.
 
 Both of these are implemented using arrays.
diff --git a/docs/docs/reference/dropped-features/macros.md b/docs-for-scalalang/docs/reference/dropped-features/macros.md
similarity index 67%
rename from docs/docs/reference/dropped-features/macros.md
rename to docs-for-scalalang/docs/reference/dropped-features/macros.md
index e71bf120fe13..f7a23edb0057 100644
--- a/docs/docs/reference/dropped-features/macros.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/macros.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Scala 2 Macros"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/macros.html
+type: section
+num: 72
+previous-page: /scala3/reference/dropped-features/delayed-init
+next-page: /scala3/reference/dropped-features/existential-types
 ---
 
 The previous, experimental macro system has been dropped.
@@ -11,6 +13,6 @@ Instead, there is a cleaner, more restricted system based on two complementary c
 In this setting, a definition marked as inlined containing a `${ ... }` is a macro, the code inside the `${ ... }` is executed at compile-time and produces code in the form of `'{ ... }`.
 Additionally, the contents of code can be inspected and created with a more complex reflection API as an extension of `'{ ... }`/`${ ... }` framework.
 
-* `inline` has been [implemented](../metaprogramming/inline.md) in Scala 3.
-* Quotes `'{ ... }` and splices `${ ... }` has been [implemented](../metaprogramming/macros.md) in Scala 3.
-* [TASTy reflect](../metaprogramming/reflection.md) provides more complex tree based APIs to inspect or create quoted code.
+* `inline` has been [implemented](../metaprogramming/inline.html) in Scala 3.
+* Quotes `'{ ... }` and splices `${ ... }` has been [implemented](../metaprogramming/macros.html) in Scala 3.
+* [TASTy reflect](../metaprogramming/reflection.html) provides more complex tree based APIs to inspect or create quoted code.
diff --git a/docs/docs/reference/dropped-features/nonlocal-returns.md b/docs-for-scalalang/docs/reference/dropped-features/nonlocal-returns.md
similarity index 80%
rename from docs/docs/reference/dropped-features/nonlocal-returns.md
rename to docs-for-scalalang/docs/reference/dropped-features/nonlocal-returns.md
index 1b23485e6a00..89b244f122b4 100644
--- a/docs/docs/reference/dropped-features/nonlocal-returns.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/nonlocal-returns.md
@@ -1,14 +1,14 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Deprecated: Nonlocal Returns"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/nonlocal-returns.html
 ---
 
 Returning from nested anonymous functions has been deprecated.
 
 Nonlocal returns are implemented by throwing and catching `scala.runtime.NonLocalReturnException`-s. This is rarely what is intended by the programmer. It can be problematic because of the hidden performance cost of throwing and catching exceptions. Furthermore, it is a leaky implementation: a catch-all exception handler can intercept a `NonLocalReturnException`.
 
-A drop-in library replacement is provided in [`scala.util.control.NonLocalReturns`](http://dotty.epfl.ch/api/scala/util/control/NonLocalReturns$.html). Example:
+A drop-in library replacement is provided in [`scala.util.control.NonLocalReturns`](https://scala-lang.org/api/3.x/scala/util/control/NonLocalReturns$.html). Example:
 
 ```scala
 import scala.util.control.NonLocalReturns.*
diff --git a/docs/docs/reference/dropped-features/package-objects.md b/docs-for-scalalang/docs/reference/dropped-features/package-objects.md
similarity index 93%
rename from docs/docs/reference/dropped-features/package-objects.md
rename to docs-for-scalalang/docs/reference/dropped-features/package-objects.md
index 69a47b340cf0..35e21d56a23c 100644
--- a/docs/docs/reference/dropped-features/package-objects.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/package-objects.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Package Objects"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/package-objects.html
+type: section
+num: 77
+previous-page: /scala3/reference/dropped-features/procedure-syntax
+next-page: /scala3/reference/dropped-features/early-initializers
 ---
 
 Package objects
diff --git a/docs/docs/reference/dropped-features/procedure-syntax.md b/docs-for-scalalang/docs/reference/dropped-features/procedure-syntax.md
similarity index 77%
rename from docs/docs/reference/dropped-features/procedure-syntax.md
rename to docs-for-scalalang/docs/reference/dropped-features/procedure-syntax.md
index cc82636d370d..f3bf8cc9d47f 100644
--- a/docs/docs/reference/dropped-features/procedure-syntax.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/procedure-syntax.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Procedure Syntax"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/procedure-syntax.html
+type: section
+num: 76
+previous-page: /scala3/reference/dropped-features/do-while
+next-page: /scala3/reference/dropped-features/package-objects
 ---
 
 Procedure syntax
diff --git a/docs/docs/reference/dropped-features/symlits.md b/docs-for-scalalang/docs/reference/dropped-features/symlits.md
similarity index 71%
rename from docs/docs/reference/dropped-features/symlits.md
rename to docs-for-scalalang/docs/reference/dropped-features/symlits.md
index 33c3e6ee0c39..3cb7243af964 100644
--- a/docs/docs/reference/dropped-features/symlits.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/symlits.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Symbol Literals"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/symlits.html
+type: section
+num: 82
+previous-page: /scala3/reference/dropped-features/xml
+next-page: /scala3/reference/dropped-features/auto-apply
 ---
 
 Symbol literals are no longer supported.
diff --git a/docs/docs/reference/dropped-features/this-qualifier.md b/docs-for-scalalang/docs/reference/dropped-features/this-qualifier.md
similarity index 81%
rename from docs/docs/reference/dropped-features/this-qualifier.md
rename to docs-for-scalalang/docs/reference/dropped-features/this-qualifier.md
index 0017573be129..c25f896415f5 100644
--- a/docs/docs/reference/dropped-features/this-qualifier.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/this-qualifier.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: private[this] and protected[this]"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/this-qualifier.html
+type: section
+num: 85
+previous-page: /scala3/reference/dropped-features/weak-conformance
+next-page: /scala3/reference/dropped-features/wildcard-init
 ---
 
 The `private[this]` and `protected[this]` access modifiers are deprecated and will be phased out.
diff --git a/docs/docs/reference/dropped-features/type-projection.md b/docs-for-scalalang/docs/reference/dropped-features/type-projection.md
similarity index 82%
rename from docs/docs/reference/dropped-features/type-projection.md
rename to docs-for-scalalang/docs/reference/dropped-features/type-projection.md
index f45eff5c423f..fb87ef79be23 100644
--- a/docs/docs/reference/dropped-features/type-projection.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/type-projection.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: General Type Projection"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/type-projection.html
+type: section
+num: 74
+previous-page: /scala3/reference/dropped-features/existential-types
+next-page: /scala3/reference/dropped-features/do-while
 ---
 
 Scala so far allowed general type projection `T#A` where `T` is an arbitrary type
diff --git a/docs/docs/reference/dropped-features/weak-conformance-spec.md b/docs-for-scalalang/docs/reference/dropped-features/weak-conformance-spec.md
similarity index 94%
rename from docs/docs/reference/dropped-features/weak-conformance-spec.md
rename to docs-for-scalalang/docs/reference/dropped-features/weak-conformance-spec.md
index 1432782a8e38..147298f5573a 100644
--- a/docs/docs/reference/dropped-features/weak-conformance-spec.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/weak-conformance-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Dropped: Weak Conformance - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/weak-conformance-spec.html
 ---
 
 To simplify the underlying type theory, Scala 3 drops the notion of
diff --git a/docs/docs/reference/dropped-features/weak-conformance.md b/docs-for-scalalang/docs/reference/dropped-features/weak-conformance.md
similarity index 89%
rename from docs/docs/reference/dropped-features/weak-conformance.md
rename to docs-for-scalalang/docs/reference/dropped-features/weak-conformance.md
index c2dabe39e7c7..deca70b60714 100644
--- a/docs/docs/reference/dropped-features/weak-conformance.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/weak-conformance.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Weak Conformance"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/weak-conformance.html
+type: section
+num: 84
+previous-page: /scala3/reference/dropped-features/auto-apply
+next-page: /scala3/reference/dropped-features/this-qualifier
 ---
 
 In some situations, Scala used a _weak conformance_ relation when
@@ -44,4 +46,4 @@ Therefore, Scala 3 drops the general notion of weak conformance, and
 instead keeps one rule: `Int` literals are adapted to other numeric
 types if necessary.
 
-[More details](weak-conformance-spec.md)
+[More details](weak-conformance-spec.html)
diff --git a/docs/docs/reference/dropped-features/wildcard-init.md b/docs-for-scalalang/docs/reference/dropped-features/wildcard-init.md
similarity index 79%
rename from docs/docs/reference/dropped-features/wildcard-init.md
rename to docs-for-scalalang/docs/reference/dropped-features/wildcard-init.md
index c4b89674b11d..be633fb1ca21 100644
--- a/docs/docs/reference/dropped-features/wildcard-init.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/wildcard-init.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: Wildcard Initializer"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/wildcard-init.html
+type: section
+num: 86
+previous-page: /scala3/reference/dropped-features/this-qualifier
+next-page: /scala3/reference/syntax
 ---
 
 The syntax
diff --git a/docs/docs/reference/dropped-features/xml.md b/docs-for-scalalang/docs/reference/dropped-features/xml.md
similarity index 89%
rename from docs/docs/reference/dropped-features/xml.md
rename to docs-for-scalalang/docs/reference/dropped-features/xml.md
index 9de06ca30f2e..cab3d0663a55 100644
--- a/docs/docs/reference/dropped-features/xml.md
+++ b/docs-for-scalalang/docs/reference/dropped-features/xml.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dropped: XML Literals"
-movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/xml.html
+type: section
+num: 81
+previous-page: /scala3/reference/dropped-features/limit22
+next-page: /scala3/reference/dropped-features/symlits
 ---
 
 XML Literals are still supported, but will be dropped in the near future, to
diff --git a/docs-for-scalalang/docs/reference/enums.md b/docs-for-scalalang/docs/reference/enums.md
new file mode 100644
index 000000000000..e8c63c237704
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/enums.md
@@ -0,0 +1,9 @@
+---
+title: "Enums"
+type: chapter
+num: 9
+previous-page: /scala3/reference/new-types/polymorphic-function-types
+next-page: /scala3/reference/enums/enums
+---
+
+This chapter documents enums in Scala 3.
diff --git a/docs/docs/reference/enums/adts.md b/docs-for-scalalang/docs/reference/enums/adts.md
similarity index 95%
rename from docs/docs/reference/enums/adts.md
rename to docs-for-scalalang/docs/reference/enums/adts.md
index 927b5fcf2ca4..10558707b543 100644
--- a/docs/docs/reference/enums/adts.md
+++ b/docs-for-scalalang/docs/reference/enums/adts.md
@@ -1,10 +1,12 @@
 ---
-layout: doc-page
 title: "Algebraic Data Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/enums/adts.html
+type: section
+num: 11
+previous-page: /scala3/reference/enums/enums
+next-page: /scala3/reference/enums/desugarEnums
 ---
 
-The [`enum` concept](./enums.md) is general enough to also support algebraic data
+The [`enum` concept](./enums.html) is general enough to also support algebraic data
 types (ADTs) and their generalized version (GADTs). Here is an example
 how an `Option` type can be represented as an ADT:
 
@@ -150,11 +152,11 @@ enum View[-T, +U] extends (T => U):
 ### Syntax of Enums
 
 Changes to the syntax fall in two categories: enum definitions and cases inside enums.
-The changes are specified below as deltas with respect to the Scala syntax given [here](../syntax.md)
+The changes are specified below as deltas with respect to the Scala syntax given [here](../syntax.html)
 
  1. Enum definitions are defined as follows:
 
-    ```ebnf
+    ```
     TmplDef   ::=  `enum' EnumDef
     EnumDef   ::=  id ClassConstr [`extends' [ConstrApps]] EnumBody
     EnumBody  ::=  [nl] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
@@ -164,7 +166,7 @@ The changes are specified below as deltas with respect to the Scala syntax given
 
  2. Cases of enums are defined as follows:
 
-    ```ebnf
+    ```
     EnumCase  ::=  `case' (id ClassConstr [`extends' ConstrApps]] | ids)
     ```
 
diff --git a/docs/docs/reference/enums/desugarEnums.md b/docs-for-scalalang/docs/reference/enums/desugarEnums.md
similarity index 98%
rename from docs/docs/reference/enums/desugarEnums.md
rename to docs-for-scalalang/docs/reference/enums/desugarEnums.md
index 95df1a7513ce..efcc41d5b2f6 100644
--- a/docs/docs/reference/enums/desugarEnums.md
+++ b/docs-for-scalalang/docs/reference/enums/desugarEnums.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Translation of Enums and ADTs"
-movedTo: https://docs.scala-lang.org/scala3/reference/enums/desugarEnums.html
+type: section
+num: 12
+previous-page: /scala3/reference/enums/adts
+next-page: /scala3/reference/contextual
 ---
 
 The compiler expands enums and their cases to code that only uses
@@ -155,7 +157,7 @@ map into `case class`es or `val`s.
    case C(ps) extends P1, ..., Pn
    ```
    are treated specially. A call `C(ts)` of the apply method is ascribed the underlying type
-   `P1 & ... & Pn` (dropping any [transparent traits](../other-new-features/transparent-traits.md))
+   `P1 & ... & Pn` (dropping any [transparent traits](../other-new-features/transparent-traits.html))
    as long as that type is still compatible with the expected type at the point of application.
    A call `t.copy(ts)` of `C`'s `copy` method is treated in the same way.
 
diff --git a/docs/docs/reference/enums/enums.md b/docs-for-scalalang/docs/reference/enums/enums.md
similarity index 96%
rename from docs/docs/reference/enums/enums.md
rename to docs-for-scalalang/docs/reference/enums/enums.md
index e68f54fa0dd1..96d11e874212 100644
--- a/docs/docs/reference/enums/enums.md
+++ b/docs-for-scalalang/docs/reference/enums/enums.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Enumerations"
-movedTo: https://docs.scala-lang.org/scala3/reference/enums/enums.html
+type: section
+num: 10
+previous-page: /scala3/reference/enums
+next-page: /scala3/reference/enums/adts
 ---
 
 An enumeration is used to define a type consisting of a set of named values.
@@ -131,7 +133,7 @@ object Planet {
 }
 ```
 
-We could imagine that a library may use [type class derivation](../contextual/derivation.md) to automatically provide an instance for `Deprecations`.
+We could imagine that a library may use [type class derivation](../contextual/derivation.html) to automatically provide an instance for `Deprecations`.
 
 ### Compatibility with Java Enums
 
diff --git a/docs/docs/reference/experimental/canthrow.md b/docs-for-scalalang/docs/reference/experimental/canthrow.md
similarity index 97%
rename from docs/docs/reference/experimental/canthrow.md
rename to docs-for-scalalang/docs/reference/experimental/canthrow.md
index 989d766a4e1e..88fa77d785a4 100644
--- a/docs/docs/reference/experimental/canthrow.md
+++ b/docs-for-scalalang/docs/reference/experimental/canthrow.md
@@ -1,6 +1,7 @@
 ---
-layout: doc-page
-title: CanThrow Capabilities
+layout: singlepage-overview
+scala3: true
+title: CanThrow Abilities
 author: Martin Odersky
 ---
 
@@ -60,7 +61,7 @@ In the _effects as capabilities_ model, an effect is expressed as an (implicit)
 ```scala
 erased class CanThrow[-E <: Exception]
 ```
-This shows another experimental Scala feature: [erased definitions](./erased-defs). Roughly speaking, values of an erased class do not generate runtime code; they are erased before code generation. This means that all `CanThrow` capabilities are compile-time only artifacts; they do not have a runtime footprint.
+This shows another experimental Scala feature: [erased definitions]({% link _scala3-reference/experimental/erased-defs.md %}). Roughly speaking, values of an erased class do not generate runtime code; they are erased before code generation. This means that all `CanThrow` capabilities are compile-time only artifacts; they do not have a runtime footprint.
 
 Now, if the compiler sees a `throw Exc()` construct where `Exc` is a checked exception, it will check that there is a capability of type `CanThrow[Exc]` that can be summoned as a given. It's a compile-time error if that's not the case.
 
diff --git a/docs/docs/reference/experimental/erased-defs-spec.md b/docs-for-scalalang/docs/reference/experimental/erased-defs-spec.md
similarity index 97%
rename from docs/docs/reference/experimental/erased-defs-spec.md
rename to docs-for-scalalang/docs/reference/experimental/erased-defs-spec.md
index ed8490f7e30e..7905e4776fed 100644
--- a/docs/docs/reference/experimental/erased-defs-spec.md
+++ b/docs-for-scalalang/docs/reference/experimental/erased-defs-spec.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Erased Definitions: More Details"
 ---
 
diff --git a/docs/docs/reference/experimental/erased-defs.md b/docs-for-scalalang/docs/reference/experimental/erased-defs.md
similarity index 97%
rename from docs/docs/reference/experimental/erased-defs.md
rename to docs-for-scalalang/docs/reference/experimental/erased-defs.md
index fa39f6df59dc..47d25583b34c 100644
--- a/docs/docs/reference/experimental/erased-defs.md
+++ b/docs-for-scalalang/docs/reference/experimental/erased-defs.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Erased Definitions"
 ---
 
@@ -160,7 +161,7 @@ object Machine:
   //                    State must be Off
 ```
 
-Note that in [Inline](../metaprogramming/inline.md) we discussed `erasedValue` and inline
+Note that in [Inline](../metaprogramming/inline.html) we discussed `erasedValue` and inline
 matches. `erasedValue` is implemented with `erased`, so the state machine above
 can be encoded as follows:
 
@@ -227,4 +228,4 @@ val err: Any = CanRead() // error: illegal reference to erased class CanRead
 ```
 Here, the type of `err` is `Any`, so `err` is not considered erased. Yet its initializing value is a reference to the erased class `CanRead`.
 
-[More Details](./erased-defs-spec.md)
+[More Details](./erased-defs-spec.html)
diff --git a/docs/docs/reference/experimental/named-typeargs-spec.md b/docs-for-scalalang/docs/reference/experimental/named-typeargs-spec.md
similarity index 96%
rename from docs/docs/reference/experimental/named-typeargs-spec.md
rename to docs-for-scalalang/docs/reference/experimental/named-typeargs-spec.md
index 404f96852aca..ddd808559825 100644
--- a/docs/docs/reference/experimental/named-typeargs-spec.md
+++ b/docs-for-scalalang/docs/reference/experimental/named-typeargs-spec.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Named Type Arguments - More Details"
 ---
 
diff --git a/docs/docs/reference/experimental/named-typeargs.md b/docs-for-scalalang/docs/reference/experimental/named-typeargs.md
similarity index 100%
rename from docs/docs/reference/experimental/named-typeargs.md
rename to docs-for-scalalang/docs/reference/experimental/named-typeargs.md
diff --git a/docs/docs/reference/experimental/numeric-literals.md b/docs-for-scalalang/docs/reference/experimental/numeric-literals.md
similarity index 100%
rename from docs/docs/reference/experimental/numeric-literals.md
rename to docs-for-scalalang/docs/reference/experimental/numeric-literals.md
diff --git a/docs/docs/reference/experimental/overview.md b/docs-for-scalalang/docs/reference/experimental/overview.md
similarity index 100%
rename from docs/docs/reference/experimental/overview.md
rename to docs-for-scalalang/docs/reference/experimental/overview.md
diff --git a/docs/docs/reference/features-classification.md b/docs-for-scalalang/docs/reference/features-classification.md
similarity index 74%
rename from docs/docs/reference/features-classification.md
rename to docs-for-scalalang/docs/reference/features-classification.md
index 6196394b572a..528b2ffccd70 100644
--- a/docs/docs/reference/features-classification.md
+++ b/docs-for-scalalang/docs/reference/features-classification.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "A Classification of Proposed Language Features"
 date: April 6, 2019
 author: Martin Odersky
@@ -16,11 +17,11 @@ The current document reflects the state of things as of April, 2019. It will be
 
 These new constructs directly model core features of [DOT](https://www.scala-lang.org/blog/2016/02/03/essence-of-scala.html), higher-kinded types, and the [SI calculus for implicit resolution](https://infoscience.epfl.ch/record/229878/files/simplicitly_1.pdf).
 
- - [Intersection types](new-types/intersection-types.md), replacing compound types,
- - [Union types](new-types/union-types.md),
- - [Type lambdas](new-types/type-lambdas.md),
+ - [Intersection types](new-types/intersection-types.html), replacing compound types,
+ - [Union types](new-types/union-types.html),
+ - [Type lambdas](new-types/type-lambdas.html),
  replacing encodings using structural types and type projection.
- - [Context functions](contextual/context-functions.md) offering abstraction over given parameters.
+ - [Context functions](contextual/context-functions.html) offering abstraction over given parameters.
 
 **Status: essential**
 
@@ -34,19 +35,19 @@ Since these are additions, there's generally no migration cost for old code. An
 
 These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.
 
- - [Trait parameters](other-new-features/trait-parameters.md) replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct.
- - [Given instances](contextual/givens.md)
+ - [Trait parameters](other-new-features/trait-parameters.html) replace [early initializers](dropped-features/early-initializers.html) with a more generally useful construct.
+ - [Given instances](contextual/givens.html)
    replace implicit objects and defs, focussing on intent over mechanism.
- - [Using clauses](contextual/using-clauses.md) replace implicit parameters, avoiding their ambiguities.
- - [Extension methods](contextual/extension-methods.md) replace implicit classes with a clearer and simpler mechanism.
- - [Opaque type aliases](other-new-features/opaques.md) replace most uses
+ - [Using clauses](contextual/using-clauses.html) replace implicit parameters, avoiding their ambiguities.
+ - [Extension methods](contextual/extension-methods.html) replace implicit classes with a clearer and simpler mechanism.
+ - [Opaque type aliases](other-new-features/opaques.html) replace most uses
    of value classes while guaranteeing absence of boxing.
- - [Top-level definitions](dropped-features/package-objects.md) replace package objects, dropping syntactic boilerplate.
- - [Export clauses](other-new-features/export.md)
+ - [Top-level definitions](dropped-features/package-objects.html) replace package objects, dropping syntactic boilerplate.
+ - [Export clauses](other-new-features/export.html)
  provide a simple and general way to express aggregation, which can replace the
  previous facade pattern of package objects inheriting from classes.
- - [Vararg splices](changed-features/vararg-splices.md) now use the form `*` instead of `@ _*`, mirroring vararg expressions,
- - [Creator applications](other-new-features/creator-applications.md) allow using simple function call syntax
+ - [Vararg splices](changed-features/vararg-splices.html) now use the form `*` instead of `@ _*`, mirroring vararg expressions,
+ - [Creator applications](other-new-features/creator-applications.html) allow using simple function call syntax
  instead of `new` expressions. `new` expressions stay around as a fallback for
  the cases where creator applications cannot be used.
 
@@ -69,10 +70,10 @@ For the next several versions, old features will remain available and deprecatio
 
 These constructs are restricted to make the language safer.
 
- - [Implicit Conversions](contextual/conversions.md): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
- - [Given Imports](contextual/given-imports.md): implicits now require a special form of import, to make the import clearly visible.
- - [Type Projection](dropped-features/type-projection.md): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
- - [Multiversal equality](contextual/multiversal-equality.md) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
+ - [Implicit Conversions](contextual/conversions.html): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
+ - [Given Imports](contextual/given-imports.html): implicits now require a special form of import, to make the import clearly visible.
+ - [Type Projection](dropped-features/type-projection.html): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
+ - [Multiversal equality](contextual/multiversal-equality.html) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
  - [infix](https://github.com/lampepfl/dotty/pull/5975)
  makes method application syntax uniform across code bases.
 
@@ -92,15 +93,15 @@ These are essential restrictions. If we decide to adopt them, we should do it fo
 
 These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation.
 
- - [DelayedInit](dropped-features/delayed-init.md),
- - [Existential types](dropped-features/existential-types.md),
- - [Procedure syntax](dropped-features/procedure-syntax.md),
- - [Class shadowing](dropped-features/class-shadowing.md),
- - [XML literals](dropped-features/xml.md),
- - [Symbol literals](dropped-features/symlits.md),
- - [Auto application](dropped-features/auto-apply.md),
- - [Weak conformance](dropped-features/weak-conformance.md),
- - [Compound types](new-types/intersection-types.md),
+ - [DelayedInit](dropped-features/delayed-init.html),
+ - [Existential types](dropped-features/existential-types.html),
+ - [Procedure syntax](dropped-features/procedure-syntax.html),
+ - [Class shadowing](dropped-features/class-shadowing.html),
+ - [XML literals](dropped-features/xml.html),
+ - [Symbol literals](dropped-features/symlits.html),
+ - [Auto application](dropped-features/auto-apply.html),
+ - [Weak conformance](dropped-features/weak-conformance.html),
+ - [Compound types](new-types/intersection-types.html),
  - [Auto tupling](https://github.com/lampepfl/dotty/pull/4311) (implemented, but not merged).
 
 The date when these constructs are dropped varies. The current status is:
@@ -127,10 +128,10 @@ and sometimes need to be manual (e.g. class shadowing, auto tupling). Sometimes
 
 These constructs have undergone changes to make them more regular and useful.
 
- - [Structural Types](changed-features/structural-types.md): They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
- - [Name-based pattern matching](changed-features/pattern-matching.md): The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
- - [Eta expansion](changed-features/eta-expansion.md) is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
- - [Implicit Resolution](changed-features/implicit-resolution.md): The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.
+ - [Structural Types](changed-features/structural-types.html): They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
+ - [Name-based pattern matching](changed-features/pattern-matching.html): The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
+ - [Eta expansion](changed-features/eta-expansion.html) is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
+ - [Implicit Resolution](changed-features/implicit-resolution.html): The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.
 
 Most aspects of old-style implicit resolution are still available under `-source 3.0-migration`. The other changes in this list are applied unconditionally.
 
@@ -146,11 +147,11 @@ Only a few programs should require changes, but some necessary changes might be
 
 These are additions to the language that make it more powerful or pleasant to use.
 
- - [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md).
- - [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring.
- - [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
+ - [Enums](enums/enums.html) provide concise syntax for enumerations and [algebraic data types](enums/adts.html).
+ - [Parameter untupling](other-new-features/parameter-untupling.html) avoids having to use `case` for tupled parameter destructuring.
+ - [Dependent function types](new-types/dependent-function-types.html) generalize dependent methods to dependent function values and types.
  - [Polymorphic function types](https://github.com/lampepfl/dotty/pull/4672) generalize polymorphic methods to dependent function values and types. _Current status_: There is a proposal, and a prototype implementation, but the implementation has not been finalized or merged yet.
- - [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
+ - [Kind polymorphism](other-new-features/kind-polymorphism.html) allows the definition of operators working equally on types and type constructors.
 
 **Status: mixed**
 
@@ -168,12 +169,12 @@ It's worth noting that macros were never included in the [Scala 2 language speci
 
 To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority.
 
-- [Match types](new-types/match-types.md) allow computation on types.
-- [Inline](metaprogramming/inline.md) provides
+- [Match types](new-types/match-types.html) allow computation on types.
+- [Inline](metaprogramming/inline.html) provides
 by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
-- [Quotes and splices](metaprogramming/macros.md) provide a principled way to express macros and staging with a unified set of abstractions.
-- [Type class derivation](contextual/derivation.md) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
-- [Implicit by-name parameters](contextual/by-name-context-parameters.md) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
+- [Quotes and splices](metaprogramming/macros.html) provide a principled way to express macros and staging with a unified set of abstractions.
+- [Type class derivation](contextual/derivation.html) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
+- [Implicit by-name parameters](contextual/by-name-context-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
 
 **Status: not yet settled**
 
diff --git a/docs-for-scalalang/docs/reference/language-versions.md b/docs-for-scalalang/docs/reference/language-versions.md
new file mode 100644
index 000000000000..ec16e8bed3cc
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/language-versions.md
@@ -0,0 +1,36 @@
+---
+title: "Language Versions"
+type: chapter
+description: This page lists the different flavours of language supported by the Scala 3 compiler.
+num: 100
+previous-page: overview
+---
+
+The default Scala language version currently supported by the Dotty compiler is `3.0`. There are also other language versions that can be specified instead:
+
+- `3.0-migration`: Same as `3.0` but with a Scala 2 compatibility mode that helps moving Scala 2.13 sources over to Scala 3. In particular, it
+
+    - flags some Scala 2 constructs that are disallowed in Scala 3 as migration warnings instead of hard errors,
+    - changes some rules to be more lenient and backwards compatible with Scala 2.13
+    - gives some additional warnings where the semantics has changed between Scala 2.13 and 3.0
+    - in conjunction with `-rewrite`, offer code rewrites from Scala 2.13 to 3.0.
+
+- `future`: A preview of changes introduced in the next versions after 3.0. In the doc pages here we refer to the language version with these changes as `3.1`, but it might be that some of these changes will be rolled out in later `3.x` versions.
+
+Some Scala-2 specific idioms will be dropped in this version. The feature set supported by this version will be refined over time  as we approach its release.
+
+- `future-migration`: Same as `future` but with additional helpers to migrate from `3.0`. Similarly to the helpers available under `3.0-migration`, these include migration warnings and optional rewrites.
+
+There are two ways to specify a language version.
+
+- With a `-source` command line setting, e.g. `-source 3.0-migration`.
+- With a `scala.language` import at the top of a source file, e.g:
+
+```scala
+package p
+import scala.language.`future-migration`
+
+class C { ... }
+```
+
+Language imports supersede command-line settings in the source files where they are specified. Only one language import specifying a source version is allowed in a source file, and it must come before any definitions in that file.
diff --git a/docs/docs/reference/metaprogramming/toc.md b/docs-for-scalalang/docs/reference/metaprogramming.md
similarity index 76%
rename from docs/docs/reference/metaprogramming/toc.md
rename to docs-for-scalalang/docs/reference/metaprogramming.md
index 12becbfa22e6..18664703a079 100644
--- a/docs/docs/reference/metaprogramming/toc.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming.md
@@ -1,13 +1,15 @@
 ---
-layout: doc-page
-title: "Overview"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming.html
+title: "Metaprogramming"
+type: chapter
+num: 27
+previous-page: /scala3/reference/contextual/relationship-implicits
+next-page: /scala3/reference/metaprogramming/inline
 ---
 
 The following pages introduce the redesign of metaprogramming in Scala. They
 introduce the following fundamental facilities:
 
-1. [`inline`](./inline.md) is a new modifier that guarantees that
+1. [`inline`](./metaprogramming/inline.html) is a new modifier that guarantees that
    a definition will be inlined at the point of use. The primary motivation
    behind inline is to reduce the overhead behind function calls and access to
    values. The expansion will be performed by the Scala compiler during the
@@ -18,10 +20,10 @@ introduce the following fundamental facilities:
    programming), macros (enabling compile-time, generative, metaprogramming) and
    runtime code generation (multi-stage programming).
 
-2. [Compile-time ops](./compiletime-ops.md) are helper definitions in the
+2. [Compile-time ops](./metaprogramming/compiletime-ops.html) are helper definitions in the
    standard library that provide support for compile-time operations over values and types.
 
-3. [Macros](./macros.md) are built on two well-known fundamental
+3. [Macros](./metaprogramming/macros.html) are built on two well-known fundamental
    operations: quotation and splicing.  Quotation converts program code to
    data, specifically, a (tree-like) representation of this code. It is
    expressed as `'{...}` for expressions and as `'[...]` for types. Splicing,
@@ -29,19 +31,19 @@ introduce the following fundamental facilities:
    to program code. Together with `inline`, these two abstractions allow
    to construct program code programmatically.
 
-4. [Runtime Staging](./staging.md) Where macros construct code at _compile-time_,
+4. [Runtime Staging](./metaprogramming/staging.html) Where macros construct code at _compile-time_,
    staging lets programs construct new code at _runtime_. That way,
    code generation can depend not only on static data but also on data available at runtime. This splits the evaluation of the program in two or more phases or ...
    stages. Consequently, this method of generative programming is called "Multi-Stage Programming". Staging is built on the same foundations as macros. It uses
    quotes and splices, but leaves out `inline`.
 
-5. [Reflection](./reflection.md) Quotations are a "black-box"
+5. [Reflection](./metaprogramming/reflection.html) Quotations are a "black-box"
    representation of code. They can be parameterized and composed using
    splices, but their structure cannot be analyzed from the outside. TASTy
    reflection gives a way to analyze code structure by partly revealing the representation type of a piece of code in a standard API. The representation
    type is a form of typed abstract syntax tree, which gives rise to the `TASTy`
    moniker.
 
-6. [TASTy Inspection](./tasty-inspect.md) Typed abstract syntax trees are serialized
+6. [TASTy Inspection](./metaprogramming/tasty-inspect.html) Typed abstract syntax trees are serialized
    in a custom compressed binary format stored in `.tasty` files. TASTy inspection allows
    to load these files and analyze their content's tree structure.
diff --git a/docs/docs/reference/metaprogramming/compiletime-ops.md b/docs-for-scalalang/docs/reference/metaprogramming/compiletime-ops.md
similarity index 94%
rename from docs/docs/reference/metaprogramming/compiletime-ops.md
rename to docs-for-scalalang/docs/reference/metaprogramming/compiletime-ops.md
index 3a31efb58d52..9bf0bc537930 100644
--- a/docs/docs/reference/metaprogramming/compiletime-ops.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/compiletime-ops.md
@@ -1,12 +1,14 @@
 ---
-layout: doc-page
 title: "Compile-time operations"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/compiletime-ops.html
+type: section
+num: 29
+previous-page: /scala3/reference/metaprogramming/inline
+next-page: /scala3/reference/metaprogramming/macros
 ---
 
 ## The `scala.compiletime` Package
 
-The [`scala.compiletime`](https://dotty.epfl.ch/api/scala/compiletime.html) package contains helper definitions that provide support for compile-time operations over values. They are described in the following.
+The [`scala.compiletime`](https://scala-lang.org/api/3.x/scala/compiletime.html) package contains helper definitions that provide support for compile-time operations over values. They are described in the following.
 
 ### `constValue` and `constValueOpt`
 
@@ -52,7 +54,7 @@ Using `erasedValue`, we can then define `defaultValue` as follows:
 ```scala
 import scala.compiletime.erasedValue
 
-inline def defaultValue[T] =
+transparent inline def defaultValue[T] =
   inline erasedValue[T] match
     case _: Byte    => Some(0: Byte)
     case _: Char    => Some(0: Char)
@@ -126,7 +128,7 @@ fail(identity("foo")) // error: failed on: identity("foo")
 
 ### The `scala.compiletime.ops` package
 
-The [`scala.compiletime.ops`](https://dotty.epfl.ch/api/scala/compiletime/ops.html) package contains types that provide support for
+The [`scala.compiletime.ops`](https://scala-lang.org/api/3.x/scala/compiletime/ops.html) package contains types that provide support for
 primitive operations on singleton types. For example,
 `scala.compiletime.ops.int.*` provides support for multiplying two singleton
 `Int` types, and `scala.compiletime.ops.boolean.&&` for the conjunction of two
@@ -213,7 +215,7 @@ would use it as follows:
 import scala.compiletime.summonFrom
 
 inline def setFor[T]: Set[T] = summonFrom {
-  case ord: Ordering[T] => new TreeSet[T](using ord)
+  case ord: Ordering[T] => new TreeSet[T]()(using ord)
   case _                => new HashSet[T]
 }
 ```
diff --git a/docs/docs/reference/metaprogramming/inline.md b/docs-for-scalalang/docs/reference/metaprogramming/inline.md
similarity index 98%
rename from docs/docs/reference/metaprogramming/inline.md
rename to docs-for-scalalang/docs/reference/metaprogramming/inline.md
index 8ccef49872b7..2e55b8e63cd0 100644
--- a/docs/docs/reference/metaprogramming/inline.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/inline.md
@@ -1,12 +1,14 @@
 ---
-layout: doc-page
 title: Inline
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/inline.html
+type: section
+num: 28
+previous-page: /scala3/reference/metaprogramming
+next-page: /scala3/reference/metaprogramming/compiletime-ops
 ---
 
 ## Inline Definitions
 
-`inline` is a new [soft modifier](../soft-modifier.md) that guarantees that a
+`inline` is a new [soft modifier](../soft-modifier.html) that guarantees that a
 definition will be inlined at the point of use. Example:
 
 ```scala
diff --git a/docs/docs/reference/metaprogramming/macros-spec.md b/docs-for-scalalang/docs/reference/metaprogramming/macros-spec.md
similarity index 97%
rename from docs/docs/reference/metaprogramming/macros-spec.md
rename to docs-for-scalalang/docs/reference/metaprogramming/macros-spec.md
index d152377e6d62..aa819c5ecb52 100644
--- a/docs/docs/reference/metaprogramming/macros-spec.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/macros-spec.md
@@ -1,14 +1,14 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Macros Spec"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/macros-spec.html
 ---
 
 ## Implementation
 
 ### Syntax
 
-Compared to the [Scala 3 reference grammar](../syntax.md)
+Compared to the [Scala 3 reference grammar](../syntax.html)
 there are the following syntax changes:
 ```
 SimpleExpr      ::=  ...
@@ -159,7 +159,7 @@ environments and terms.
                        Es |- 't: expr T
 ```
 The meta theory of a slightly simplified 2-stage variant of this calculus
-is studied [separately](./simple-smp.md).
+is studied [separately](./simple-smp.html).
 
 ## Going Further
 
diff --git a/docs/docs/reference/metaprogramming/macros.md b/docs-for-scalalang/docs/reference/metaprogramming/macros.md
similarity index 98%
rename from docs/docs/reference/metaprogramming/macros.md
rename to docs-for-scalalang/docs/reference/metaprogramming/macros.md
index 16af18d3c831..9d70230c1356 100644
--- a/docs/docs/reference/metaprogramming/macros.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/macros.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Macros"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/macros.html
+type: section
+num: 30
+previous-page: /scala3/reference/metaprogramming/compiletime-ops
+next-page: /scala3/reference/metaprogramming/staging
 ---
 
 > When developing macros enable `-Xcheck-macros` scalac option flag to have extra runtime checks.
@@ -18,7 +20,7 @@ schemes with the familiar string interpolation syntax.
 println(s"Hello, $name, here is the result of 1 + 1 = ${1 + 1}")
 ```
 
-In string interpolation we _quoted_ a string and then we _spliced_ into it, two others. The first, `name`, is a reference to a value of type [`String`](https://dotty.epfl.ch/api/scala/Predef$.html#String), and the second is an arithmetic expression that will be _evaluated_ followed by the splicing of its string representation.
+In string interpolation we _quoted_ a string and then we _spliced_ into it, two others. The first, `name`, is a reference to a value of type [`String`](https://scala-lang.org/api/3.x/scala/Predef$.html#String-0), and the second is an arithmetic expression that will be _evaluated_ followed by the splicing of its string representation.
 
 Quotes and splices in this section allow us to treat code in a similar way,
 effectively supporting macros. The entry point for macros is an inline method
@@ -83,7 +85,7 @@ and it takes types `T` to expressions of type `Type[T]`. Splicing
 takes expressions of type `Expr[T]` to expressions of type `T` and it
 takes expressions of type `Type[T]` to types `T`.
 
-The two types can be defined in package [`scala.quoted`](https://dotty.epfl.ch/api/scala/quoted.html) as follows:
+The two types can be defined in package [`scala.quoted`](https://scala-lang.org/api/3.x/scala/quoted.html) as follows:
 
 ```scala
 package scala.quoted
@@ -503,7 +505,7 @@ and allow for undefined compiler behavior if they are not. This is analogous to
 the status of pattern guards in Scala, which are also required, but not
 verified, to be pure.
 
-[Multi-Stage Programming](./staging.md) introduces one additional method where
+[Multi-Stage Programming](./staging.html) introduces one additional method where
 you can expand code at runtime with a method `run`. There is also a problem with
 that invocation of `run` in splices. Consider the following expression:
 
@@ -625,7 +627,7 @@ def setForExpr[T: Type](using Quotes): Expr[Set[T]] =
 
 ## Relationship with Transparent Inline
 
-[Inline](./inline.md) documents inlining. The code below introduces a transparent
+[Inline](./inline.html) documents inlining. The code below introduces a transparent
 inline method that can calculate either a value of type `Int` or a value of type
 `String`.
 
@@ -820,4 +822,4 @@ To match an actual application we can use braces on the function part `${b}(a1,
 
 ## More details
 
-[More details](./macros-spec.md)
+[More details](./macros-spec.html)
diff --git a/docs/docs/reference/metaprogramming/reflection.md b/docs-for-scalalang/docs/reference/metaprogramming/reflection.md
similarity index 92%
rename from docs/docs/reference/metaprogramming/reflection.md
rename to docs-for-scalalang/docs/reference/metaprogramming/reflection.md
index 74bb4f693e1b..a7c65cff680a 100644
--- a/docs/docs/reference/metaprogramming/reflection.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/reflection.md
@@ -1,20 +1,22 @@
 ---
-layout: doc-page
 title: "Reflection"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/reflection.html
+type: section
+num: 32
+previous-page: /scala3/reference/metaprogramming/staging
+next-page: /scala3/reference/metaprogramming/tasty-inspect
 ---
 
 Reflection enables inspection and construction of Typed Abstract Syntax Trees
 (Typed-AST). It may be used on quoted expressions (`quoted.Expr`) and quoted
-types (`quoted.Type`) from [Macros](./macros.md) or on full TASTy files.
+types (`quoted.Type`) from [Macros](./macros.html) or on full TASTy files.
 
-If you are writing macros, please first read [Macros](./macros.md).
+If you are writing macros, please first read [Macros](./macros.html).
 You may find all you need without using quote reflection.
 
 ## API: From quotes and splices to TASTy reflect trees and back
 
 With `quoted.Expr` and `quoted.Type` we can compute code but also analyze code
-by inspecting the ASTs. [Macros](./macros.md) provide the guarantee that the
+by inspecting the ASTs. [Macros](./macros.html) provide the guarantee that the
 generation of code will be type-correct. Using quote reflection will break these
 guarantees and may fail at macro expansion time, hence additional explicit
 checks must be done.
diff --git a/docs/docs/reference/metaprogramming/simple-smp.md b/docs-for-scalalang/docs/reference/metaprogramming/simple-smp.md
similarity index 98%
rename from docs/docs/reference/metaprogramming/simple-smp.md
rename to docs-for-scalalang/docs/reference/metaprogramming/simple-smp.md
index 7335135869c7..6a7e2c0fbae1 100644
--- a/docs/docs/reference/metaprogramming/simple-smp.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/simple-smp.md
@@ -1,10 +1,11 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "The Meta-theory of Symmetric Metaprogramming"
 ---
 
 This note presents a simplified variant of
-[principled metaprogramming](./macros.md)
+[principled metaprogramming](./macros.html)
 and sketches its soundness proof. The variant treats only dialogues
 between two stages. A program can have quotes which can contain
 splices (which can contain quotes, which can contain splices, and so
diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs-for-scalalang/docs/reference/metaprogramming/staging.md
similarity index 95%
rename from docs/docs/reference/metaprogramming/staging.md
rename to docs-for-scalalang/docs/reference/metaprogramming/staging.md
index 2b76df3f5fd5..0e90966c85b2 100644
--- a/docs/docs/reference/metaprogramming/staging.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/staging.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Runtime Multi-Stage Programming"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/staging.html
+type: section
+num: 31
+previous-page: /scala3/reference/metaprogramming/macros
+next-page: /scala3/reference/metaprogramming/reflection
 ---
 
 The framework expresses at the same time compile-time metaprogramming and
@@ -97,7 +99,7 @@ scala -with-compiler -classpath out Test
 
 ## Example
 
-Now take exactly the same example as in [Macros](./macros.md). Assume that we
+Now take exactly the same example as in [Macros](./macros.html). Assume that we
 do not want to pass an array statically but generate code at run-time and pass
 the value, also at run-time. Note, how we make a future-stage function of type
 `Expr[Array[Int] => Int]` in line 6 below. Using `staging.run { ... }` we can evaluate an
diff --git a/docs/docs/reference/metaprogramming/tasty-inspect.md b/docs-for-scalalang/docs/reference/metaprogramming/tasty-inspect.md
similarity index 92%
rename from docs/docs/reference/metaprogramming/tasty-inspect.md
rename to docs-for-scalalang/docs/reference/metaprogramming/tasty-inspect.md
index 2ab2ce84c354..32bc2efa4313 100644
--- a/docs/docs/reference/metaprogramming/tasty-inspect.md
+++ b/docs-for-scalalang/docs/reference/metaprogramming/tasty-inspect.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "TASTy Inspection"
-movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming/tasty-inspect.html
+type: section
+num: 33
+previous-page: /scala3/reference/metaprogramming/reflection
+next-page: /scala3/reference/other-new-features
 ---
 
 ```scala
diff --git a/docs-for-scalalang/docs/reference/new-types.md b/docs-for-scalalang/docs/reference/new-types.md
new file mode 100644
index 000000000000..61368808406e
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/new-types.md
@@ -0,0 +1,9 @@
+---
+title: "New Types"
+type: chapter
+num: 2
+previous-page: /scala3/reference/overview
+next-page: /scala3/reference/new-types/intersection-types
+---
+
+This chapter documents the new types introduced in Scala 3.
diff --git a/docs/docs/reference/new-types/dependent-function-types-spec.md b/docs-for-scalalang/docs/reference/new-types/dependent-function-types-spec.md
similarity index 94%
rename from docs/docs/reference/new-types/dependent-function-types-spec.md
rename to docs-for-scalalang/docs/reference/new-types/dependent-function-types-spec.md
index b89f04327989..07a07b74287c 100644
--- a/docs/docs/reference/new-types/dependent-function-types-spec.md
+++ b/docs-for-scalalang/docs/reference/new-types/dependent-function-types-spec.md
@@ -1,14 +1,14 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Dependent Function Types - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/dependent-function-types-spec.html
 ---
 
 Initial implementation in [PR #3464](https://github.com/lampepfl/dotty/pull/3464).
 
 ## Syntax
 
-```ebnf
+```
 FunArgTypes       ::=  InfixType
                     |  ‘(’ [ FunArgType {',' FunArgType } ] ‘)’
                     |  ‘(’ TypedFunParam {',' TypedFunParam } ‘)’
@@ -39,7 +39,7 @@ dependent function types for methods with dependent result types.
 
 Dependent functions can be implicit, and generalize to arity `N > 22` in the
 same way that other functions do, see
-[the corresponding documentation](../dropped-features/limit22.md).
+[the corresponding documentation](../dropped-features/limit22.html).
 
 ## Examples
 
diff --git a/docs/docs/reference/new-types/dependent-function-types.md b/docs-for-scalalang/docs/reference/new-types/dependent-function-types.md
similarity index 84%
rename from docs/docs/reference/new-types/dependent-function-types.md
rename to docs-for-scalalang/docs/reference/new-types/dependent-function-types.md
index 45e86120af6f..ffa9012c4ad3 100644
--- a/docs/docs/reference/new-types/dependent-function-types.md
+++ b/docs-for-scalalang/docs/reference/new-types/dependent-function-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Dependent Function Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/dependent-function-types.html
+type: section
+num: 7
+previous-page: /scala3/reference/new-types/match-types
+next-page: /scala3/reference/new-types/polymorphic-function-types
 ---
 
 A dependent function type is a function type whose result depends
@@ -36,7 +38,7 @@ This type describes function values that take any argument `e` of type
 `Entry` and return a result of type `e.Key`.
 
 Recall that a normal function type `A => B` is represented as an
-instance of the [`Function1` trait](https://dotty.epfl.ch/api/scala/Function1.html)
+instance of the [`Function1` trait](https://scala-lang.org/api/3.x/scala/Function1.html)
 (i.e. `Function1[A, B]`) and analogously for functions with more parameters. Dependent functions
 are also represented as instances of these traits, but they get an additional
 refinement. In fact, the dependent function type above is just syntactic sugar for
@@ -46,4 +48,4 @@ Function1[Entry, Entry#Key]:
   def apply(e: Entry): e.Key
 ```
 
-[More details](./dependent-function-types-spec.md)
+[More details](./dependent-function-types-spec.html)
diff --git a/docs/docs/reference/new-types/intersection-types-spec.md b/docs-for-scalalang/docs/reference/new-types/intersection-types-spec.md
similarity index 96%
rename from docs/docs/reference/new-types/intersection-types-spec.md
rename to docs-for-scalalang/docs/reference/new-types/intersection-types-spec.md
index 4d236c37dcc3..aeceeac04868 100644
--- a/docs/docs/reference/new-types/intersection-types-spec.md
+++ b/docs-for-scalalang/docs/reference/new-types/intersection-types-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Intersection Types - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/intersection-types-spec.html
 ---
 
 ## Syntax
diff --git a/docs/docs/reference/new-types/intersection-types.md b/docs-for-scalalang/docs/reference/new-types/intersection-types.md
similarity index 90%
rename from docs/docs/reference/new-types/intersection-types.md
rename to docs-for-scalalang/docs/reference/new-types/intersection-types.md
index d498e664d150..e912ec699457 100644
--- a/docs/docs/reference/new-types/intersection-types.md
+++ b/docs-for-scalalang/docs/reference/new-types/intersection-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
-title: "Intersection Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/intersection-types.html
+title: Intersection Types
+type: section
+num: 3
+previous-page: /scala3/reference/new-types
+next-page: /scala3/reference/new-types/union-types
 ---
 
 Used on types, the `&` operator creates an intersection type.
@@ -65,4 +67,4 @@ class C extends A, B:
 ```
 
 
-[More details](./intersection-types-spec.md)
+[More details](./intersection-types-spec.html)
diff --git a/docs/docs/reference/new-types/match-types.md b/docs-for-scalalang/docs/reference/new-types/match-types.md
similarity index 98%
rename from docs/docs/reference/new-types/match-types.md
rename to docs-for-scalalang/docs/reference/new-types/match-types.md
index 0ec8f3e58932..2516fe78e3ce 100644
--- a/docs/docs/reference/new-types/match-types.md
+++ b/docs-for-scalalang/docs/reference/new-types/match-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Match Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/match-types.html
+type: section
+num: 6
+previous-page: /scala3/reference/new-types/type-lambdas
+next-page: /scala3/reference/new-types/dependent-function-types
 ---
 
 A match type reduces to one of its right-hand sides, depending on the type of
diff --git a/docs/docs/reference/new-types/polymorphic-function-types.md b/docs-for-scalalang/docs/reference/new-types/polymorphic-function-types.md
similarity index 94%
rename from docs/docs/reference/new-types/polymorphic-function-types.md
rename to docs-for-scalalang/docs/reference/new-types/polymorphic-function-types.md
index 2a803f5e65db..58224ef0de43 100644
--- a/docs/docs/reference/new-types/polymorphic-function-types.md
+++ b/docs-for-scalalang/docs/reference/new-types/polymorphic-function-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Polymorphic Function Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/polymorphic-function-types.html
+type: section
+num: 8
+previous-page: /scala3/reference/new-types/dependent-function-types
+next-page: /scala3/reference/enums
 ---
 
 A polymorphic function type is a function type which accepts type parameters.
@@ -81,7 +83,7 @@ println(e1) // Apply(Apply(Var(wrap),Var(f)),Apply(Var(wrap),Var(a)))
 ## Relationship With Type Lambdas
 
 Polymorphic function types are not to be confused with
-[_type lambdas_](type-lambdas.md).
+[_type lambdas_](type-lambdas.html).
 While the former describes the _type_ of a polymorphic _value_,
 the latter is an actual function value _at the type level_.
 
diff --git a/docs/docs/reference/new-types/type-lambdas-spec.md b/docs-for-scalalang/docs/reference/new-types/type-lambdas-spec.md
similarity index 96%
rename from docs/docs/reference/new-types/type-lambdas-spec.md
rename to docs-for-scalalang/docs/reference/new-types/type-lambdas-spec.md
index de6bd293d201..06bd314512c4 100644
--- a/docs/docs/reference/new-types/type-lambdas-spec.md
+++ b/docs-for-scalalang/docs/reference/new-types/type-lambdas-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Type Lambdas - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/type-lambdas-spec.html
 ---
 
 ## Syntax
@@ -105,7 +105,7 @@ would be treated as covariant, `X` is used covariantly on its right-hand side.
 
 **Note**: The decision to treat `Nothing` as universal bottom type is provisional, and might be changed after further discussion.
 
-**Note**: Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.md)
+**Note**: Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.html)
 
 ## Curried Type Parameters
 
diff --git a/docs/docs/reference/new-types/type-lambdas.md b/docs-for-scalalang/docs/reference/new-types/type-lambdas.md
similarity index 69%
rename from docs/docs/reference/new-types/type-lambdas.md
rename to docs-for-scalalang/docs/reference/new-types/type-lambdas.md
index 8ede3f9305c7..8b12fbcece57 100644
--- a/docs/docs/reference/new-types/type-lambdas.md
+++ b/docs-for-scalalang/docs/reference/new-types/type-lambdas.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Type Lambdas"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/type-lambdas.html
+type: section
+num: 5
+previous-page: /scala3/reference/new-types/union-types
+next-page: /scala3/reference/new-types/match-types
 ---
 
 A _type lambda_ lets one express a higher-kinded type directly, without
@@ -14,4 +16,4 @@ a type definition.
 For instance, the type above defines a binary type constructor, which maps arguments `X` and `Y` to `Map[Y, X]`.
 Type parameters of type lambdas can have bounds, but they cannot carry `+` or `-` variance annotations.
 
-[More details](./type-lambdas-spec.md)
+[More details](./type-lambdas-spec.html)
diff --git a/docs/docs/reference/new-types/union-types-spec.md b/docs-for-scalalang/docs/reference/new-types/union-types-spec.md
similarity index 97%
rename from docs/docs/reference/new-types/union-types-spec.md
rename to docs-for-scalalang/docs/reference/new-types/union-types-spec.md
index d12e651536c5..9cfa27f619c3 100644
--- a/docs/docs/reference/new-types/union-types-spec.md
+++ b/docs-for-scalalang/docs/reference/new-types/union-types-spec.md
@@ -1,13 +1,13 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Union Types - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/union-types-spec.html
 ---
 
 ## Syntax
 
 Syntactically, unions follow the same rules as intersections, but have a lower precedence, see
-[Intersection Types - More Details](./intersection-types-spec.md).
+[Intersection Types - More Details](./intersection-types-spec.html).
 
 ### Interaction with pattern matching syntax
 `|` is also used in pattern matching to separate pattern alternatives and has
diff --git a/docs/docs/reference/new-types/union-types.md b/docs-for-scalalang/docs/reference/new-types/union-types.md
similarity index 87%
rename from docs/docs/reference/new-types/union-types.md
rename to docs-for-scalalang/docs/reference/new-types/union-types.md
index 9c52cff3864d..7b2922fe3415 100644
--- a/docs/docs/reference/new-types/union-types.md
+++ b/docs-for-scalalang/docs/reference/new-types/union-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Union Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/new-types/union-types.html
+type: section
+num: 4
+previous-page: /scala3/reference/new-types/intersection-types
+next-page: /scala3/reference/new-types/type-lambdas
 ---
 
 A union type `A | B` has as values all values of type `A` and also all values of type `B`.
@@ -43,4 +45,4 @@ The type of `res2` is `Object & Product`, which is a supertype of
 UserName`.  If we want the least supertype, we have to give it
 explicitly, as is done for the type of `either`.
 
-[More details](./union-types-spec.md)
+[More details](./union-types-spec.html)
diff --git a/docs-for-scalalang/docs/reference/other-new-features.md b/docs-for-scalalang/docs/reference/other-new-features.md
new file mode 100644
index 000000000000..faa2aefc6a91
--- /dev/null
+++ b/docs-for-scalalang/docs/reference/other-new-features.md
@@ -0,0 +1,9 @@
+---
+title: "Other New Features"
+type: chapter
+num: 34
+previous-page: /scala3/reference/metaprogramming/tasty-inspect
+next-page: /scala3/reference/other-new-features/trait-parameters
+---
+
+The following pages document new features of Scala 3.
diff --git a/docs/docs/reference/other-new-features/control-syntax.md b/docs-for-scalalang/docs/reference/other-new-features/control-syntax.md
similarity index 91%
rename from docs/docs/reference/other-new-features/control-syntax.md
rename to docs-for-scalalang/docs/reference/other-new-features/control-syntax.md
index 2f0bbde41331..0fefba262bf5 100644
--- a/docs/docs/reference/other-new-features/control-syntax.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/control-syntax.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: New Control Syntax
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/control-syntax.html
+type: section
+num: 46
+previous-page: /scala3/reference/other-new-features/targetName
+next-page: /scala3/reference/other-new-features/indentation
 ---
 
 Scala 3 has a new "quiet" syntax for control expressions that does not rely on
diff --git a/docs/docs/reference/other-new-features/creator-applications.md b/docs-for-scalalang/docs/reference/other-new-features/creator-applications.md
similarity index 94%
rename from docs/docs/reference/other-new-features/creator-applications.md
rename to docs-for-scalalang/docs/reference/other-new-features/creator-applications.md
index 17bc1574f763..0422bbfac77c 100644
--- a/docs/docs/reference/other-new-features/creator-applications.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/creator-applications.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Universal Apply Methods"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/creator-applications.html
+type: section
+num: 37
+previous-page: /scala3/reference/other-new-features/transparent-traits
+next-page: /scala3/reference/other-new-features/export
 ---
 
 Scala case classes generate apply methods, so that values of case classes can be created using simple
diff --git a/docs/docs/reference/other-new-features/experimental-defs.md b/docs-for-scalalang/docs/reference/other-new-features/experimental-defs.md
similarity index 100%
rename from docs/docs/reference/other-new-features/experimental-defs.md
rename to docs-for-scalalang/docs/reference/other-new-features/experimental-defs.md
diff --git a/docs/docs/reference/other-new-features/explicit-nulls.md b/docs-for-scalalang/docs/reference/other-new-features/explicit-nulls.md
similarity index 97%
rename from docs/docs/reference/other-new-features/explicit-nulls.md
rename to docs-for-scalalang/docs/reference/other-new-features/explicit-nulls.md
index abcaaac58196..a0dac187ae60 100644
--- a/docs/docs/reference/other-new-features/explicit-nulls.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/explicit-nulls.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Explicit Nulls"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/explicit-nulls.html
+type: section
+num: 48
+previous-page: /scala3/reference/other-new-features/indentation
+next-page: /scala3/reference/other-new-features/safe-initialization
 ---
 
 Explicit nulls is an opt-in feature that modifies the Scala type system, which makes reference types
@@ -13,7 +15,7 @@ This means the following code will no longer typecheck:
 val x: String = null // error: found `Null`, but required `String`
 ```
 
-Instead, to mark a type as nullable we use a [union type](../new-types/union-types.md)
+Instead, to mark a type as nullable we use a [union type](../new-types/union-types.html)
 
 ```scala
 val x: String | Null = null // ok
@@ -36,7 +38,7 @@ When explicit nulls are enabled, the type hierarchy changes so that `Null` is on
 
 This is the new type hierarchy:
 
-!["Type Hierarchy for Explicit Nulls"](/images/explicit-nulls/explicit-nulls-type-hierarchy.png)
+!["Type Hierarchy for Explicit Nulls"](/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png)
 
 After erasure, `Null` remains a subtype of all reference types (as forced by the JVM).
 
@@ -81,7 +83,7 @@ val c = new C()
 ```
 
 The unsoundness above can be caught by the compiler with the option `-Ysafe-init`.
-More details can be found in [safe initialization](./safe-initialization.md).
+More details can be found in [safe initialization](./safe-initialization.html).
 
 ## Equality
 
@@ -535,4 +537,4 @@ Our strategy for binary compatibility with Scala binaries that predate explicit
 and new libraries compiled without `-Yexplicit-nulls` is to leave the types unchanged
 and be compatible but unsound.
 
-[More details](../../internals/explicit-nulls.md)
+[More details](https://dotty.epfl.ch/docs/internals/explicit-nulls.html)
diff --git a/docs/docs/reference/other-new-features/export.md b/docs-for-scalalang/docs/reference/other-new-features/export.md
similarity index 97%
rename from docs/docs/reference/other-new-features/export.md
rename to docs-for-scalalang/docs/reference/other-new-features/export.md
index 59f227858320..49a190c4c923 100644
--- a/docs/docs/reference/other-new-features/export.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/export.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Export Clauses"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/export.html
+type: section
+num: 38
+previous-page: /scala3/reference/other-new-features/creator-applications
+next-page: /scala3/reference/other-new-features/opaques
 ---
 
 An export clause defines aliases for selected members of an object. Example:
@@ -136,7 +138,7 @@ ImportSpec        ::=  NamedSelector
                     |  WildcardSelector
                     | ‘{’ ImportSelectors) ‘}’
 NamedSelector     ::=  id [‘as’ (id | ‘_’)]
-WildCardSelector  ::=  ‘*' | ‘given’ [InfixType]
+WildCardSelector  ::=  ‘*’ | ‘given’ [InfixType]
 ImportSelectors   ::=  NamedSelector [‘,’ ImportSelectors]
                     |  WildCardSelector {‘,’ WildCardSelector}
 ```
diff --git a/docs/docs/reference/other-new-features/indentation-experimental.md b/docs-for-scalalang/docs/reference/other-new-features/indentation-experimental.md
similarity index 98%
rename from docs/docs/reference/other-new-features/indentation-experimental.md
rename to docs-for-scalalang/docs/reference/other-new-features/indentation-experimental.md
index ed6e838fd5a4..389219d8e877 100644
--- a/docs/docs/reference/other-new-features/indentation-experimental.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/indentation-experimental.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Fewer Braces"
 ---
 
diff --git a/docs/docs/reference/other-new-features/indentation.md b/docs-for-scalalang/docs/reference/other-new-features/indentation.md
similarity index 97%
rename from docs/docs/reference/other-new-features/indentation.md
rename to docs-for-scalalang/docs/reference/other-new-features/indentation.md
index c7a6fdbb7453..6a71e351f3c1 100644
--- a/docs/docs/reference/other-new-features/indentation.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/indentation.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Optional Braces"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/indentation.html
+type: section
+num: 47
+previous-page: /scala3/reference/other-new-features/control-syntax
+next-page: /scala3/reference/other-new-features/explicit-nulls
 ---
 
 Scala 3 enforces some rules on indentation and allows some occurrences of braces `{...}` to be optional:
@@ -85,7 +87,7 @@ There are two rules:
       then  else  do  catch  finally  yield  match
       ```
     - if the first token on the next line is a
-        [leading infix operator](../changed-features/operators.md).
+        [leading infix operator](../changed-features/operators.html).
       then its indentation width is less then the current indentation width,
       and it either matches a previous indentation width or is also less
       than the enclosing indentation width.
@@ -409,7 +411,7 @@ Significant indentation is enabled by default. It can be turned off by giving an
 The Scala 3 compiler can rewrite source code to indented code and back.
 When invoked with options `-rewrite -indent` it will rewrite braces to
 indented regions where possible. When invoked with options `-rewrite -no-indent` it will rewrite in the reverse direction, inserting braces for indentation regions.
-The `-indent` option only works on [new-style syntax](./control-syntax.md). So to go from old-style syntax to new-style indented code one has to invoke the compiler twice, first with options `-rewrite -new-syntax`, then again with options
+The `-indent` option only works on [new-style syntax](./control-syntax.html). So to go from old-style syntax to new-style indented code one has to invoke the compiler twice, first with options `-rewrite -new-syntax`, then again with options
 `-rewrite -indent`. To go in the opposite direction, from indented code to old-style syntax, it's `-rewrite -no-indent`, followed by `-rewrite -old-syntax`.
 
 ### Variant: Indentation Marker `:`
diff --git a/docs/docs/reference/other-new-features/kind-polymorphism.md b/docs-for-scalalang/docs/reference/other-new-features/kind-polymorphism.md
similarity index 94%
rename from docs/docs/reference/other-new-features/kind-polymorphism.md
rename to docs-for-scalalang/docs/reference/other-new-features/kind-polymorphism.md
index 7dbcf3e96927..7e69bca4ea51 100644
--- a/docs/docs/reference/other-new-features/kind-polymorphism.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/kind-polymorphism.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Kind Polymorphism"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/kind-polymorphism.html
+type: section
+num: 42
+previous-page: /scala3/reference/other-new-features/parameter-untupling
+next-page: /scala3/reference/other-new-features/matchable
 ---
 
 Normally type parameters in Scala are partitioned into _kinds_. First-level types are types of values. Higher-kinded types are type constructors
diff --git a/docs/docs/reference/other-new-features/matchable.md b/docs-for-scalalang/docs/reference/other-new-features/matchable.md
similarity index 94%
rename from docs/docs/reference/other-new-features/matchable.md
rename to docs-for-scalalang/docs/reference/other-new-features/matchable.md
index fdce97dab8f0..12b33e63f17d 100644
--- a/docs/docs/reference/other-new-features/matchable.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/matchable.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "The Matchable Trait"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/matchable.html
+type: section
+num: 43
+previous-page: /scala3/reference/other-new-features/kind-polymorphism
+next-page: /scala3/reference/other-new-features/threadUnsafe-annotation
 ---
 
 A new trait `Matchable` controls the ability to pattern match.
@@ -132,7 +134,7 @@ Here, universal `equals` will return true for
   Meter(10).equals(Second(10))
 ```
 
-even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.md) one can mitigate that problem somewhat by turning
+even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.html) one can mitigate that problem somewhat by turning
 
 ```scala
   Meter(10) == Second(10)
diff --git a/docs/docs/reference/other-new-features/named-typeargs.md b/docs-for-scalalang/docs/reference/other-new-features/named-typeargs.md
similarity index 69%
rename from docs/docs/reference/other-new-features/named-typeargs.md
rename to docs-for-scalalang/docs/reference/other-new-features/named-typeargs.md
index 11179c365da0..98009d4f3b7d 100644
--- a/docs/docs/reference/other-new-features/named-typeargs.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/named-typeargs.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Named Type Arguments"
 ---
 
diff --git a/docs/docs/reference/other-new-features/opaques-details.md b/docs-for-scalalang/docs/reference/other-new-features/opaques-details.md
similarity index 94%
rename from docs/docs/reference/other-new-features/opaques-details.md
rename to docs-for-scalalang/docs/reference/other-new-features/opaques-details.md
index ecfb78db48b7..b7891a86c081 100644
--- a/docs/docs/reference/other-new-features/opaques-details.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/opaques-details.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Opaque Type Aliases: More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/opaques-details.html
 ---
 
 ### Syntax
@@ -11,7 +11,7 @@ Modifier          ::=  ...
                     |  ‘opaque’
 ```
 
-`opaque` is a [soft modifier](../soft-modifier.md). It can still be used as a normal identifier when it is not in front of a definition keyword.
+`opaque` is a [soft modifier](../soft-modifier.html). It can still be used as a normal identifier when it is not in front of a definition keyword.
 
 Opaque type aliases must be members of classes, traits, or objects, or they are defined
 at the top-level. They cannot be defined in local blocks.
diff --git a/docs/docs/reference/other-new-features/opaques.md b/docs-for-scalalang/docs/reference/other-new-features/opaques.md
similarity index 96%
rename from docs/docs/reference/other-new-features/opaques.md
rename to docs-for-scalalang/docs/reference/other-new-features/opaques.md
index 402440bad90c..cb4cf635678b 100644
--- a/docs/docs/reference/other-new-features/opaques.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/opaques.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Opaque Type Aliases"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/opaques.html
+type: section
+num: 39
+previous-page: /scala3/reference/other-new-features/export
+next-page: /scala3/reference/other-new-features/open-classes
 ---
 
 Opaque types aliases provide type abstraction without any overhead. Example:
@@ -164,4 +166,4 @@ l1.mul(x, z) // error: found l2.Logarithm, required l1.Logarithm
 ```
 In general, one can think of an opaque type as being only transparent in the scope of `private[this]`.
 
-[More details](opaques-details.md)
+[More details](opaques-details.html)
diff --git a/docs/docs/reference/other-new-features/open-classes.md b/docs-for-scalalang/docs/reference/other-new-features/open-classes.md
similarity index 96%
rename from docs/docs/reference/other-new-features/open-classes.md
rename to docs-for-scalalang/docs/reference/other-new-features/open-classes.md
index f1ddcf8c190f..342faed61ad4 100644
--- a/docs/docs/reference/other-new-features/open-classes.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/open-classes.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Open Classes"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/open-classes.html
+type: section
+num: 40
+previous-page: /scala3/reference/other-new-features/opaques
+next-page: /scala3/reference/other-new-features/parameter-untupling
 ---
 
 An `open` modifier on a class signals that the class is planned for extensions. Example:
diff --git a/docs/docs/reference/other-new-features/parameter-untupling-spec.md b/docs-for-scalalang/docs/reference/other-new-features/parameter-untupling-spec.md
similarity index 95%
rename from docs/docs/reference/other-new-features/parameter-untupling-spec.md
rename to docs-for-scalalang/docs/reference/other-new-features/parameter-untupling-spec.md
index feedb77aa774..dbabf9d5d7d7 100644
--- a/docs/docs/reference/other-new-features/parameter-untupling-spec.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/parameter-untupling-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Parameter Untupling - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/parameter-untupling-spec.html
 ---
 
 ## Motivation
diff --git a/docs/docs/reference/other-new-features/parameter-untupling.md b/docs-for-scalalang/docs/reference/other-new-features/parameter-untupling.md
similarity index 81%
rename from docs/docs/reference/other-new-features/parameter-untupling.md
rename to docs-for-scalalang/docs/reference/other-new-features/parameter-untupling.md
index 1beed4968d4f..de58f8c61fd0 100644
--- a/docs/docs/reference/other-new-features/parameter-untupling.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/parameter-untupling.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Parameter Untupling"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/parameter-untupling.html
+type: section
+num: 41
+previous-page: /scala3/reference/other-new-features/open-classes
+next-page: /scala3/reference/other-new-features/kind-polymorphism
 ---
 
 Say you have a list of pairs
@@ -42,5 +44,5 @@ function type of the form `((T_1, ..., T_n)) => U`.
 
 For more information see:
 
-* [More details](./parameter-untupling-spec.md)
+* [More details](./parameter-untupling-spec.html)
 * [Issue #897](https://github.com/lampepfl/dotty/issues/897).
diff --git a/docs/docs/reference/other-new-features/safe-initialization.md b/docs-for-scalalang/docs/reference/other-new-features/safe-initialization.md
similarity index 98%
rename from docs/docs/reference/other-new-features/safe-initialization.md
rename to docs-for-scalalang/docs/reference/other-new-features/safe-initialization.md
index 09bb495f9263..7ecafb9a2888 100644
--- a/docs/docs/reference/other-new-features/safe-initialization.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/safe-initialization.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Safe Initialization"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/safe-initialization.html
+type: section
+num: 49
+previous-page: /scala3/reference/other-new-features/explicit-nulls
+next-page: /scala3/reference/other-new-features/type-test
 ---
 
 Scala 3 implements experimental safe initialization check, which can be enabled by the compiler option `-Ysafe-init`.
diff --git a/docs/docs/reference/other-new-features/targetName.md b/docs-for-scalalang/docs/reference/other-new-features/targetName.md
similarity index 96%
rename from docs/docs/reference/other-new-features/targetName.md
rename to docs-for-scalalang/docs/reference/other-new-features/targetName.md
index a83c4247c1ef..377bd2db10b0 100644
--- a/docs/docs/reference/other-new-features/targetName.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/targetName.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "The @targetName annotation"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/targetName.html
+type: section
+num: 45
+previous-page: /scala3/reference/other-new-features/threadUnsafe-annotation
+next-page: /scala3/reference/other-new-features/control-syntax
 ---
 
 A `@targetName` annotation on a definition defines an alternate name for the implementation of that definition. Example:
diff --git a/docs/docs/reference/other-new-features/threadUnsafe-annotation.md b/docs-for-scalalang/docs/reference/other-new-features/threadUnsafe-annotation.md
similarity index 71%
rename from docs/docs/reference/other-new-features/threadUnsafe-annotation.md
rename to docs-for-scalalang/docs/reference/other-new-features/threadUnsafe-annotation.md
index 99a16413f310..0916f6ff9b7b 100644
--- a/docs/docs/reference/other-new-features/threadUnsafe-annotation.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/threadUnsafe-annotation.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "The @threadUnsafe annotation"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/threadUnsafe-annotation.html
+type: section
+num: 44
+previous-page: /scala3/reference/other-new-features/matchable
+next-page: /scala3/reference/other-new-features/targetName
 ---
 
 A new annotation `@threadUnsafe` can be used on a field which defines
diff --git a/docs/docs/reference/other-new-features/trait-parameters.md b/docs-for-scalalang/docs/reference/other-new-features/trait-parameters.md
similarity index 91%
rename from docs/docs/reference/other-new-features/trait-parameters.md
rename to docs-for-scalalang/docs/reference/other-new-features/trait-parameters.md
index 9cc55c4e060b..a3a692f91cc7 100644
--- a/docs/docs/reference/other-new-features/trait-parameters.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/trait-parameters.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Trait Parameters"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/trait-parameters.html
+type: section
+num: 35
+previous-page: /scala3/reference/other-new-features
+next-page: /scala3/reference/other-new-features/transparent-traits
 ---
 
 Scala 3 allows traits to have parameters, just like classes have parameters.
@@ -56,7 +58,7 @@ class E extends Greeting("Bob"), FormalGreeting
 ### Traits With Context Parameters
 
 This "explicit extension required" rule is relaxed if the missing trait contains only
-[context parameters](../contextual/using-clauses). In that case the trait reference is
+[context parameters]({% link _scala3-reference/contextual/using-clauses.md %}). In that case the trait reference is
 implicitly inserted as an additional parent with inferred arguments. For instance,
 here's a variant of greetings where the addressee is a context parameter of type
 `ImpliedName`:
diff --git a/docs/docs/reference/other-new-features/transparent-traits.md b/docs-for-scalalang/docs/reference/other-new-features/transparent-traits.md
similarity index 88%
rename from docs/docs/reference/other-new-features/transparent-traits.md
rename to docs-for-scalalang/docs/reference/other-new-features/transparent-traits.md
index 20141213db0a..236f0c64d7b8 100644
--- a/docs/docs/reference/other-new-features/transparent-traits.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/transparent-traits.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Transparent Traits"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/transparent-traits.html
+type: section
+num: 36
+previous-page: /scala3/reference/other-new-features/trait-parameters
+next-page: /scala3/reference/other-new-features/creator-applications
 ---
 
 Traits are used in two roles:
@@ -20,7 +22,7 @@ val x = Set(if condition then Val else Var)
 
 Here, the inferred type of `x` is `Set[Kind & Product & Serializable]` whereas one would have hoped it to be `Set[Kind]`. The reasoning for this particular type to be inferred is as follows:
 
-- The type of the conditional above is the [union type](../new-types/union-types.md) `Val | Var`.
+- The type of the conditional above is the [union type](../new-types/union-types.html) `Val | Var`.
 - A union type is widened in type inference to the least supertype that is not a union type.
   In the example, this type is `Kind & Product & Serializable` since all three traits are traits of both `Val` and `Var`.
   So that type becomes the inferred element type of the set.
@@ -42,7 +44,7 @@ appear in the inferred type.
 
 The traits `scala.Product`, `java.lang.Serializable` and `java.lang.Comparable`
 are treated automatically as transparent. Other traits are turned into transparent traits using the modifier `transparent`. Scala 2 traits can also be made transparent
-by adding a [`@transparentTrait` annotation](https://dotty.epfl.ch/api/scala/annotation/transparentTrait.html). This annotation is defined in `scala.annotation`. It will be deprecated and phased out once Scala 2/3 interopability is no longer needed.
+by adding a [`@transparentTrait` annotation](https://scala-lang.org/api/3.x/scala/annotation/transparentTrait.html). This annotation is defined in `scala.annotation`. It will be deprecated and phased out once Scala 2/3 interopability is no longer needed.
 
 Typically, transparent traits are traits
 that influence the implementation of inheriting classes and traits that are not usually used as types by themselves. Two examples from the standard collection library are:
diff --git a/docs/docs/reference/other-new-features/type-test.md b/docs-for-scalalang/docs/reference/other-new-features/type-test.md
similarity index 97%
rename from docs/docs/reference/other-new-features/type-test.md
rename to docs-for-scalalang/docs/reference/other-new-features/type-test.md
index da9fa6a1c2b3..1fab03490e98 100644
--- a/docs/docs/reference/other-new-features/type-test.md
+++ b/docs-for-scalalang/docs/reference/other-new-features/type-test.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "TypeTest"
-movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/type-test.html
+type: section
+num: 50
+previous-page: /scala3/reference/other-new-features/safe-initialization
+next-page: /scala3/reference/changed-features
 ---
 
 ## TypeTest
diff --git a/docs/docs/reference/overview.md b/docs-for-scalalang/docs/reference/overview.md
similarity index 70%
rename from docs/docs/reference/overview.md
rename to docs-for-scalalang/docs/reference/overview.md
index 27f91a000e76..8366ec10ddc2 100644
--- a/docs/docs/reference/overview.md
+++ b/docs-for-scalalang/docs/reference/overview.md
@@ -1,8 +1,10 @@
 ---
-layout: doc-page
 title: "Overview"
-movedTo: https://docs.scala-lang.org/scala3/reference/overview.html
+type: chapter
+num: 1
+next-page: /scala3/reference/new-types
 ---
+
 Scala 3 implements many language changes and improvements over Scala 2.
 In this reference, we discuss design decisions and present important differences compared to Scala 2.
 
@@ -25,37 +27,37 @@ Corresponding to these goals, the language changes fall into seven categories:
 
 These new constructs directly model core features of DOT, higher-kinded types, and the [SI calculus for implicit resolution](https://infoscience.epfl.ch/record/229878/files/simplicitly_1.pdf).
 
-- [Intersection types](new-types/intersection-types.md), replacing compound types,
-- [Union types](new-types/union-types.md),
-- [Type lambdas](new-types/type-lambdas.md), replacing encodings using structural types and type projection.
-- [Context functions](contextual/context-functions.md), offering abstraction over given parameters.
+- [Intersection types](new-types/intersection-types.html), replacing compound types,
+- [Union types](new-types/union-types.html),
+- [Type lambdas](new-types/type-lambdas.html), replacing encodings using structural types and type projection.
+- [Context functions](contextual/context-functions.html), offering abstraction over given parameters.
 
 ## Simplifications
 
 These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.
 
-- [Trait parameters](other-new-features/trait-parameters.md)
-  replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct.
-- [Given instances](contextual/givens.md)
+- [Trait parameters](other-new-features/trait-parameters.html)
+  replace [early initializers](dropped-features/early-initializers.html) with a more generally useful construct.
+- [Given instances](contextual/givens.html)
   replace implicit objects and defs, focussing on intent over mechanism.
-- [Using clauses](contextual/using-clauses.md)
+- [Using clauses](contextual/using-clauses.html)
   replace implicit parameters, avoiding their ambiguities.
-- [Extension methods](contextual/extension-methods.md)
+- [Extension methods](contextual/extension-methods.html)
   replace implicit classes with a clearer and simpler mechanism.
-- [Opaque type aliases](other-new-features/opaques.md)
+- [Opaque type aliases](other-new-features/opaques.html)
   replace most uses of value classes while guaranteeing absence of boxing.
-- [Top-level definitions](dropped-features/package-objects.md)
+- [Top-level definitions](dropped-features/package-objects.html)
   replace package objects, dropping syntactic boilerplate.
-- [Export clauses](other-new-features/export.md)
+- [Export clauses](other-new-features/export.html)
   provide a simple and general way to express aggregation, which can replace
   the previous facade pattern of package objects inheriting from classes.
-- [Vararg splices](changed-features/vararg-splices.md)
+- [Vararg splices](changed-features/vararg-splices.html)
   now use the form `xs*` in function arguments and patterns instead of `xs: _*` and `xs @ _*`,
-- [Universal apply methods](other-new-features/creator-applications.md)
+- [Universal apply methods](other-new-features/creator-applications.html)
   allow using simple function call syntax instead of `new` expressions. `new` expressions stay around
   as a fallback for the cases where creator applications cannot be used.
 
-With the exception of [early initializers](dropped-features/early-initializers.md) and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later.
+With the exception of [early initializers](dropped-features/early-initializers.html) and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later.
 
 Value classes (superseded by opaque type aliases) are a special case. There are currently no deprecation plans for value classes, since we might bring them back in a more general form if they are supported natively by the JVM as is planned by [project Valhalla](https://openjdk.java.net/projects/valhalla/).
 
@@ -63,15 +65,15 @@ Value classes (superseded by opaque type aliases) are a special case. There are
 
 These constructs are restricted to make the language safer.
 
-- [Implicit Conversions](contextual/conversions.md):
+- [Implicit Conversions](contextual/conversions.html):
   there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
-- [Given Imports](contextual/given-imports.md):
+- [Given Imports](contextual/given-imports.html):
   implicits now require a special form of import, to make the import clearly visible.
-- [Type Projection](dropped-features/type-projection.md):
+- [Type Projection](dropped-features/type-projection.html):
   only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
-- [Multiversal Equality](contextual/multiversal-equality.md):
+- [Multiversal Equality](contextual/multiversal-equality.html):
   implement an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
-- [infix](changed-features/operators.md):
+- [infix](changed-features/operators.html):
   make method application syntax uniform across code bases.
 
 Unrestricted implicit conversions continue to be available in Scala 3.0, but will be deprecated and removed later. Unrestricted versions of the other constructs in the list above are available only under `-source 3.0-migration`.
@@ -80,37 +82,37 @@ Unrestricted implicit conversions continue to be available in Scala 3.0, but wil
 
 These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation.
 
-- [DelayedInit](dropped-features/delayed-init.md),
-- [Existential types](dropped-features/existential-types.md),
-- [Procedure syntax](dropped-features/procedure-syntax.md),
-- [Class shadowing](dropped-features/class-shadowing.md),
-- [XML literals](dropped-features/xml.md),
-- [Symbol literals](dropped-features/symlits.md),
-- [Auto application](dropped-features/auto-apply.md),
-- [Weak conformance](dropped-features/weak-conformance.md),
-- Compound types (replaced by [Intersection types](new-types/intersection-types.md)),
+- [DelayedInit](dropped-features/delayed-init.html),
+- [Existential types](dropped-features/existential-types.html),
+- [Procedure syntax](dropped-features/procedure-syntax.html),
+- [Class shadowing](dropped-features/class-shadowing.html),
+- [XML literals](dropped-features/xml.html),
+- [Symbol literals](dropped-features/symlits.html),
+- [Auto application](dropped-features/auto-apply.html),
+- [Weak conformance](dropped-features/weak-conformance.html),
+- Compound types (replaced by [Intersection types](new-types/intersection-types.html)),
 - [Auto tupling](https://github.com/lampepfl/dotty/pull/4311) (implemented, but not merged).
 
 The date when these constructs are dropped varies. The current status is:
 
 - Not implemented at all:
-  - DelayedInit, existential types, weak conformance.
+    - DelayedInit, existential types, weak conformance.
 - Supported under `-source 3.0-migration`:
-  - procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form.
+    - procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form.
 - Supported in 3.0, to be deprecated and phased out later:
-  - [XML literals](dropped-features/xml.md), compound types.
+    - [XML literals](dropped-features/xml.html), compound types.
 
 ## Changes
 
 These constructs have undergone changes to make them more regular and useful.
 
-- [Structural Types](changed-features/structural-types.md):
+- [Structural Types](changed-features/structural-types.html):
   They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
-- [Name-based pattern matching](changed-features/pattern-matching.md):
+- [Name-based pattern matching](changed-features/pattern-matching.html):
   The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
-- [Automatic Eta expansion](changed-features/eta-expansion.md):
+- [Automatic Eta expansion](changed-features/eta-expansion.html):
   Eta expansion is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
-- [Implicit Resolution](changed-features/implicit-resolution.md):
+- [Implicit Resolution](changed-features/implicit-resolution.html):
   The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.
 
 Most aspects of old-style implicit resolution are still available under `-source 3.0-migration`. The other changes in this list are applied unconditionally.
@@ -119,13 +121,13 @@ Most aspects of old-style implicit resolution are still available under `-source
 
 These are additions to the language that make it more powerful or pleasant to use.
 
-- [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md).
-- [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring.
-- [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
-- [Polymorphic function types](new-types/polymorphic-function-types.md) generalize polymorphic methods to polymorphic function values and types.
+- [Enums](enums/enums.html) provide concise syntax for enumerations and [algebraic data types](enums/adts.html).
+- [Parameter untupling](other-new-features/parameter-untupling.html) avoids having to use `case` for tupled parameter destructuring.
+- [Dependent function types](new-types/dependent-function-types.html) generalize dependent methods to dependent function values and types.
+- [Polymorphic function types](new-types/polymorphic-function-types.html) generalize polymorphic methods to polymorphic function values and types.
   _Current status_: There is a proposal and a merged prototype implementation, but the implementation has not been finalized (it is notably missing type inference support).
-- [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
-- [`@targetName` annotations](other-new-features/targetName.md) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.
+- [Kind polymorphism](other-new-features/kind-polymorphism.html) allows the definition of operators working equally on types and type constructors.
+- [`@targetName` annotations](other-new-features/targetName.html) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.
 
 ## Metaprogramming
 
@@ -135,19 +137,19 @@ It's worth noting that macros were never included in the [Scala 2 language speci
 
 To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority.
 
-- [Match Types](new-types/match-types.md)
+- [Match Types](new-types/match-types.html)
   allow computation on types.
-- [Inline](metaprogramming/inline.md)
+- [Inline](metaprogramming/inline.html)
   provides by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
-- [Quotes and Splices](metaprogramming/macros.md)
+- [Quotes and Splices](metaprogramming/macros.html)
   provide a principled way to express macros and staging with a unified set of abstractions.
-- [Type class derivation](contextual/derivation.md)
+- [Type class derivation](contextual/derivation.html)
   provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
-- [By-name context parameters](contextual/by-name-context-parameters.md)
+- [By-name context parameters](contextual/by-name-context-parameters.html)
   provide a more robust in-language implementation of the `Lazy` macro in [Shapeless](https://github.com/milessabin/shapeless).
 
 ## See Also
 
-[A classification of proposed language features](./features-classification.md) is
+[A classification of proposed language features](./features-classification.html) is
 an expanded version of this page that adds the status (i.e. relative importance to be a part of Scala 3, and relative urgency when to decide this) and expected migration cost
 of each language construct.
diff --git a/docs/docs/reference/soft-modifier.md b/docs-for-scalalang/docs/reference/soft-modifier.md
similarity index 95%
rename from docs/docs/reference/soft-modifier.md
rename to docs-for-scalalang/docs/reference/soft-modifier.md
index 2b81e39afb04..3e9bb73b7586 100644
--- a/docs/docs/reference/soft-modifier.md
+++ b/docs-for-scalalang/docs/reference/soft-modifier.md
@@ -1,6 +1,7 @@
 ---
-layout: doc-page
-title: Soft Keywords
+layout: singlepage-overview
+scala3: true
+title: "Soft Keywords"
 ---
 
 A soft modifier is one of the identifiers `opaque`, `inline`, `open`, `transparent`, and `infix`.
diff --git a/docs/docs/reference/syntax.md b/docs-for-scalalang/docs/reference/syntax.md
similarity index 98%
rename from docs/docs/reference/syntax.md
rename to docs-for-scalalang/docs/reference/syntax.md
index 8e5a7c3d6c52..365d861f4688 100644
--- a/docs/docs/reference/syntax.md
+++ b/docs-for-scalalang/docs/reference/syntax.md
@@ -1,7 +1,8 @@
 ---
-layout: doc-page
 title: "Scala 3 Syntax Summary"
-movedTo: https://docs.scala-lang.org/scala3/reference/syntax.html
+type: chapter
+num: 87
+previous-page: /scala3/reference/dropped-features/wildcard-init
 ---
 
 The following description of Scala tokens uses literal characters `‘c’` when
@@ -10,7 +11,7 @@ referring to the ASCII fragment `\u0000` – `\u007F`.
 _Unicode escapes_ are used to represent the [Unicode character](https://www.w3.org/International/articles/definitions-characters/) with the given
 hexadecimal code:
 
-```ebnf
+```
 UnicodeEscape ::= ‘\’ ‘u’ {‘u’} hexDigit hexDigit hexDigit hexDigit
 hexDigit      ::= ‘0’ | … | ‘9’ | ‘A’ | … | ‘F’ | ‘a’ | … | ‘f’
 ```
@@ -22,7 +23,7 @@ Informal descriptions are typeset as `“some comment”`.
 The lexical syntax of Scala is given by the following grammar in EBNF
 form.
 
-```ebnf
+```
 whiteSpace       ::=  ‘\u0020’ | ‘\u0009’ | ‘\u000D’ | ‘\u000A’
 upper            ::=  ‘A’ | … | ‘Z’ | ‘\$’ | ‘_’  “… and Unicode category Lu”
 lower            ::=  ‘a’ | … | ‘z’ “… and Unicode category Ll”
@@ -90,7 +91,7 @@ semi             ::=  ‘;’ |  nl {nl}
 
 ## Optional Braces
 
-The lexical analyzer also inserts `indent` and `outdent` tokens that represent regions of indented code [at certain points](./other-new-features/indentation.md).
+The lexical analyzer also inserts `indent` and `outdent` tokens that represent regions of indented code [at certain points](./other-new-features/indentation.html).
 
 In the context-free productions below we use the notation `<<< ts >>>`
 to indicate a token sequence `ts` that is either enclosed in a pair of braces `{ ts }` or that constitutes an indented region `indent ts outdent`. Analogously, the
@@ -125,7 +126,7 @@ type      val       var       while     with      yield
 as  derives  end  extension  infix  inline  opaque  open  transparent  using  |  *  +  -
 ```
 
-See the [separate section on soft keywords](./soft-modifier.md) for additional
+See the [separate section on soft keywords](./soft-modifier.html) for additional
 details on where a soft keyword is recognized.
 
 ## Context-free Syntax
@@ -134,7 +135,7 @@ The context-free syntax of Scala is given by the following EBNF
 grammar:
 
 ### Literals and Paths
-```ebnf
+```
 SimpleLiteral     ::=  [‘-’] integerLiteral
                     |  [‘-’] floatingPointLiteral
                     |  booleanLiteral
@@ -156,7 +157,7 @@ ClassQualifier    ::=  ‘[’ id ‘]’
 ```
 
 ### Types
-```ebnf
+```
 Type              ::=  FunType
                     |  HkTypeParamClause ‘=>>’ Type
                     |  FunParamClause ‘=>>’ Type
@@ -201,7 +202,7 @@ Types             ::=  Type {‘,’ Type}
 ```
 
 ### Expressions
-```ebnf
+```
 Expr              ::=  FunParams (‘=>’ | ‘?=>’) Expr
                     |  HkTypeParamClause ‘=>’ Expr
                     |  Expr1
@@ -303,7 +304,7 @@ ArgumentPatterns  ::=  ‘(’ [Patterns] ‘)’
 ```
 
 ### Type and Value Parameters
-```ebnf
+```
 ClsTypeParamClause::=  ‘[’ ClsTypeParam {‘,’ ClsTypeParam} ‘]’
 ClsTypeParam      ::=  {Annotation} [‘+’ | ‘-’] id [HkTypeParamClause] TypeParamBounds
 
@@ -331,7 +332,7 @@ DefParam          ::=  {Annotation} [‘inline’] Param
 ```
 
 ### Bindings and Imports
-```ebnf
+```
 Bindings          ::=  ‘(’ [Binding {‘,’ Binding}] ‘)’
 Binding           ::=  (id | ‘_’) [‘:’ Type]
 
@@ -369,7 +370,7 @@ EndMarkerTag      ::=  id | ‘if’ | ‘while’ | ‘for’ | ‘match’ | 
 ```
 
 ### Declarations and Definitions
-```ebnf
+```
 RefineDcl         ::=  ‘val’ ValDcl
                     |  ‘def’ DefDcl
                     |  ‘type’ {nl} TypeDcl
diff --git a/docs/docs/usage/scaladoc/blog.md b/docs-for-scalalang/docs/usage/scaladoc/blog.md
similarity index 77%
rename from docs/docs/usage/scaladoc/blog.md
rename to docs-for-scalalang/docs/usage/scaladoc/blog.md
index a12804ad4757..b80faf9bdb90 100644
--- a/docs/docs/usage/scaladoc/blog.md
+++ b/docs-for-scalalang/docs/usage/scaladoc/blog.md
@@ -1,9 +1,12 @@
 ---
-title: Built-in blog
+layout: multipage-overview
+title: "Built-in blog"
+partof: scala3-scaladoc
+num: 5
+previous-page: static-site
+next-page: site-versioning
 ---
 
-# {{page.title}}
-
 Scaladoc allows you to include a simple blog in your documentation. For now, it
 provides only basic features. In the future, we plan to include more advanced
 features like tagging or author pages.
@@ -22,7 +25,7 @@ All your blogposts must be put under `blog/_posts` directory.
 │   └── index.html
 ```
 
-If you are using yaml [sidebar](./staticSite.html#sidebar) don't forget to place
+If you are using yaml [sidebar]({% link _overviews/scala3-scaladoc/static-site.md %}#sidebar) don't forget to place
 
 ```
 sidebar:
diff --git a/docs/docs/usage/scaladoc/scaladocDocstrings.md b/docs-for-scalalang/docs/usage/scaladoc/docstrings.md
similarity index 97%
rename from docs/docs/usage/scaladoc/scaladocDocstrings.md
rename to docs-for-scalalang/docs/usage/scaladoc/docstrings.md
index 115ef3395c80..72a8f99c88b5 100644
--- a/docs/docs/usage/scaladoc/scaladocDocstrings.md
+++ b/docs-for-scalalang/docs/usage/scaladoc/docstrings.md
@@ -1,9 +1,12 @@
 ---
-title: Scaladoc docstrings - specific Tags and Features
+layout: multipage-overview
+title: "Docstrings - specific Tags and Features"
+partof: scala3-scaladoc
+num: 2
+previous-page: index
+next-page: linking
 ---
 
-# {{page.title}}
-
 This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc.
 Since many things are the same as in the old scaladoc, some parts are reused from this [article](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html)
 
@@ -192,4 +195,4 @@ Further information on the formatting and style recommendations can be found in
 
 Scaladoc allows linking to API documentation with Wiki-style links. Linking to
 `scala.collection.immutable.List` is as simple as
-`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./linkingDocumentation.html#definition-links).
+`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation]({% link _overviews/scala3-scaladoc/linking.md %}#definition-links).
diff --git a/docs-for-scalalang/docs/usage/scaladoc/index.md b/docs-for-scalalang/docs/usage/scaladoc/index.md
new file mode 100644
index 000000000000..1aac56b5735e
--- /dev/null
+++ b/docs-for-scalalang/docs/usage/scaladoc/index.md
@@ -0,0 +1,11 @@
+---
+layout: multipage-overview
+title: "Scaladoc"
+partof: scala3-scaladoc
+num: 1
+next-page: docstrings
+---
+
+![scaladoc logo]({{ site.baseurl }}/resources/images/scala3/scaladoc/logo.svg)
+
+scaladoc is a tool to generate the API documentation of your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`.
diff --git a/docs/docs/usage/scaladoc/linkingDocumentation.md b/docs-for-scalalang/docs/usage/scaladoc/linking.md
similarity index 96%
rename from docs/docs/usage/scaladoc/linkingDocumentation.md
rename to docs-for-scalalang/docs/usage/scaladoc/linking.md
index f965e8bd8963..bfac8b9cef22 100644
--- a/docs/docs/usage/scaladoc/linkingDocumentation.md
+++ b/docs-for-scalalang/docs/usage/scaladoc/linking.md
@@ -1,9 +1,12 @@
 ---
-title: Linking documentation
+layout: multipage-overview
+title: "Linking documentation"
+partof: scala3-scaladoc
+num: 3
+previous-page: docstrings
+next-page: static-site
 ---
 
-# {{ page.title }}
-
 Scaladoc's main feature is creating API documentation from code comments.
 
 By default, the code comments are understood as Markdown, though we also support
diff --git a/docs-for-scalalang/docs/usage/scaladoc/search-engine.md b/docs-for-scalalang/docs/usage/scaladoc/search-engine.md
new file mode 100644
index 000000000000..b338d38792a7
--- /dev/null
+++ b/docs-for-scalalang/docs/usage/scaladoc/search-engine.md
@@ -0,0 +1,86 @@
+---
+layout: multipage-overview
+title: "Type-based search"
+partof: scala3-scaladoc
+num: 7
+previous-page: site-versioning
+next-page: settings
+---
+
+Searching for functions by their symbolic names can be time-consuming.
+That is why the new scaladoc allows searching for methods and fields by their types.
+
+
+Consider the following extension method definition:
+```
+extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
+```
+Instead of searching for `span` we can also search for `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`.
+
+To use this feature, type the signature of the member you are looking for in the scaladoc searchbar. This is how it works:
+
+![]({{ site.baseurl }}/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif)
+
+This feature is provided by the [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with the development of this feature, follow the [Inkuire repository](https://github.com/VirtusLab/Inkuire).
+
+## Examples of queries
+
+Some examples of queries with intended results:
+- `List[Int] => (Int => Long) => List[Long]` -> `map`
+- `Seq[A] => (A => B) => Seq[B]` -> `map`
+- `(A, B) => A` -> `_1`
+- `Set[Long] => Long => Boolean` -> `contains`
+- `Int => Long => Int` -> `const`
+- `String => Int => Char` -> `apply`
+- `(Int & Float) => (String | Double)` -> `toDouble`, `toString`
+- `F[A] => Int` -> `length`
+
+## Query syntax
+
+In order for a scaladoc searchbar query to be searched using Inkuire instead of the default search engine, the query has to contain the `=>` character sequence.
+
+Accepted input is similar to a curried function signature in Scala 3. With some differences:
+- AndTypes, OrTypes and Functions have to be enclosed in parentheses e.g. `(Int & Any) => String`
+- fields and parameterless methods can be found by preceding their type with `=>`, e.g., `=> Int`
+- A wildcard `_` can be used to indicate that we want to match any type in a given place e.g. `Long => Double => _`
+- Types in the form of single letter e.g. `A` or a letter with a digit `X1` are automatically assumed to be type variables
+- Other type variables can be declared just like in polymorphic functions e.g. `[AVariable, AlsoAVariable] => AVariable => AlsoAVariable => AVariable`
+
+### Working with type aliases and method receivers
+
+When it comes to how the code is mapped to InkuireDb entries, there are some transformations to make the engine more opinionated (though open to suggestions and changes). Firstly, the receiver (non-module owner) of a function can be treated as a first argument. Automatic currying is also applied, so that the results don't depend on argument lists. When finding matches, `val`s and `def`s are not distinguished.
+
+So the following declarations should be found by query `Num => Int => Int => Int`:
+```
+class Num():
+  def a(i: Int, j: Int): Int
+  def b(i: Int)(j: Int): Int
+  def c(i: Int): (Int => Int)
+  val d: Int => Int => Int
+  val e: Int => Int => Int
+  val f: (Int, Int) => Int
+end Num
+
+def g(i: Num, j: Int, k: Int): Int
+extension (i: Num) def h(j: Int, k: Int): Int
+def i(i: Num, j: Int)(k: Int): Int
+extension (i: Num) def j(j: Int)(k: Int): Int
+...
+```
+
+When it comes to type aliases, they are desugared on both the declaration and the query signature. This means that for declarations:
+```
+type Name = String
+
+def fromName(name: Name): String
+def fromString(str: String): Name
+```
+both methods, `fromName` and `fromString`, should be found for queries `Name => Name`, `String => String`, `Name => String` and `String => Name`.
+
+## How it works
+
+Inkuire works as a JavaScript worker in the browser thanks to the power of [ScalaJS](https://www.scala-js.org/).
+
+To enable Inkuire when running scaladoc, add the flag `-Ygenerate-inkuire`. By adding this flag two files are generated:
+- `inkuire-db.json` - this is the file containing all the searchable declarations from the currently documented project in a format readable to the Inkuire search engine.
+- `inkuire-config.json` - this file contains the locations of the database files that should be searchable from the documentation of the current project. By default, it will be generated with the location of the local db file as well as the default implied locations of database files in [External mappings](/scala3/guides/scaladoc/settings.html#-external-mappings).
diff --git a/docs/docs/usage/scaladoc/settings.md b/docs-for-scalalang/docs/usage/scaladoc/settings.md
similarity index 95%
rename from docs/docs/usage/scaladoc/settings.md
rename to docs-for-scalalang/docs/usage/scaladoc/settings.md
index 4881c9790d4e..803330d69eb0 100644
--- a/docs/docs/usage/scaladoc/settings.md
+++ b/docs-for-scalalang/docs/usage/scaladoc/settings.md
@@ -1,9 +1,11 @@
 ---
-title: Scaladoc settings
+layout: multipage-overview
+title: "Settings"
+partof: scala3-scaladoc
+num: 8
+previous-page: search-engine
 ---
 
-# {{page.title}}
-
 This chapter lists the configuration options that can be used when calling scaladoc. Some of the information shown here can be found by calling scaladoc with the `-help` flag.
 
 ## Parity with scaladoc for Scala 2
@@ -77,7 +79,7 @@ In such case paths used in templates will be relativized against `<sub-path>`
 Mapping between regexes matching classpath entries and external documentation.
 
 Example external mapping is:
-`-external-mappings:.*scala.*::scaladoc3::http://dotty.epfl.ch/api/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/`
+`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/`
 
 A mapping is of the form '\<regex>::\[scaladoc3|scaladoc|javadoc]::\<path>'. You can supply several mappings, separated by commas, as shown in the example.
 
@@ -158,7 +160,7 @@ compile - Enables snippet checking.
 nocompile - Disables snippet checking.
 fail - Enables snippet checking, asserts that snippet doesn't compile.
 
-The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page](docs/reference/other-new-features/opaques.html)
+The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page]({% link _scala3-reference/other-new-features/opaques.md %})
 
 Example usage:
 
diff --git a/docs/docs/usage/scaladoc/site-versioning.md b/docs-for-scalalang/docs/usage/scaladoc/site-versioning.md
similarity index 90%
rename from docs/docs/usage/scaladoc/site-versioning.md
rename to docs-for-scalalang/docs/usage/scaladoc/site-versioning.md
index 9cd1e3d9fc5f..f7424fc90657 100644
--- a/docs/docs/usage/scaladoc/site-versioning.md
+++ b/docs-for-scalalang/docs/usage/scaladoc/site-versioning.md
@@ -1,9 +1,12 @@
 ---
-title: Site versioning
+layout: multipage-overview
+title: "Site versioning"
+partof: scala3-scaladoc
+num: 6
+previous-page: blog
+next-page: search-engine
 ---
 
-# {{ page.title }}
-
 Scaladoc provides a convenient way to switch between different versions of the documentation. The feature is useful if we want to expose older docs for users that didn't migrate to the new version of our library.
 
 ### How to setup it
@@ -33,4 +36,4 @@ doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/v
 
 Providing a JSON file via `-versions-dictionary-url` enables scaladoc to link between versions. It is also convenient to be able to change the revision label in the drop-down menu. Everything will change automatically.
 
-![](images/scaladoc/nightly.gif)
+![]({{ site.baseurl }}/resources/images/scala3/scaladoc/nightly.gif)
diff --git a/docs/docs/usage/scaladoc/staticSite.md b/docs-for-scalalang/docs/usage/scaladoc/static-site.md
similarity index 77%
rename from docs/docs/usage/scaladoc/staticSite.md
rename to docs-for-scalalang/docs/usage/scaladoc/static-site.md
index f9d61342cba7..46bcdc018350 100644
--- a/docs/docs/usage/scaladoc/staticSite.md
+++ b/docs-for-scalalang/docs/usage/scaladoc/static-site.md
@@ -1,9 +1,12 @@
 ---
-title: Static documentation
+layout: multipage-overview
+title: "Static documentation"
+partof: scala3-scaladoc
+num: 4
+previous-page: linking
+next-page: blog
 ---
 
-# {{ page.title }}
-
 Scaladoc can generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/).
 Having a combined tool allows providing interaction between static documentation and API, thus allowing the two to blend naturally.
 
@@ -41,6 +44,7 @@ In Scaladoc, all templates can contain YAML front-matter. The front-matter
 is parsed and put into the `page` variable available in templates via Liquid.
 
 Example front-matter
+
 ```
 ---
 title: My custom title
@@ -51,10 +55,10 @@ Scaladoc uses some predefined properties to controls some aspects of page.
 
 Predefined properties:
 
- - **title** provide page title that will be used in navigation and HTML metadata.
- - **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.**
- - **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.**
- - **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.**
+- **title** provide page title that will be used in navigation and HTML metadata.
+- **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.**
+- **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.**
+- **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.**
 - **layout** - predefined layout to use, see below. **This setting is not exported to the template engine.**
 
 
@@ -105,26 +109,26 @@ Scaladoc by default uses layout of files in `docs` directory to create table of
 
 ```yaml
 sidebar:
-    - title: Blog
-    - title: My title
-      page: my-page1.md
-    - page: my-page2.md
-    - page: my-page3/subsection
-    - title: Reference
-      subsection:
-        - page: my-page3.md
-    - index: my-page4/index.md
-      subsection:
-        - page: my-page4/my-page4.md
-    - title: My subsection
-      index: my-page5/index.md
-      subsection:
-        - page: my-page5/my-page5.md
-    - index: my-page6/index.md
-      subsection:
-        - index: my-page6/my-page6/index.md
-          subsection:
-            - page: my-page6/my-page6/my-page6.md
+  - title: Blog
+  - title: My title
+    page: my-page1.md
+  - page: my-page2.md
+  - page: my-page3/subsection
+  - title: Reference
+    subsection:
+      - page: my-page3.md
+  - index: my-page4/index.md
+    subsection:
+      - page: my-page4/my-page4.md
+  - title: My subsection
+    index: my-page5/index.md
+    subsection:
+      - page: my-page5/my-page5.md
+  - index: my-page6/index.md
+    subsection:
+      - index: my-page6/my-page6/index.md
+        subsection:
+          - page: my-page6/my-page6/my-page6.md
 ```
 
 The `sidebar` key is mandatory.
@@ -134,16 +138,14 @@ On each level, you can have three different types of entries: `page`, `blog` or
 - `title` (optional) - title of the page
 - `page` (mandatory) - path to the file that will represent the page, it can be either html or markdown file to be rendered, there is also the possibility to pass the `directory` path. If so, the scaladoc will render the directory and all its content as if there were no `sidebar.yml` basing on its tree structure and index files.
 
-The `page` property
-
-`subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are:
+The `page` property `subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are:
 - `title` (optional) - title of the page
 - `index` (optional) - path to the file that will represent the index file of the subsection, it can be either html or markdown file to be rendered
 - `subsection` (mandatory) - nested nodes, can be either pages or subsections
 
 In `subsection`s, you can omit `title` or `index`, however not specifying any of these properties prevents you from specifying the title of the section.
 
-`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here](blog.md).
+`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here]({% link _overviews/scala3-scaladoc/blog.md %}).
 
 ```
 ├── blog
@@ -198,5 +200,4 @@ For example, consider the following situation:
 You can refer to the assets from within any of the files using markdown links:
 
 ```
-This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)
-```
+This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)```
diff --git a/docs/docs/reference/changed-features/numeric-literals.md b/docs/docs/reference/changed-features/numeric-literals.md
deleted file mode 100644
index 7705410ce369..000000000000
--- a/docs/docs/reference/changed-features/numeric-literals.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: doc-page
-title: "Numeric Literals"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/numeric-literals.html
----
-
-[Document was moved](../experimental/numeric-literals.md)
\ No newline at end of file
diff --git a/docs/docs/reference/changed-features/type-checking.md b/docs/docs/reference/changed-features/type-checking.md
deleted file mode 100644
index 09a62698d4c7..000000000000
--- a/docs/docs/reference/changed-features/type-checking.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: doc-page
-title: "Changes in Type Checking"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/type-checking.html
----
-
-*** **TO BE FILLED IN** ***
diff --git a/docs/docs/reference/contextual/motivation.md b/docs/docs/reference/contextual/motivation.md
deleted file mode 100644
index 9a72ed5d1a5b..000000000000
--- a/docs/docs/reference/contextual/motivation.md
+++ /dev/null
@@ -1,83 +0,0 @@
----
-layout: doc-page
-title: "Overview"
-movedTo: https://docs.scala-lang.org/scala3/reference/contextual.html
----
-
-### Critique of the Status Quo
-
-Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them.
-
-Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g [Rust's traits](https://doc.rust-lang.org/rust-by-example/trait.html) or [Swift's protocol extensions](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID521). Design proposals are also on the table for Kotlin as [compile time dependency resolution](https://github.com/Kotlin/KEEP/blob/e863b25f8b3f2e9b9aaac361c6ee52be31453ee0/proposals/compile-time-dependency-resolution.md), for C# as [Shapes and Extensions](https://github.com/dotnet/csharplang/issues/164)
-or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as [Coq](https://coq.inria.fr/refman/language/extensions/implicit-arguments.html) or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html).
-
-Even though these designs use widely different terminology, they are all variants of the core idea of _term inference_. Given a type, the compiler synthesizes a "canonical" term that has that type. Scala embodies the idea in a purer form than most other languages: An implicit parameter directly leads to an inferred argument term that could also be written down explicitly. By contrast, type class based designs are less direct since they hide term inference behind some form of type classification and do not offer the option of writing the inferred quantities (typically, dictionaries) explicitly.
-
-Given that term inference is where the industry is heading, and given that Scala has it in a very pure form, how come implicits are not more popular? In fact, it's fair to say that implicits are at the same time Scala's most distinguished and most controversial feature. I believe this is due to a number of aspects that together make implicits harder to learn than necessary and also make it harder to prevent abuses.
-
-Particular criticisms are:
-
-1. Being very powerful, implicits are easily over-used and mis-used. This observation holds in almost all cases when we talk about _implicit conversions_, which, even though conceptually different, share the same syntax with other implicit definitions. For instance, regarding the two definitions
-
-    ```scala
-    implicit def i1(implicit x: T): C[T] = ...
-    implicit def i2(x: T): C[T] = ...
-    ```
-
-   the first of these is a conditional implicit _value_, the second an implicit _conversion_. Conditional implicit values are a cornerstone for expressing type classes, whereas most applications of implicit conversions have turned out to be of dubious value. The problem is that many newcomers to the language start with defining implicit conversions since they are easy to understand and seem powerful and convenient. Scala 3 will put under a language flag both definitions and applications of "undisciplined" implicit conversions between types defined elsewhere. This is a useful step to push back against overuse of implicit conversions. But the problem remains that syntactically, conversions and values just look too similar for comfort.
-
- 2. Another widespread abuse is over-reliance on implicit imports. This often leads to inscrutable type errors that go away with the right import incantation, leaving a feeling of frustration. Conversely, it is hard to see what implicits a program uses since implicits can hide anywhere in a long list of imports.
-
- 3. The syntax of implicit definitions is too minimal. It consists of a single modifier, `implicit`, that can be attached to a large number of language constructs. A problem with this for newcomers is that it conveys mechanism instead of intent. For instance, a type class instance is an implicit object or val if unconditional and an implicit def with implicit parameters referring to some class if conditional. This describes precisely what the implicit definitions translate to -- just drop the `implicit` modifier, and that's it! But the cues that define intent are rather indirect and can be easily misread, as demonstrated by the definitions of `i1` and `i2` above.
-
- 4. The syntax of implicit parameters also has shortcomings. While implicit _parameters_ are designated specifically, arguments are not. Passing an argument to an implicit parameter looks like a regular application `f(arg)`. This is problematic because it means there can be confusion regarding what parameter gets instantiated in a call. For instance, in
-
-    ```scala
-    def currentMap(implicit ctx: Context): Map[String, Int]
-    ```
-
-    one cannot write `currentMap("abc")` since the string `"abc"` is taken as explicit argument to the implicit `ctx` parameter. One has to write `currentMap.apply("abc")` instead, which is awkward and irregular. For the same reason, a method definition can only have one implicit parameter section and it must always come last. This restriction not only reduces orthogonality, but also prevents some useful program constructs, such as a method with a regular parameter whose type depends on an implicit value. Finally, it's also a bit annoying that implicit parameters must have a name, even though in many cases that name is never referenced.
-
- 5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but tools like [Scaladoc](https://docs.scala-lang.org/overviews/scaladoc/overview.html) that are based on static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Scala 3 compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
-
-None of the shortcomings is fatal, after all implicits are very widely used, and many libraries and applications rely on them. But together, they make code using implicits a lot more cumbersome and less clear than it could be.
-
-Historically, many of these shortcomings come from the way implicits were gradually "discovered" in Scala. Scala originally had only implicit conversions with the intended use case of "extending" a class or trait after it was defined, i.e. what is expressed by implicit classes in later versions of Scala. Implicit parameters and instance definitions came later in 2006 and we picked similar syntax since it seemed convenient. For the same reason, no effort was made to distinguish implicit imports or arguments from normal ones.
-
-Existing Scala programmers by and large have gotten used to the status quo and see little need for change. But for newcomers this status quo presents a big hurdle. I believe if we want to overcome that hurdle, we should take a step back and allow ourselves to consider a radically new design.
-
-### The New Design
-
-The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes:
-
- 1. [Given Instances](./givens.md) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
-
- 2. [Using Clauses](./using-clauses.md) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition.
-
- 3. ["Given" Imports](./given-imports.md) are a new class of import selectors that specifically import
-    givens and nothing else.
-
- 4. [Implicit Conversions](./conversions.md) are now expressed as given instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out.
-
-This section also contains pages describing other language features that are related to context abstraction. These are:
-
- - [Context Bounds](./context-bounds.md), which carry over unchanged.
- - [Extension Methods](./extension-methods.md) replace implicit classes in a way that integrates better with type classes.
- - [Implementing Type Classes](type-classes.md) demonstrates how some common type classes can be implemented using the new constructs.
- - [Type Class Derivation](./derivation.md) introduces constructs to automatically derive type class instances for ADTs.
- - [Multiversal Equality](./multiversal-equality.md) introduces a special type class to support type safe equality.
- - [Context Functions](./context-functions.md) provide a way to abstract over context parameters.
- - [By-Name Context Parameters](./by-name-context-parameters.md) are an essential tool to define recursive synthesized values without looping.
- - [Relationship with Scala 2 Implicits](./relationship-implicits.md) discusses the relationship between old-style implicits and new-style givens and how to migrate from one to the other.
-
-Overall, the new design achieves a better separation of term inference from the rest of the language: There is a single way to define givens instead of a multitude of forms all taking an `implicit` modifier. There is a single way to introduce implicit parameters and arguments instead of conflating implicit with normal arguments. There is a separate way to import givens that does not allow them to hide in a sea of normal imports. And there is a single way to define an implicit conversion which is clearly marked as such and does not require special syntax.
-
-This design thus avoids feature interactions and makes the language more consistent and orthogonal. It will make implicits easier to learn and harder to abuse. It will greatly improve the clarity of the 95% of Scala programs that use implicits. It has thus the potential to fulfil the promise of term inference in a principled way that is also accessible and friendly.
-
-Could we achieve the same goals by tweaking existing implicits? After having tried for a long time, I believe now that this is impossible.
-
- - First, some of the problems are clearly syntactic and require different syntax to solve them.
- - Second, there is the problem how to migrate. We cannot change the rules in mid-flight. At some stage of language evolution we need to accommodate both the new and the old rules. With a syntax change, this is easy: Introduce the new syntax with new rules, support the old syntax for a while to facilitate cross compilation, deprecate and phase out the old syntax at some later time. Keeping the same syntax does not offer this path, and in fact does not seem to offer any viable path for evolution
- - Third, even if we would somehow succeed with migration, we still have the problem
- how to teach this. We cannot make existing tutorials go away. Almost all existing tutorials start with implicit conversions, which will go away; they use normal imports, which will go away, and they explain calls to methods with implicit parameters by expanding them to plain applications, which will also go away. This means that we'd have
- to add modifications and qualifications to all existing literature and courseware, likely causing more confusion with beginners instead of less. By contrast, with a new syntax there is a clear criterion: Any book or courseware that mentions `implicit` is outdated and should be updated.
diff --git a/docs/docs/usage/scaladoc/index.md b/docs/docs/usage/scaladoc/index.md
deleted file mode 100644
index ef0db90daebf..000000000000
--- a/docs/docs/usage/scaladoc/index.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-title: scaladoc
----
-
-![scaladoc logo](/images/scaladoc-logo.png)
-
-scaladoc is a tool to generate documentation for your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`.
-
-As you probably have guessed, this whole site was created using scaladoc.
-
-
-{% for post in site.posts %}
-## [{{ post.title }}](/{{ post.url }})
-
-{{ post.excerpt }}
-
-[ (read more) ](/{{ post.url }})
-
-{% endfor %}
-
-## Other extensions
-
-We would love to have your feedback on what you think would be good in order to
-render the documentation you want! Perhaps you would like to render method
-definitions or members? Do you want to have runnable code snippets? Let us know
-by filing [issues](https://github.com/lampepfl/dotty/issues/new)!
diff --git a/project/scripts/processDocs.sc b/project/scripts/processDocs.sc
new file mode 100644
index 000000000000..28c52431e6b9
--- /dev/null
+++ b/project/scripts/processDocs.sc
@@ -0,0 +1,49 @@
+import java.nio.file.{ FileSystems, Files, Path }
+import java.io.PrintStream
+import scala.io.{ Codec, Source }
+import scala.collection.JavaConverters._
+
+val inputDir = FileSystems.getDefault.getPath("docs-for-scalalang")
+val outputDir = FileSystems.getDefault.getPath("docs")
+
+def copyFile(path: Path): Unit =
+  val inputStream = Source.fromFile(path.toFile)(Codec.UTF8)
+  val fileContent = inputStream.getLines().mkString("\n")
+
+  val newPath = outputDir.resolve(inputDir.relativize(path))
+  Files.createDirectories(newPath.getParent())
+
+  new PrintStream(newPath.toFile):
+
+    val titlePattern = "(?s)^---\n.*title: (\".*\").*---"
+    val reference = raw".*/reference/.*".r
+    val usageScaladoc = raw".*/usage/scaladoc/.*".r
+    val transformed = newPath.toString match
+      case reference(_*) => fileContent.replaceAll(
+          titlePattern,
+          s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/contextual/${newPath.getFileName.toString.stripSuffix(".md")}.html\n---"
+        )
+      case usageScaladoc(_*) => fileContent.replaceAll(
+          titlePattern,
+          s"---\ntitle: $$1\n---"
+        )
+      case _ =>
+        fileContent
+
+
+    val jekyllLinkPattern = """\(\{\% link _scala3-reference(.*) %\}\)"""
+    val jekyllLinkSubstitution = "(..$1)"
+    val localLinkPattern = """\((?!http|www)(.*).html\)"""
+    val localLinkSubstitution = "($1.md)"
+    val transformedWithLinks = transformed.replaceAll(
+      jekyllLinkPattern,
+      jekyllLinkSubstitution
+    ).replaceAll(
+      localLinkPattern,
+      localLinkSubstitution
+    )
+
+    write(transformedWithLinks.getBytes("UTF8"))
+
+def main(args: Array[String]): Unit =
+  Files.walk(inputDir).iterator().asScala.filter(Files.isRegularFile(_)).foreach(copyFile)

From 633d3bf1442d2c1e9d0805f1895f1f1365858af9 Mon Sep 17 00:00:00 2001
From: Andrzej Ratajczak <andrzej.ratajczak98@gmail.com>
Date: Thu, 23 Sep 2021 12:44:44 +0200
Subject: [PATCH 2/4] Rewrite script to have all docs in docs/

---
 docs/README.md                                |  5 ++
 .../docs/reference/changed-features.md        |  0
 .../changed-features/compiler-plugins.md      |  0
 .../changed-features/eta-expansion-spec.md    |  0
 .../changed-features/eta-expansion.md         |  0
 .../implicit-conversions-spec.md              |  0
 .../changed-features/implicit-conversions.md  |  0
 .../changed-features/implicit-resolution.md   |  0
 .../reference/changed-features/imports.md     |  0
 .../changed-features/interpolation-escapes.md |  0
 .../changed-features/lazy-vals-init.md        |  0
 .../changed-features/main-functions.md        |  0
 .../changed-features/match-syntax.md          |  0
 .../changed-features/numeric-literals.md      |  0
 .../reference/changed-features/operators.md   |  0
 .../changed-features/overload-resolution.md   |  0
 .../changed-features/pattern-bindings.md      |  0
 .../changed-features/pattern-matching.md      |  0
 .../changed-features/structural-types-spec.md |  0
 .../changed-features/structural-types.md      |  0
 .../changed-features/type-checking.md         |  0
 .../changed-features/type-inference.md        |  0
 .../changed-features/vararg-splices.md        |  0
 .../reference/changed-features/wildcards.md   |  0
 .../docs/reference/contextual.md              |  0
 .../contextual/by-name-context-parameters.md  |  0
 .../reference/contextual/context-bounds.md    |  0
 .../contextual/context-functions-spec.md      |  0
 .../reference/contextual/context-functions.md |  0
 .../docs/reference/contextual/conversions.md  |  0
 .../reference/contextual/derivation-macro.md  |  0
 .../docs/reference/contextual/derivation.md   |  0
 .../reference/contextual/extension-methods.md |  0
 .../reference/contextual/given-imports.md     |  0
 .../docs/reference/contextual/givens.md       |  0
 .../contextual/multiversal-equality.md        |  0
 .../contextual/relationship-implicits.md      |  0
 .../right-associative-extension-methods.md    |  0
 .../docs/reference/contextual/type-classes.md |  0
 .../reference/contextual/using-clauses.md     |  0
 .../docs/reference/dropped-features.md        |  0
 .../reference/dropped-features/auto-apply.md  |  0
 .../dropped-features/class-shadowing-spec.md  |  0
 .../dropped-features/class-shadowing.md       |  0
 .../dropped-features/delayed-init.md          |  0
 .../reference/dropped-features/do-while.md    |  0
 .../dropped-features/early-initializers.md    |  0
 .../dropped-features/existential-types.md     |  0
 .../reference/dropped-features/limit22.md     |  0
 .../docs/reference/dropped-features/macros.md |  0
 .../dropped-features/nonlocal-returns.md      |  0
 .../dropped-features/package-objects.md       |  0
 .../dropped-features/procedure-syntax.md      |  0
 .../reference/dropped-features/symlits.md     |  0
 .../dropped-features/this-qualifier.md        |  0
 .../dropped-features/type-projection.md       |  0
 .../dropped-features/weak-conformance-spec.md |  0
 .../dropped-features/weak-conformance.md      |  0
 .../dropped-features/wildcard-init.md         |  0
 .../docs/reference/dropped-features/xml.md    |  0
 .../docs/reference/enums.md                   |  0
 .../docs/reference/enums/adts.md              |  0
 .../docs/reference/enums/desugarEnums.md      |  0
 .../docs/reference/enums/enums.md             |  0
 .../docs/reference/experimental/canthrow.md   |  2 +-
 .../experimental/erased-defs-spec.md          |  0
 .../reference/experimental/erased-defs.md     |  0
 .../experimental/named-typeargs-spec.md       |  0
 .../reference/experimental/named-typeargs.md  |  0
 .../experimental/numeric-literals.md          |  0
 .../docs/reference/experimental/overview.md   |  2 +-
 .../docs/reference/features-classification.md |  0
 .../docs/reference/language-versions.md       |  0
 .../docs/reference/metaprogramming.md         |  0
 .../metaprogramming/compiletime-ops.md        |  0
 .../docs/reference/metaprogramming/inline.md  |  0
 .../reference/metaprogramming/macros-spec.md  |  0
 .../docs/reference/metaprogramming/macros.md  |  0
 .../reference/metaprogramming/reflection.md   |  0
 .../reference/metaprogramming/simple-smp.md   |  0
 .../docs/reference/metaprogramming/staging.md |  0
 .../metaprogramming/tasty-inspect.md          |  0
 .../docs/reference/new-types.md               |  0
 .../dependent-function-types-spec.md          |  0
 .../new-types/dependent-function-types.md     |  0
 .../new-types/intersection-types-spec.md      |  0
 .../reference/new-types/intersection-types.md |  0
 .../docs/reference/new-types/match-types.md   |  0
 .../new-types/polymorphic-function-types.md   |  0
 .../reference/new-types/type-lambdas-spec.md  |  0
 .../docs/reference/new-types/type-lambdas.md  |  0
 .../reference/new-types/union-types-spec.md   |  0
 .../docs/reference/new-types/union-types.md   |  0
 .../docs/reference/other-new-features.md      |  0
 .../other-new-features/control-syntax.md      |  0
 .../creator-applications.md                   |  0
 .../other-new-features/experimental-defs.md   |  0
 .../other-new-features/explicit-nulls.md      |  0
 .../reference/other-new-features/export.md    |  0
 .../indentation-experimental.md               |  0
 .../other-new-features/indentation.md         |  0
 .../other-new-features/kind-polymorphism.md   |  0
 .../reference/other-new-features/matchable.md |  0
 .../other-new-features/named-typeargs.md      |  0
 .../other-new-features/opaques-details.md     |  0
 .../reference/other-new-features/opaques.md   |  0
 .../other-new-features/open-classes.md        |  0
 .../parameter-untupling-spec.md               |  0
 .../other-new-features/parameter-untupling.md |  0
 .../other-new-features/safe-initialization.md |  0
 .../other-new-features/targetName.md          |  0
 .../threadUnsafe-annotation.md                |  0
 .../other-new-features/trait-parameters.md    |  0
 .../other-new-features/transparent-traits.md  |  0
 .../reference/other-new-features/type-test.md |  0
 .../docs/reference/overview.md                |  0
 .../docs/reference/soft-modifier.md           |  0
 .../docs/reference/syntax.md                  |  0
 docs/docs/usage/language-versions.md          | 35 --------
 .../docs/usage/scaladoc/blog.md               |  0
 .../docs/usage/scaladoc/docstrings.md         |  0
 .../docs/usage/scaladoc/index.md              |  0
 .../docs/usage/scaladoc/linking.md            |  0
 .../docs/usage/scaladoc/search-engine.md      |  0
 .../docs/usage/scaladoc/settings.md           |  0
 .../docs/usage/scaladoc/site-versioning.md    |  0
 .../docs/usage/scaladoc/static-site.md        |  0
 docs/sidebar.yml                              | 12 ++-
 project/Build.scala                           |  2 +-
 project/scripts/processDocs.sc                | 82 ++++++++++---------
 130 files changed, 62 insertions(+), 78 deletions(-)
 create mode 100644 docs/README.md
 rename {docs-for-scalalang => docs}/docs/reference/changed-features.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/compiler-plugins.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/eta-expansion-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/eta-expansion.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/implicit-conversions-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/implicit-conversions.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/implicit-resolution.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/imports.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/interpolation-escapes.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/lazy-vals-init.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/main-functions.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/match-syntax.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/numeric-literals.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/operators.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/overload-resolution.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/pattern-bindings.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/pattern-matching.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/structural-types-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/structural-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/type-checking.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/type-inference.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/vararg-splices.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/changed-features/wildcards.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/by-name-context-parameters.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/context-bounds.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/context-functions-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/context-functions.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/conversions.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/derivation-macro.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/derivation.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/extension-methods.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/given-imports.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/givens.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/multiversal-equality.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/relationship-implicits.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/right-associative-extension-methods.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/type-classes.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/contextual/using-clauses.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/auto-apply.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/class-shadowing-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/class-shadowing.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/delayed-init.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/do-while.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/early-initializers.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/existential-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/limit22.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/macros.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/nonlocal-returns.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/package-objects.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/procedure-syntax.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/symlits.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/this-qualifier.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/type-projection.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/weak-conformance-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/weak-conformance.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/wildcard-init.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/dropped-features/xml.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/enums.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/enums/adts.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/enums/desugarEnums.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/enums/enums.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/canthrow.md (99%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/erased-defs-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/erased-defs.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/named-typeargs-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/named-typeargs.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/numeric-literals.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/experimental/overview.md (95%)
 rename {docs-for-scalalang => docs}/docs/reference/features-classification.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/language-versions.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/compiletime-ops.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/inline.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/macros-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/macros.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/reflection.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/simple-smp.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/staging.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/metaprogramming/tasty-inspect.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/dependent-function-types-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/dependent-function-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/intersection-types-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/intersection-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/match-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/polymorphic-function-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/type-lambdas-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/type-lambdas.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/union-types-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/new-types/union-types.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/control-syntax.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/creator-applications.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/experimental-defs.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/explicit-nulls.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/export.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/indentation-experimental.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/indentation.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/kind-polymorphism.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/matchable.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/named-typeargs.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/opaques-details.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/opaques.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/open-classes.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/parameter-untupling-spec.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/parameter-untupling.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/safe-initialization.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/targetName.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/threadUnsafe-annotation.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/trait-parameters.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/transparent-traits.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/other-new-features/type-test.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/overview.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/soft-modifier.md (100%)
 rename {docs-for-scalalang => docs}/docs/reference/syntax.md (100%)
 delete mode 100644 docs/docs/usage/language-versions.md
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/blog.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/docstrings.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/index.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/linking.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/search-engine.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/settings.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/site-versioning.md (100%)
 rename {docs-for-scalalang => docs}/docs/usage/scaladoc/static-site.md (100%)

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000000..eaa0a02b9ce6
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,5 @@
+This directory is for keeping all the compiler related docs.
+
+For serving this files, one should notice that files under `docs/docs/reference` and `docs/docs/usage/scaladoc` are designed to be compatible with `docs.scala-lang` jekyll page.
+If one wants to generate static site with these files, should firstly run the script from `project/scripts/processDocs.sc`, for example with:
+`bin/scala project/scripts/processDocs.sc` and then using sbt task `sbt scaladoc/generateScalaDocumentation` generate the whole scaladoc for dotty.
diff --git a/docs-for-scalalang/docs/reference/changed-features.md b/docs/docs/reference/changed-features.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features.md
rename to docs/docs/reference/changed-features.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/compiler-plugins.md b/docs/docs/reference/changed-features/compiler-plugins.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/compiler-plugins.md
rename to docs/docs/reference/changed-features/compiler-plugins.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/eta-expansion-spec.md b/docs/docs/reference/changed-features/eta-expansion-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/eta-expansion-spec.md
rename to docs/docs/reference/changed-features/eta-expansion-spec.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/eta-expansion.md b/docs/docs/reference/changed-features/eta-expansion.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/eta-expansion.md
rename to docs/docs/reference/changed-features/eta-expansion.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/implicit-conversions-spec.md b/docs/docs/reference/changed-features/implicit-conversions-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/implicit-conversions-spec.md
rename to docs/docs/reference/changed-features/implicit-conversions-spec.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/implicit-conversions.md b/docs/docs/reference/changed-features/implicit-conversions.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/implicit-conversions.md
rename to docs/docs/reference/changed-features/implicit-conversions.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/implicit-resolution.md b/docs/docs/reference/changed-features/implicit-resolution.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/implicit-resolution.md
rename to docs/docs/reference/changed-features/implicit-resolution.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/imports.md b/docs/docs/reference/changed-features/imports.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/imports.md
rename to docs/docs/reference/changed-features/imports.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/interpolation-escapes.md b/docs/docs/reference/changed-features/interpolation-escapes.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/interpolation-escapes.md
rename to docs/docs/reference/changed-features/interpolation-escapes.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/lazy-vals-init.md b/docs/docs/reference/changed-features/lazy-vals-init.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/lazy-vals-init.md
rename to docs/docs/reference/changed-features/lazy-vals-init.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/main-functions.md b/docs/docs/reference/changed-features/main-functions.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/main-functions.md
rename to docs/docs/reference/changed-features/main-functions.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/match-syntax.md b/docs/docs/reference/changed-features/match-syntax.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/match-syntax.md
rename to docs/docs/reference/changed-features/match-syntax.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/numeric-literals.md b/docs/docs/reference/changed-features/numeric-literals.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/numeric-literals.md
rename to docs/docs/reference/changed-features/numeric-literals.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/operators.md b/docs/docs/reference/changed-features/operators.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/operators.md
rename to docs/docs/reference/changed-features/operators.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/overload-resolution.md b/docs/docs/reference/changed-features/overload-resolution.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/overload-resolution.md
rename to docs/docs/reference/changed-features/overload-resolution.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/pattern-bindings.md b/docs/docs/reference/changed-features/pattern-bindings.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/pattern-bindings.md
rename to docs/docs/reference/changed-features/pattern-bindings.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/pattern-matching.md b/docs/docs/reference/changed-features/pattern-matching.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/pattern-matching.md
rename to docs/docs/reference/changed-features/pattern-matching.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/structural-types-spec.md b/docs/docs/reference/changed-features/structural-types-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/structural-types-spec.md
rename to docs/docs/reference/changed-features/structural-types-spec.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/structural-types.md b/docs/docs/reference/changed-features/structural-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/structural-types.md
rename to docs/docs/reference/changed-features/structural-types.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/type-checking.md b/docs/docs/reference/changed-features/type-checking.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/type-checking.md
rename to docs/docs/reference/changed-features/type-checking.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/type-inference.md b/docs/docs/reference/changed-features/type-inference.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/type-inference.md
rename to docs/docs/reference/changed-features/type-inference.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/vararg-splices.md b/docs/docs/reference/changed-features/vararg-splices.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/vararg-splices.md
rename to docs/docs/reference/changed-features/vararg-splices.md
diff --git a/docs-for-scalalang/docs/reference/changed-features/wildcards.md b/docs/docs/reference/changed-features/wildcards.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/changed-features/wildcards.md
rename to docs/docs/reference/changed-features/wildcards.md
diff --git a/docs-for-scalalang/docs/reference/contextual.md b/docs/docs/reference/contextual.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual.md
rename to docs/docs/reference/contextual.md
diff --git a/docs-for-scalalang/docs/reference/contextual/by-name-context-parameters.md b/docs/docs/reference/contextual/by-name-context-parameters.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/by-name-context-parameters.md
rename to docs/docs/reference/contextual/by-name-context-parameters.md
diff --git a/docs-for-scalalang/docs/reference/contextual/context-bounds.md b/docs/docs/reference/contextual/context-bounds.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/context-bounds.md
rename to docs/docs/reference/contextual/context-bounds.md
diff --git a/docs-for-scalalang/docs/reference/contextual/context-functions-spec.md b/docs/docs/reference/contextual/context-functions-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/context-functions-spec.md
rename to docs/docs/reference/contextual/context-functions-spec.md
diff --git a/docs-for-scalalang/docs/reference/contextual/context-functions.md b/docs/docs/reference/contextual/context-functions.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/context-functions.md
rename to docs/docs/reference/contextual/context-functions.md
diff --git a/docs-for-scalalang/docs/reference/contextual/conversions.md b/docs/docs/reference/contextual/conversions.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/conversions.md
rename to docs/docs/reference/contextual/conversions.md
diff --git a/docs-for-scalalang/docs/reference/contextual/derivation-macro.md b/docs/docs/reference/contextual/derivation-macro.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/derivation-macro.md
rename to docs/docs/reference/contextual/derivation-macro.md
diff --git a/docs-for-scalalang/docs/reference/contextual/derivation.md b/docs/docs/reference/contextual/derivation.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/derivation.md
rename to docs/docs/reference/contextual/derivation.md
diff --git a/docs-for-scalalang/docs/reference/contextual/extension-methods.md b/docs/docs/reference/contextual/extension-methods.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/extension-methods.md
rename to docs/docs/reference/contextual/extension-methods.md
diff --git a/docs-for-scalalang/docs/reference/contextual/given-imports.md b/docs/docs/reference/contextual/given-imports.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/given-imports.md
rename to docs/docs/reference/contextual/given-imports.md
diff --git a/docs-for-scalalang/docs/reference/contextual/givens.md b/docs/docs/reference/contextual/givens.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/givens.md
rename to docs/docs/reference/contextual/givens.md
diff --git a/docs-for-scalalang/docs/reference/contextual/multiversal-equality.md b/docs/docs/reference/contextual/multiversal-equality.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/multiversal-equality.md
rename to docs/docs/reference/contextual/multiversal-equality.md
diff --git a/docs-for-scalalang/docs/reference/contextual/relationship-implicits.md b/docs/docs/reference/contextual/relationship-implicits.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/relationship-implicits.md
rename to docs/docs/reference/contextual/relationship-implicits.md
diff --git a/docs-for-scalalang/docs/reference/contextual/right-associative-extension-methods.md b/docs/docs/reference/contextual/right-associative-extension-methods.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/right-associative-extension-methods.md
rename to docs/docs/reference/contextual/right-associative-extension-methods.md
diff --git a/docs-for-scalalang/docs/reference/contextual/type-classes.md b/docs/docs/reference/contextual/type-classes.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/type-classes.md
rename to docs/docs/reference/contextual/type-classes.md
diff --git a/docs-for-scalalang/docs/reference/contextual/using-clauses.md b/docs/docs/reference/contextual/using-clauses.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/contextual/using-clauses.md
rename to docs/docs/reference/contextual/using-clauses.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features.md b/docs/docs/reference/dropped-features.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features.md
rename to docs/docs/reference/dropped-features.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/auto-apply.md b/docs/docs/reference/dropped-features/auto-apply.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/auto-apply.md
rename to docs/docs/reference/dropped-features/auto-apply.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/class-shadowing-spec.md b/docs/docs/reference/dropped-features/class-shadowing-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/class-shadowing-spec.md
rename to docs/docs/reference/dropped-features/class-shadowing-spec.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/class-shadowing.md b/docs/docs/reference/dropped-features/class-shadowing.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/class-shadowing.md
rename to docs/docs/reference/dropped-features/class-shadowing.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/delayed-init.md b/docs/docs/reference/dropped-features/delayed-init.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/delayed-init.md
rename to docs/docs/reference/dropped-features/delayed-init.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/do-while.md b/docs/docs/reference/dropped-features/do-while.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/do-while.md
rename to docs/docs/reference/dropped-features/do-while.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/early-initializers.md b/docs/docs/reference/dropped-features/early-initializers.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/early-initializers.md
rename to docs/docs/reference/dropped-features/early-initializers.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/existential-types.md b/docs/docs/reference/dropped-features/existential-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/existential-types.md
rename to docs/docs/reference/dropped-features/existential-types.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/limit22.md b/docs/docs/reference/dropped-features/limit22.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/limit22.md
rename to docs/docs/reference/dropped-features/limit22.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/macros.md b/docs/docs/reference/dropped-features/macros.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/macros.md
rename to docs/docs/reference/dropped-features/macros.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/nonlocal-returns.md b/docs/docs/reference/dropped-features/nonlocal-returns.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/nonlocal-returns.md
rename to docs/docs/reference/dropped-features/nonlocal-returns.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/package-objects.md b/docs/docs/reference/dropped-features/package-objects.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/package-objects.md
rename to docs/docs/reference/dropped-features/package-objects.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/procedure-syntax.md b/docs/docs/reference/dropped-features/procedure-syntax.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/procedure-syntax.md
rename to docs/docs/reference/dropped-features/procedure-syntax.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/symlits.md b/docs/docs/reference/dropped-features/symlits.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/symlits.md
rename to docs/docs/reference/dropped-features/symlits.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/this-qualifier.md b/docs/docs/reference/dropped-features/this-qualifier.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/this-qualifier.md
rename to docs/docs/reference/dropped-features/this-qualifier.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/type-projection.md b/docs/docs/reference/dropped-features/type-projection.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/type-projection.md
rename to docs/docs/reference/dropped-features/type-projection.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/weak-conformance-spec.md b/docs/docs/reference/dropped-features/weak-conformance-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/weak-conformance-spec.md
rename to docs/docs/reference/dropped-features/weak-conformance-spec.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/weak-conformance.md b/docs/docs/reference/dropped-features/weak-conformance.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/weak-conformance.md
rename to docs/docs/reference/dropped-features/weak-conformance.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/wildcard-init.md b/docs/docs/reference/dropped-features/wildcard-init.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/wildcard-init.md
rename to docs/docs/reference/dropped-features/wildcard-init.md
diff --git a/docs-for-scalalang/docs/reference/dropped-features/xml.md b/docs/docs/reference/dropped-features/xml.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/dropped-features/xml.md
rename to docs/docs/reference/dropped-features/xml.md
diff --git a/docs-for-scalalang/docs/reference/enums.md b/docs/docs/reference/enums.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/enums.md
rename to docs/docs/reference/enums.md
diff --git a/docs-for-scalalang/docs/reference/enums/adts.md b/docs/docs/reference/enums/adts.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/enums/adts.md
rename to docs/docs/reference/enums/adts.md
diff --git a/docs-for-scalalang/docs/reference/enums/desugarEnums.md b/docs/docs/reference/enums/desugarEnums.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/enums/desugarEnums.md
rename to docs/docs/reference/enums/desugarEnums.md
diff --git a/docs-for-scalalang/docs/reference/enums/enums.md b/docs/docs/reference/enums/enums.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/enums/enums.md
rename to docs/docs/reference/enums/enums.md
diff --git a/docs-for-scalalang/docs/reference/experimental/canthrow.md b/docs/docs/reference/experimental/canthrow.md
similarity index 99%
rename from docs-for-scalalang/docs/reference/experimental/canthrow.md
rename to docs/docs/reference/experimental/canthrow.md
index 88fa77d785a4..8233627bf27b 100644
--- a/docs-for-scalalang/docs/reference/experimental/canthrow.md
+++ b/docs/docs/reference/experimental/canthrow.md
@@ -1,7 +1,7 @@
 ---
 layout: singlepage-overview
 scala3: true
-title: CanThrow Abilities
+title: "CanThrow Abilities"
 author: Martin Odersky
 ---
 
diff --git a/docs-for-scalalang/docs/reference/experimental/erased-defs-spec.md b/docs/docs/reference/experimental/erased-defs-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/experimental/erased-defs-spec.md
rename to docs/docs/reference/experimental/erased-defs-spec.md
diff --git a/docs-for-scalalang/docs/reference/experimental/erased-defs.md b/docs/docs/reference/experimental/erased-defs.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/experimental/erased-defs.md
rename to docs/docs/reference/experimental/erased-defs.md
diff --git a/docs-for-scalalang/docs/reference/experimental/named-typeargs-spec.md b/docs/docs/reference/experimental/named-typeargs-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/experimental/named-typeargs-spec.md
rename to docs/docs/reference/experimental/named-typeargs-spec.md
diff --git a/docs-for-scalalang/docs/reference/experimental/named-typeargs.md b/docs/docs/reference/experimental/named-typeargs.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/experimental/named-typeargs.md
rename to docs/docs/reference/experimental/named-typeargs.md
diff --git a/docs-for-scalalang/docs/reference/experimental/numeric-literals.md b/docs/docs/reference/experimental/numeric-literals.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/experimental/numeric-literals.md
rename to docs/docs/reference/experimental/numeric-literals.md
diff --git a/docs-for-scalalang/docs/reference/experimental/overview.md b/docs/docs/reference/experimental/overview.md
similarity index 95%
rename from docs-for-scalalang/docs/reference/experimental/overview.md
rename to docs/docs/reference/experimental/overview.md
index 3a81c8e8bfe9..bd2cda02d79a 100644
--- a/docs-for-scalalang/docs/reference/experimental/overview.md
+++ b/docs/docs/reference/experimental/overview.md
@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: Experimental language features
+title: "Experimental language features"
 author: Nicolas Stucki
 ---
 
diff --git a/docs-for-scalalang/docs/reference/features-classification.md b/docs/docs/reference/features-classification.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/features-classification.md
rename to docs/docs/reference/features-classification.md
diff --git a/docs-for-scalalang/docs/reference/language-versions.md b/docs/docs/reference/language-versions.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/language-versions.md
rename to docs/docs/reference/language-versions.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming.md b/docs/docs/reference/metaprogramming.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming.md
rename to docs/docs/reference/metaprogramming.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/compiletime-ops.md b/docs/docs/reference/metaprogramming/compiletime-ops.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/compiletime-ops.md
rename to docs/docs/reference/metaprogramming/compiletime-ops.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/inline.md b/docs/docs/reference/metaprogramming/inline.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/inline.md
rename to docs/docs/reference/metaprogramming/inline.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/macros-spec.md b/docs/docs/reference/metaprogramming/macros-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/macros-spec.md
rename to docs/docs/reference/metaprogramming/macros-spec.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/macros.md b/docs/docs/reference/metaprogramming/macros.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/macros.md
rename to docs/docs/reference/metaprogramming/macros.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/reflection.md b/docs/docs/reference/metaprogramming/reflection.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/reflection.md
rename to docs/docs/reference/metaprogramming/reflection.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/simple-smp.md b/docs/docs/reference/metaprogramming/simple-smp.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/simple-smp.md
rename to docs/docs/reference/metaprogramming/simple-smp.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/staging.md
rename to docs/docs/reference/metaprogramming/staging.md
diff --git a/docs-for-scalalang/docs/reference/metaprogramming/tasty-inspect.md b/docs/docs/reference/metaprogramming/tasty-inspect.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/metaprogramming/tasty-inspect.md
rename to docs/docs/reference/metaprogramming/tasty-inspect.md
diff --git a/docs-for-scalalang/docs/reference/new-types.md b/docs/docs/reference/new-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types.md
rename to docs/docs/reference/new-types.md
diff --git a/docs-for-scalalang/docs/reference/new-types/dependent-function-types-spec.md b/docs/docs/reference/new-types/dependent-function-types-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/dependent-function-types-spec.md
rename to docs/docs/reference/new-types/dependent-function-types-spec.md
diff --git a/docs-for-scalalang/docs/reference/new-types/dependent-function-types.md b/docs/docs/reference/new-types/dependent-function-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/dependent-function-types.md
rename to docs/docs/reference/new-types/dependent-function-types.md
diff --git a/docs-for-scalalang/docs/reference/new-types/intersection-types-spec.md b/docs/docs/reference/new-types/intersection-types-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/intersection-types-spec.md
rename to docs/docs/reference/new-types/intersection-types-spec.md
diff --git a/docs-for-scalalang/docs/reference/new-types/intersection-types.md b/docs/docs/reference/new-types/intersection-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/intersection-types.md
rename to docs/docs/reference/new-types/intersection-types.md
diff --git a/docs-for-scalalang/docs/reference/new-types/match-types.md b/docs/docs/reference/new-types/match-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/match-types.md
rename to docs/docs/reference/new-types/match-types.md
diff --git a/docs-for-scalalang/docs/reference/new-types/polymorphic-function-types.md b/docs/docs/reference/new-types/polymorphic-function-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/polymorphic-function-types.md
rename to docs/docs/reference/new-types/polymorphic-function-types.md
diff --git a/docs-for-scalalang/docs/reference/new-types/type-lambdas-spec.md b/docs/docs/reference/new-types/type-lambdas-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/type-lambdas-spec.md
rename to docs/docs/reference/new-types/type-lambdas-spec.md
diff --git a/docs-for-scalalang/docs/reference/new-types/type-lambdas.md b/docs/docs/reference/new-types/type-lambdas.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/type-lambdas.md
rename to docs/docs/reference/new-types/type-lambdas.md
diff --git a/docs-for-scalalang/docs/reference/new-types/union-types-spec.md b/docs/docs/reference/new-types/union-types-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/union-types-spec.md
rename to docs/docs/reference/new-types/union-types-spec.md
diff --git a/docs-for-scalalang/docs/reference/new-types/union-types.md b/docs/docs/reference/new-types/union-types.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/new-types/union-types.md
rename to docs/docs/reference/new-types/union-types.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features.md b/docs/docs/reference/other-new-features.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features.md
rename to docs/docs/reference/other-new-features.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/control-syntax.md b/docs/docs/reference/other-new-features/control-syntax.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/control-syntax.md
rename to docs/docs/reference/other-new-features/control-syntax.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/creator-applications.md b/docs/docs/reference/other-new-features/creator-applications.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/creator-applications.md
rename to docs/docs/reference/other-new-features/creator-applications.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/experimental-defs.md b/docs/docs/reference/other-new-features/experimental-defs.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/experimental-defs.md
rename to docs/docs/reference/other-new-features/experimental-defs.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/explicit-nulls.md b/docs/docs/reference/other-new-features/explicit-nulls.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/explicit-nulls.md
rename to docs/docs/reference/other-new-features/explicit-nulls.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/export.md b/docs/docs/reference/other-new-features/export.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/export.md
rename to docs/docs/reference/other-new-features/export.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/indentation-experimental.md b/docs/docs/reference/other-new-features/indentation-experimental.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/indentation-experimental.md
rename to docs/docs/reference/other-new-features/indentation-experimental.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/indentation.md b/docs/docs/reference/other-new-features/indentation.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/indentation.md
rename to docs/docs/reference/other-new-features/indentation.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/kind-polymorphism.md b/docs/docs/reference/other-new-features/kind-polymorphism.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/kind-polymorphism.md
rename to docs/docs/reference/other-new-features/kind-polymorphism.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/matchable.md b/docs/docs/reference/other-new-features/matchable.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/matchable.md
rename to docs/docs/reference/other-new-features/matchable.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/named-typeargs.md b/docs/docs/reference/other-new-features/named-typeargs.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/named-typeargs.md
rename to docs/docs/reference/other-new-features/named-typeargs.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/opaques-details.md b/docs/docs/reference/other-new-features/opaques-details.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/opaques-details.md
rename to docs/docs/reference/other-new-features/opaques-details.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/opaques.md b/docs/docs/reference/other-new-features/opaques.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/opaques.md
rename to docs/docs/reference/other-new-features/opaques.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/open-classes.md b/docs/docs/reference/other-new-features/open-classes.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/open-classes.md
rename to docs/docs/reference/other-new-features/open-classes.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/parameter-untupling-spec.md b/docs/docs/reference/other-new-features/parameter-untupling-spec.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/parameter-untupling-spec.md
rename to docs/docs/reference/other-new-features/parameter-untupling-spec.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/parameter-untupling.md b/docs/docs/reference/other-new-features/parameter-untupling.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/parameter-untupling.md
rename to docs/docs/reference/other-new-features/parameter-untupling.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/safe-initialization.md b/docs/docs/reference/other-new-features/safe-initialization.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/safe-initialization.md
rename to docs/docs/reference/other-new-features/safe-initialization.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/targetName.md b/docs/docs/reference/other-new-features/targetName.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/targetName.md
rename to docs/docs/reference/other-new-features/targetName.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/threadUnsafe-annotation.md b/docs/docs/reference/other-new-features/threadUnsafe-annotation.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/threadUnsafe-annotation.md
rename to docs/docs/reference/other-new-features/threadUnsafe-annotation.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/trait-parameters.md b/docs/docs/reference/other-new-features/trait-parameters.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/trait-parameters.md
rename to docs/docs/reference/other-new-features/trait-parameters.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/transparent-traits.md b/docs/docs/reference/other-new-features/transparent-traits.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/transparent-traits.md
rename to docs/docs/reference/other-new-features/transparent-traits.md
diff --git a/docs-for-scalalang/docs/reference/other-new-features/type-test.md b/docs/docs/reference/other-new-features/type-test.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/other-new-features/type-test.md
rename to docs/docs/reference/other-new-features/type-test.md
diff --git a/docs-for-scalalang/docs/reference/overview.md b/docs/docs/reference/overview.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/overview.md
rename to docs/docs/reference/overview.md
diff --git a/docs-for-scalalang/docs/reference/soft-modifier.md b/docs/docs/reference/soft-modifier.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/soft-modifier.md
rename to docs/docs/reference/soft-modifier.md
diff --git a/docs-for-scalalang/docs/reference/syntax.md b/docs/docs/reference/syntax.md
similarity index 100%
rename from docs-for-scalalang/docs/reference/syntax.md
rename to docs/docs/reference/syntax.md
diff --git a/docs/docs/usage/language-versions.md b/docs/docs/usage/language-versions.md
deleted file mode 100644
index f40abf81a7b0..000000000000
--- a/docs/docs/usage/language-versions.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-layout: doc-page
-title: "Language Versions"
-movedTo: https://docs.scala-lang.org/scala3/reference/language-versions.html
----
-
-The default Scala language version currently supported by the Dotty compiler is `3.0`. There are also other language versions that can be specified instead:
-
- - `3.0-migration`: Same as `3.0` but with a Scala 2 compatibility mode that helps moving Scala 2.13 sources over to Scala 3. In particular, it
-
-    - flags some Scala 2 constructs that are disallowed in Scala 3 as migration warnings instead of hard errors,
-    - changes some rules to be more lenient and backwards compatible with Scala 2.13
-    - gives some additional warnings where the semantics has changed between Scala 2.13 and 3.0
-    - in conjunction with `-rewrite`, offer code rewrites from Scala 2.13 to 3.0.
-
- - `future`: A preview of changes introduced in the next versions after 3.0. In the doc pages here we refer to the language version with these changes as `3.1`, but it might be that some of these changes will be rolled out in later `3.x` versions.
-
- Some Scala-2 specific idioms will be dropped in this version. The feature set supported by this version will be refined over time  as we approach its release.
-
- - `future-migration`: Same as `future` but with additional helpers to migrate from `3.0`. Similarly to the helpers available under `3.0-migration`, these include migration warnings and optional rewrites.
-
-There are two ways to specify a language version.
-
- - With a `-source` command line setting, e.g. `-source 3.0-migration`.
- - With a `scala.language` import at the top of a source file, e.g:
-
-```scala
-package p
-import scala.language.`future-migration`
-
-class C { ... }
-```
-
-Language imports supersede command-line settings in the source files where they are specified. Only one language import specifying a source version is allowed in a source file, and it must come before any definitions in that file.
-
diff --git a/docs-for-scalalang/docs/usage/scaladoc/blog.md b/docs/docs/usage/scaladoc/blog.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/blog.md
rename to docs/docs/usage/scaladoc/blog.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/docstrings.md b/docs/docs/usage/scaladoc/docstrings.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/docstrings.md
rename to docs/docs/usage/scaladoc/docstrings.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/index.md b/docs/docs/usage/scaladoc/index.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/index.md
rename to docs/docs/usage/scaladoc/index.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/linking.md b/docs/docs/usage/scaladoc/linking.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/linking.md
rename to docs/docs/usage/scaladoc/linking.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/search-engine.md b/docs/docs/usage/scaladoc/search-engine.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/search-engine.md
rename to docs/docs/usage/scaladoc/search-engine.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/settings.md b/docs/docs/usage/scaladoc/settings.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/settings.md
rename to docs/docs/usage/scaladoc/settings.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/site-versioning.md b/docs/docs/usage/scaladoc/site-versioning.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/site-versioning.md
rename to docs/docs/usage/scaladoc/site-versioning.md
diff --git a/docs-for-scalalang/docs/usage/scaladoc/static-site.md b/docs/docs/usage/scaladoc/static-site.md
similarity index 100%
rename from docs-for-scalalang/docs/usage/scaladoc/static-site.md
rename to docs/docs/usage/scaladoc/static-site.md
diff --git a/docs/sidebar.yml b/docs/sidebar.yml
index 783c97517ba7..c1a783451451 100644
--- a/docs/sidebar.yml
+++ b/docs/sidebar.yml
@@ -6,7 +6,6 @@ sidebar:
       - page: docs/usage/sbt-projects.md
       - page: docs/usage/ide-support.md
       - page: docs/usage/worksheet-mode.md
-      - page: docs/usage/language-versions.md
       - page: docs/usage/cbt-projects.md
       - page: docs/usage/scaladoc
   - title: Reference
@@ -27,7 +26,7 @@ sidebar:
           - page: docs/reference/enums/desugarEnums.md
       - title: Contextual Abstractions
         subsection:
-          - page: docs/reference/contextual/motivation.md
+          - page: docs/reference/contextual.md
           - page: docs/reference/contextual/givens.md
           - page: docs/reference/contextual/using-clauses.md
           - page: docs/reference/contextual/context-bounds.md
@@ -42,7 +41,7 @@ sidebar:
           - page: docs/reference/contextual/relationship-implicits.md
       - title: Metaprogramming
         subsection:
-          - page: docs/reference/metaprogramming/toc.md
+          - page: docs/reference/metaprogramming.md
           - page: docs/reference/metaprogramming/inline.md
           - page: docs/reference/metaprogramming/compiletime-ops.md
           - page: docs/reference/metaprogramming/macros.md
@@ -110,7 +109,14 @@ sidebar:
       - title: Experimental Features
         subsection:
           - page: docs/reference/experimental/overview.md
+          - page: docs/reference/experimental/canthrow.md
+          - page: docs/reference/experimental/erased-defs.md
+          - page: docs/reference/experimental/erased-defs-spec.md
+          - page: docs/reference/experimental/named-typeargs.md
+          - page: docs/reference/experimental/named-typeargs-spec.md
+          - page: docs/reference/experimental/numeric-literals.md
       - page: docs/reference/syntax.md
+      - page: docs/reference/language-versions.md
   - title: Contributing
     subsection:
       - page: docs/contributing/contribute-knowledge.md
diff --git a/project/Build.scala b/project/Build.scala
index 13cb718bf783..533f85630cb4 100644
--- a/project/Build.scala
+++ b/project/Build.scala
@@ -1419,7 +1419,7 @@ object Build {
               "https://scala-lang.org/api/versions.json",
               "-Ydocument-synthetic-types",
               s"-snippet-compiler:${dottyLibRoot}/scala/quoted=compile,${dottyLibRoot}/scala/compiletime=compile"
-            ) ++ (if (justAPI) Nil else Seq("-siteroot", "docs", "-Yapi-subdirectory")))
+            ) ++ (if (justAPI) Nil else Seq("-siteroot", "docs-for-dotty-page", "-Yapi-subdirectory")))
 
         if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }
         else if (justAPI) generateDocTask
diff --git a/project/scripts/processDocs.sc b/project/scripts/processDocs.sc
index 28c52431e6b9..2c65f7962acd 100644
--- a/project/scripts/processDocs.sc
+++ b/project/scripts/processDocs.sc
@@ -1,49 +1,57 @@
-import java.nio.file.{ FileSystems, Files, Path }
+import java.nio.file.{ FileSystems, Files, Path, StandardCopyOption }
 import java.io.PrintStream
 import scala.io.{ Codec, Source }
 import scala.collection.JavaConverters._
 
-val inputDir = FileSystems.getDefault.getPath("docs-for-scalalang")
-val outputDir = FileSystems.getDefault.getPath("docs")
+val inputDir = FileSystems.getDefault.getPath("docs")
+val outputDir = FileSystems.getDefault.getPath("docs-for-dotty-page")
 
 def copyFile(path: Path): Unit =
-  val inputStream = Source.fromFile(path.toFile)(Codec.UTF8)
-  val fileContent = inputStream.getLines().mkString("\n")
-
   val newPath = outputDir.resolve(inputDir.relativize(path))
   Files.createDirectories(newPath.getParent())
 
-  new PrintStream(newPath.toFile):
-
-    val titlePattern = "(?s)^---\n.*title: (\".*\").*---"
-    val reference = raw".*/reference/.*".r
-    val usageScaladoc = raw".*/usage/scaladoc/.*".r
-    val transformed = newPath.toString match
-      case reference(_*) => fileContent.replaceAll(
-          titlePattern,
-          s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/contextual/${newPath.getFileName.toString.stripSuffix(".md")}.html\n---"
-        )
-      case usageScaladoc(_*) => fileContent.replaceAll(
-          titlePattern,
-          s"---\ntitle: $$1\n---"
-        )
-      case _ =>
-        fileContent
-
-
-    val jekyllLinkPattern = """\(\{\% link _scala3-reference(.*) %\}\)"""
-    val jekyllLinkSubstitution = "(..$1)"
-    val localLinkPattern = """\((?!http|www)(.*).html\)"""
-    val localLinkSubstitution = "($1.md)"
-    val transformedWithLinks = transformed.replaceAll(
-      jekyllLinkPattern,
-      jekyllLinkSubstitution
-    ).replaceAll(
-      localLinkPattern,
-      localLinkSubstitution
-    )
-
-    write(transformedWithLinks.getBytes("UTF8"))
+  path.toString match
+    case s if s.startsWith("docs/docs/") =>
+      val inputStream = Source.fromFile(path.toFile)(Codec.UTF8)
+      val fileContent = inputStream.getLines().mkString("\n")
+
+      new PrintStream(newPath.toFile):
+
+        // Patterns
+        val titlePattern = "(?s)^---\n.*title: (\".*\").*---"
+
+        val jekyllLinkPattern = """\{\% link _overviews/scala3-scaladoc(.*) %\}"""
+        val jekyllLinkSubstitution = "..$1"
+        val jekyllLinkPattern2 = """\{\% link |_overviews/scala3-scaladoc/(.*) %\}"""
+        val jekyllLinkSubstitution2 = "$1"
+        val localLinkPattern = """\((?!http|www)(.*).html\)"""
+        val localLinkSubstitution = "($1.md)"
+
+        // Prefixes
+        val reference = raw"docs/docs/reference/.*".r
+        val usageScaladoc = raw"docs/docs/usage/scaladoc/.*".r
+
+        val patterns = path.toString match
+          case reference(_*) => Map(
+            titlePattern -> s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/contextual/${newPath.getFileName.toString.stripSuffix(".md")}.html\n---",
+            jekyllLinkPattern -> jekyllLinkSubstitution,
+            jekyllLinkPattern2 -> jekyllLinkSubstitution2,
+            localLinkPattern -> localLinkSubstitution,
+          )
+          case usageScaladoc(_*) => Map(
+            titlePattern -> s"---\ntitle: $$1\n---",
+            jekyllLinkPattern -> jekyllLinkSubstitution,
+            jekyllLinkPattern2 -> jekyllLinkSubstitution2,
+            localLinkPattern -> localLinkSubstitution,
+          )
+          case _ =>
+            Map.empty
+
+        val transformed = patterns.foldLeft(fileContent){ case (res, (pattern, substitution)) => res.replaceAll(pattern, substitution) }
+        write(transformed.getBytes("UTF8"))
+
+    case s =>
+      Files.copy(path, newPath, StandardCopyOption.REPLACE_EXISTING);
 
 def main(args: Array[String]): Unit =
   Files.walk(inputDir).iterator().asScala.filter(Files.isRegularFile(_)).foreach(copyFile)

From ced87c3e3d4c5ad3048074c6b6208f05bebcd932 Mon Sep 17 00:00:00 2001
From: Andrzej Ratajczak <andrzej.ratajczak98@gmail.com>
Date: Mon, 27 Sep 2021 12:34:56 +0200
Subject: [PATCH 3/4] Move script to sbt task

---
 .github/workflows/ci.yaml       |  3 --
 .github/workflows/scaladoc.yaml |  3 --
 .gitignore                      |  3 ++
 docs/README.md                  |  3 +-
 project/Build.scala             |  2 +-
 project/CopyDocs.scala          | 78 +++++++++++++++++++++++++++++++++
 project/scripts/processDocs.sc  | 57 ------------------------
 7 files changed, 83 insertions(+), 66 deletions(-)
 create mode 100644 project/CopyDocs.scala
 delete mode 100644 project/scripts/processDocs.sc

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index c6604631362c..1f60ab5b0236 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -490,9 +490,6 @@ jobs:
       - name: Add SBT proxy repositories
         run: cp -vf .github/workflows/repositories /root/.sbt/ ; true
 
-      - name: Copy docs
-        run: ./bin/scala project/scripts/processDocs.sc 
-
       - name: Generate Website
         run: |
           ./project/scripts/genDocs -doc-snapshot
diff --git a/.github/workflows/scaladoc.yaml b/.github/workflows/scaladoc.yaml
index 843c11992de8..dbe0628751c1 100644
--- a/.github/workflows/scaladoc.yaml
+++ b/.github/workflows/scaladoc.yaml
@@ -52,9 +52,6 @@ jobs:
       - name: Generate testcases documentation
         run: ./project/scripts/sbt scaladoc/generateTestcasesDocumentation
 
-      - name: Copy docs
-        run: ./bin/scala project/scripts/processDocs.sc 
-
       - name: Generate Scala 3 documentation
         run: ./project/scripts/sbt scaladoc/generateScalaDocumentation
 
diff --git a/.gitignore b/.gitignore
index 17a292e4c6a7..3fe2a41f8d2b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -102,3 +102,6 @@ cs
 
 # Coursier test product
 compiler/test-coursier/run/*.jar
+
+# Docs
+docs-for-dotty-page/*
diff --git a/docs/README.md b/docs/README.md
index eaa0a02b9ce6..f6d95155126a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,4 @@
 This directory is for keeping all the compiler related docs.
 
 For serving this files, one should notice that files under `docs/docs/reference` and `docs/docs/usage/scaladoc` are designed to be compatible with `docs.scala-lang` jekyll page.
-If one wants to generate static site with these files, should firstly run the script from `project/scripts/processDocs.sc`, for example with:
-`bin/scala project/scripts/processDocs.sc` and then using sbt task `sbt scaladoc/generateScalaDocumentation` generate the whole scaladoc for dotty.
+Preprocessing the sources to be compatible with scaladoc static site is done via script at `project/CopyDocs.scala`
diff --git a/project/Build.scala b/project/Build.scala
index 533f85630cb4..f90264178e0f 100644
--- a/project/Build.scala
+++ b/project/Build.scala
@@ -1388,7 +1388,7 @@ object Build {
         val dest = file(extraArgs.headOption.getOrElse("scaladoc/output/scala3")).getAbsoluteFile
         val justAPI = extraArgs.drop(1).headOption == Some("--justAPI")
         val majorVersion = (LocalProject("scala3-library-bootstrapped") / scalaBinaryVersion).value
-
+        CopyDocs.copyDocs() // invoke copying function form `project/CopyDocs.scala`
         val dottyJars: Seq[java.io.File] = Seq(
           (`stdlib-bootstrapped`/Compile/products).value,
           (`scala3-interfaces`/Compile/products).value,
diff --git a/project/CopyDocs.scala b/project/CopyDocs.scala
new file mode 100644
index 000000000000..9d37d48bc4a3
--- /dev/null
+++ b/project/CopyDocs.scala
@@ -0,0 +1,78 @@
+import scala.io.{ Codec, Source }
+import java.nio.file.{ FileSystems, Files, Path, StandardCopyOption }
+import java.io.PrintStream
+import collection.JavaConverters._
+
+
+/**
+ * Object used for copying docs from docs to docs-for-dotty-page. More explenation can be found and [readme](../docs/README.md)
+ */
+object CopyDocs {
+
+  /**
+   * Input directory from which we will take all the docs.
+   */
+  val inputDir = FileSystems.getDefault.getPath("docs")
+
+  /**
+   * Output directory. Most of the sources will be copied as they are, but some of the files will have headers and links processed.
+   */
+  val outputDir = FileSystems.getDefault.getPath("docs-for-dotty-page")
+
+  implicit def stringToFun(s: String): MyParams => String = _ => s
+
+  // Patterns, for convenience
+  val titlePattern = "(?s)^---\n.*title: ([^\n]*).*---"
+  val jekyllLinkPattern = """\{\% link _overviews/scala3-scaladoc(.*) %\}"""
+  val jekyllLinkSubstitution = "..$1"
+  val jekyllLinkPattern2 = """\{\% link |_overviews/scala3-scaladoc/(.*) %\}"""
+  val jekyllLinkSubstitution2 = "$1"
+  val localLinkPattern = """\((?!http|www)(.*).html\)"""
+  val localLinkSubstitution = "($1.md)"
+
+  case class MyParams(newPath: String)
+
+  /**
+   * Structure for holding which transformations should be applied to which directories.
+   * The outer map is holding morphism `directory prefix` -> `set of transformations`.
+   * The inner set is a collection of pairs `regex pattern` -> `substitution value`.
+   */
+  val transformationMap: Map[String, Set[(String, MyParams => String)]] = Map(
+    "docs/docs/reference/" -> Set(
+      titlePattern -> ((p) => s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/${p.newPath}.html\n---"),
+      jekyllLinkPattern -> jekyllLinkSubstitution,
+      jekyllLinkPattern2 -> jekyllLinkSubstitution2,
+      localLinkPattern -> localLinkSubstitution,
+    ),
+
+    "docs/docs/usage/scaladoc/" -> Set(
+      titlePattern -> s"---\ntitle: $$1\n---",
+      jekyllLinkPattern -> jekyllLinkSubstitution,
+      jekyllLinkPattern2 -> jekyllLinkSubstitution2,
+      localLinkPattern -> localLinkSubstitution,
+    ),
+  )
+
+  def copyDocs() = {
+    def copyFile(path: Path): Unit = {
+      val newPath = outputDir.resolve(inputDir.relativize(path))
+      Files.createDirectories(newPath.getParent())
+
+      path.toString match {
+        case s if s.startsWith("docs/docs/") =>
+          val inputStream = Source.fromFile(path.toFile)(Codec.UTF8)
+          val fileContent = inputStream.getLines().mkString("\n")
+
+          new PrintStream(newPath.toFile) {
+            val patterns = transformationMap.find { case (k, v) => path.toString.startsWith(k) }.map(_._2).getOrElse(Set.empty)
+            val params = MyParams(newPath = s.stripPrefix("docs/docs/reference/").stripSuffix(".md"))
+            val transformed = patterns.foldLeft(fileContent) { case (res, (pattern, substitution)) => res.replaceAll(pattern, substitution(params)) }
+            write(transformed.getBytes("UTF8"))
+          }
+        case s =>
+          Files.copy(path, newPath, StandardCopyOption.REPLACE_EXISTING);
+      }
+    }
+    Files.walk(inputDir).iterator().asScala.filter(Files.isRegularFile(_)).foreach(copyFile)
+  }
+}
diff --git a/project/scripts/processDocs.sc b/project/scripts/processDocs.sc
deleted file mode 100644
index 2c65f7962acd..000000000000
--- a/project/scripts/processDocs.sc
+++ /dev/null
@@ -1,57 +0,0 @@
-import java.nio.file.{ FileSystems, Files, Path, StandardCopyOption }
-import java.io.PrintStream
-import scala.io.{ Codec, Source }
-import scala.collection.JavaConverters._
-
-val inputDir = FileSystems.getDefault.getPath("docs")
-val outputDir = FileSystems.getDefault.getPath("docs-for-dotty-page")
-
-def copyFile(path: Path): Unit =
-  val newPath = outputDir.resolve(inputDir.relativize(path))
-  Files.createDirectories(newPath.getParent())
-
-  path.toString match
-    case s if s.startsWith("docs/docs/") =>
-      val inputStream = Source.fromFile(path.toFile)(Codec.UTF8)
-      val fileContent = inputStream.getLines().mkString("\n")
-
-      new PrintStream(newPath.toFile):
-
-        // Patterns
-        val titlePattern = "(?s)^---\n.*title: (\".*\").*---"
-
-        val jekyllLinkPattern = """\{\% link _overviews/scala3-scaladoc(.*) %\}"""
-        val jekyllLinkSubstitution = "..$1"
-        val jekyllLinkPattern2 = """\{\% link |_overviews/scala3-scaladoc/(.*) %\}"""
-        val jekyllLinkSubstitution2 = "$1"
-        val localLinkPattern = """\((?!http|www)(.*).html\)"""
-        val localLinkSubstitution = "($1.md)"
-
-        // Prefixes
-        val reference = raw"docs/docs/reference/.*".r
-        val usageScaladoc = raw"docs/docs/usage/scaladoc/.*".r
-
-        val patterns = path.toString match
-          case reference(_*) => Map(
-            titlePattern -> s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/contextual/${newPath.getFileName.toString.stripSuffix(".md")}.html\n---",
-            jekyllLinkPattern -> jekyllLinkSubstitution,
-            jekyllLinkPattern2 -> jekyllLinkSubstitution2,
-            localLinkPattern -> localLinkSubstitution,
-          )
-          case usageScaladoc(_*) => Map(
-            titlePattern -> s"---\ntitle: $$1\n---",
-            jekyllLinkPattern -> jekyllLinkSubstitution,
-            jekyllLinkPattern2 -> jekyllLinkSubstitution2,
-            localLinkPattern -> localLinkSubstitution,
-          )
-          case _ =>
-            Map.empty
-
-        val transformed = patterns.foldLeft(fileContent){ case (res, (pattern, substitution)) => res.replaceAll(pattern, substitution) }
-        write(transformed.getBytes("UTF8"))
-
-    case s =>
-      Files.copy(path, newPath, StandardCopyOption.REPLACE_EXISTING);
-
-def main(args: Array[String]): Unit =
-  Files.walk(inputDir).iterator().asScala.filter(Files.isRegularFile(_)).foreach(copyFile)

From deaa6c1b3e4c8543dfc7cc6362c9b01addf71c0d Mon Sep 17 00:00:00 2001
From: Andrzej Ratajczak <andrzej.ratajczak98@gmail.com>
Date: Wed, 29 Sep 2021 14:12:26 +0200
Subject: [PATCH 4/4] Update headers for experimental and gather loosely
 scattered files for docs.scala-lang

---
 .../reference/experimental/named-typeargs.md  |   3 +-
 .../experimental/numeric-literals.md          |   4 +-
 docs/docs/reference/experimental/overview.md  |   3 +-
 docs/docs/resources/talks.md                  |  77 +++---
 docs/docs/usage/getting-started.md            | 234 +++++++++++++-----
 docs/docs/usage/ide-support.md                |  63 +----
 docs/docs/usage/tools-worksheets.md           |  56 +++++
 docs/docs/usage/worksheet-mode.md             |  51 ----
 docs/sidebar.yml                              |   2 +-
 project/CopyDocs.scala                        |  32 ++-
 10 files changed, 295 insertions(+), 230 deletions(-)
 create mode 100644 docs/docs/usage/tools-worksheets.md
 delete mode 100644 docs/docs/usage/worksheet-mode.md

diff --git a/docs/docs/reference/experimental/named-typeargs.md b/docs/docs/reference/experimental/named-typeargs.md
index e9a67b0368dd..0abdd9d40e29 100644
--- a/docs/docs/reference/experimental/named-typeargs.md
+++ b/docs/docs/reference/experimental/named-typeargs.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Named Type Arguments"
 ---
 
diff --git a/docs/docs/reference/experimental/numeric-literals.md b/docs/docs/reference/experimental/numeric-literals.md
index 3303043aa4ea..da4a267784d1 100644
--- a/docs/docs/reference/experimental/numeric-literals.md
+++ b/docs/docs/reference/experimental/numeric-literals.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Numeric Literals"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/numeric-literals.html
 ---
 
 **Note**: This feature is not yet part of the Scala 3 language definition. It can be made available by a language import:
diff --git a/docs/docs/reference/experimental/overview.md b/docs/docs/reference/experimental/overview.md
index bd2cda02d79a..fe785e0302c3 100644
--- a/docs/docs/reference/experimental/overview.md
+++ b/docs/docs/reference/experimental/overview.md
@@ -1,5 +1,6 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Experimental language features"
 author: Nicolas Stucki
 ---
diff --git a/docs/docs/resources/talks.md b/docs/docs/resources/talks.md
index c902c5d4cd16..9991d847fb9a 100644
--- a/docs/docs/resources/talks.md
+++ b/docs/docs/resources/talks.md
@@ -1,62 +1,69 @@
 ---
-layout: doc-page
-title: Talks
-movedTo: https://docs.scala-lang.org/scala3/talks.html
+layout: singlepage-overview
+title: "Talks"
 ---
 
-Talks on Dotty
---------------
+Let’s Talk About Scala 3 Series
+-------------------------------
+
+[Let’s Talk About Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) is a series
+of short (around 15 min) talks about Scala 3. It covers a variety of themes like how to get started, how to take
+advantage of the new language features, or how to migrate from Scala 2.
+
+Talks on Scala 3
+----------------
 - (ScalaDays 2019, Lausanne) [A Tour of Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw) by [Martin Odersky](http://twitter.com/odersky) [\[slides\]](https://www.slideshare.net/Odersky/a-tour-of-scala-3)
 
 - (ScalaDays 2016, Berlin) [Scala's Road Ahead](https://www.youtube.com/watch?v=GHzWqJKFCk4) by [Martin Odersky](http://twitter.com/odersky) [\[slides\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016)
 
 - (JVMLS 2015) [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) by [Martin Odersky](http://twitter.com/odersky) [\[slides\]](http://www.slideshare.net/Odersky/compilers-are-databases)
 
-- (Scala World 2015) [Dotty: Exploring the future of Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) by [Dmitry Petrashko](http://twitter.com/darkdimius) [\[slides\]](https://d-d.me/scalaworld2015/#/). 
-Dmitry covers many of the new features that Dotty brings on the table such as Intersection and Union types, improved lazy val initialization and more. 
-Dmitry also covers dotty internals and in particular the high-level of contextual abstractions of Dotty. You will get to 
-become familiar with many core concepts such as `Denotations`, their evolution through (compilation) time, their 
-transformations and more.
+- (Scala World 2015) [Dotty: Exploring the future of Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) by [Dmitry Petrashko](http://twitter.com/darkdimius) [\[slides\]](https://d-d.me/scalaworld2015/#/).
+  Dmitry covers many of the new features that Dotty brings on the table such as Intersection and Union types, improved lazy val initialization and more.
+  Dmitry also covers dotty internals and in particular the high-level of contextual abstractions of Dotty. You will get to
+  become familiar with many core concepts such as `Denotations`, their evolution through (compilation) time, their
+  transformations and more.
 
-Deep Dive with Dotty
---------------------
+Deep Dive with Scala 3
+----------------------
 - (ScalaDays 2019, Lausanne) [Metaprogramming in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) by [Nicolas Stucki](https://github.com/nicolasstucki).
 
 - (ScalaDays 2019, Lausanne) [Future-proofing Scala: the TASTY intermediate representation](https://www.youtube.com/watch?v=zQFjC3zLYwo) by [Guillaume Martres](http://guillaume.martres.me/).
 
-- (Mar 21, 2017) [Dotty Internals 1: Trees & Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) by [Dmitry Petrashko](http://twitter.com/darkdimius) [\[meeting notes\]](../internals/dotty-internals-1-notes.md). 
-This is a recorded meeting between EPFL and Waterloo, where we introduce first notions inside Dotty: Trees and Symbols.
+- (Mar 21, 2017) [Dotty Internals 1: Trees & Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) by [Dmitry Petrashko](http://twitter.com/darkdimius) [\[meeting notes\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html).
+  This is a recorded meeting between EPFL and Waterloo, where we introduce first notions inside Dotty: Trees and Symbols.
 
 - (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc) by [Martin Odersky](http://twitter.com/odersky) and [Dmitry Petrashko](http://twitter.com/darkdimius).
-This is a recorded meeting between EPFL and Waterloo, where we introduce how types are represented inside Dotty.
+  This is a recorded meeting between EPFL and Waterloo, where we introduce how types are represented inside Dotty.
 
 - (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY) by [Martin Odersky](http://twitter.com/odersky) and [Dmitry Petrashko](http://twitter.com/darkdimius).
-This is a recorded meeting between EPFL and Waterloo, where we introduce denotations in Dotty.
+  This is a recorded meeting between EPFL and Waterloo, where we introduce denotations in Dotty.
 
 - (JVM Language Summit) [How do we make the Dotty compiler fast](https://www.youtube.com/watch?v=9xYoSwnSPz0) by [Dmitry Petrashko](http://twitter.com/darkdimius).
-[Dmitry Petrashko](http://twitter.com/darkdimius) gives a high-level introduction on what was done to make Dotty .
+  [Dmitry Petrashko](http://twitter.com/darkdimius) gives a high-level introduction on what was done to make Dotty .
 
 
-- (Typelevel Summit Oslo, May 2016) [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) by 
-Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/).
-Guillaume focused on some of the practical improvements to the type system that Dotty makes, like the new type parameter 
-inference algorithm that is able to reason about the type safety of more situations than scalac.
+- (Typelevel Summit Oslo, May 2016) [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) by
+  Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/).
+  Guillaume focused on some of the practical improvements to the type system that Dotty makes, like the new type parameter
+  inference algorithm that is able to reason about the type safety of more situations than scalac.
 
-- (flatMap(Oslo) 2016) [AutoSpecialization in Dotty](https://vimeo.com/165928176) by [Dmitry Petrashko](http://twitter.com/darkdimius) [\[slides\]](https://d-d.me/talks/flatmap2016/#/). 
-The Dotty Linker analyses your program and its dependencies to 
-apply a new specialization scheme. It builds on our experience from Specialization, Miniboxing and the Valhalla Project, 
-and drastically reduces the size of the emitted bytecode. And, best of all, it's always enabled, happens behind the 
-scenes without annotations,  and results in speedups in excess of 20x. Additionally, it "just works" on Scala collections.
+- (flatMap(Oslo) 2016) [AutoSpecialization in Dotty](https://vimeo.com/165928176) by [Dmitry Petrashko](http://twitter.com/darkdimius) [\[slides\]](https://d-d.me/talks/flatmap2016/#/).
+  The Dotty Linker analyses your program and its dependencies to
+  apply a new specialization scheme. It builds on our experience from Specialization, Miniboxing and the Valhalla Project,
+  and drastically reduces the size of the emitted bytecode. And, best of all, it's always enabled, happens behind the
+  scenes without annotations,  and results in speedups in excess of 20x. Additionally, it "just works" on Scala collections.
 
 - (ScalaSphere 2016) [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-live-demo/).
-Guillaume hacks on Dotty: a live demo during which he 
-creates a simple compiler phase to trace method calls at run-time.
+  Guillaume hacks on Dotty: a live demo during which he
+  creates a simple compiler phase to trace method calls at run-time.
+
+- (Scala By the Bay 2016) [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) by Guillaume
+  Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-tutorial/#/). Guillaume provides a high-level view of the
+  compilation-pipeline of Dotty.
 
-- (Scala By the Bay 2016) [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) by Guillaume 
-Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-tutorial/#/). Guillaume provides a high-level view of the 
-compilation-pipeline of Dotty.
+- (ScalaDays 2015, Amsterdam) [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) by Dmitry Petrashko [\[slides\]](https://d-d.me/scaladays2015/#/).
+  Dmitry introduces the call-graph analysis algorithm
+  that Dotty implements and the performance benefits we can get in terms of number of methods, bytecode size, JVM code size
+  and the number of objects allocated in the end.
 
-- (ScalaDays 2015, Amsterdam) [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) by Dmitry Petrashko [\[slides\]](https://d-d.me/scaladays2015/#/). 
-Dmitry introduces the call-graph analysis algorithm 
-that Dotty implements and the performance benefits we can get in terms of number of methods, bytecode size, JVM code size 
-and the number of objects allocated in the end.
diff --git a/docs/docs/usage/getting-started.md b/docs/docs/usage/getting-started.md
index 436183c391ec..c888285fb39c 100644
--- a/docs/docs/usage/getting-started.md
+++ b/docs/docs/usage/getting-started.md
@@ -1,93 +1,193 @@
 ---
-layout: doc-page
-title: Getting Started: Users
-movedTo: https://docs.scala-lang.org/scala3/getting-started.html
+layout: singlepage-overview
+title: Getting Started with Scala 3
+languages: ["ja"]
 ---
 
-## Trying out Dotty
 
-### In your web browser
-[Scastie](https://scastie.scala-lang.org/?target=dotty), the online Scala playground, supports Dotty.
-This is an easy way to try Dotty without installing anything, directly in your browser.
 
-### sbt
-The fastest way to create a new project compiled by Dotty is using [sbt](http://www.scala-sbt.org/)
+## Try Scala without installing anything
 
-Create a simple Dotty project:
-```bash
-$ sbt new scala/scala3.g8
-```
+To start experimenting with Scala 3 right away, use <a href="https://scastie.scala-lang.org/?target=dotty" target="_blank">“Scastie” in your browser</a>.
+_Scastie_ is an online “playground” where you can experiment with Scala examples to see how things work, with access to all Scala compilers and published libraries.
 
-Or a Dotty project that cross compiles with Scala 2:
-```bash
-$ sbt new scala/scala3-cross.g8
-```
 
-You can then start a Dotty REPL directly from your sbt project:
-```bash
-$ sbt
-> console
-scala>
-```
 
-For more information, see the [Dotty Example Project](https://github.com/scala/scala3-example-project)
+## Install Scala on your computer
+
+Installing Scala means installing various command-line tools and build tools.
+We recommend using the Scala installer tool "Coursier" that automatically installs all the requirements, but you can still manually install each tool.
+
+
+### Using the Scala Installer (recommended way)
+
+The Scala installer is a tool named [Coursier](https://get-coursier.io/docs/cli-overview), whose main command is named `cs`.
+It ensures that a JVM and standard Scala tools are installed on your system.
+Install it on your system with the following instructions.
+
+<div class="main-download">
+  <div id="download-step-one">
+    <p>Follow <a href="https://get-coursier.io/docs/cli-overview.html#install-native-launcher" target="_blank">the instructions to install the <code>cs</code> launcher</a> then run:</p>
+    <p><code>$ cs install scala3-repl</code></p>
+    <p><code>$ cs install scala3-compiler</code></p>
+  </div>
+</div>
+
+Along with managing JVMs, `cs setup` also installs useful command line tools:
+
+- A JDK
+- The [sbt](https://www.scala-sbt.org) and [mill](https://com-lihaoyi.github.io/mill/) build tools
+- [Ammonite](https://ammonite.io), an enhanced REPL
+- [scalafmt](https://scalameta.org/scalafmt), the Scala formatter
+- The [Coursier CLI](https://get-coursier.io/docs/cli-overview), to install further Scala-based applications
+- (the `scala` and `scalac` command-line tools for Scala 2.13 -- not Scala 3).
+
+For more information, read the [coursier-cli documentation](https://get-coursier.io/docs/cli-overview).
+
+
+### ... or manually
 
-### IDE support
-Start using the Dotty IDE in any Dotty project by following the
-[IDE guide](./ide-support.md).
+You only need two tools to compile, run, test, and package a Scala project: Java 8 or 11, and sbt.
+To install these manually:
 
-### Standalone installation
-Releases are available for download on the [Releases Section](https://github.com/lampepfl/dotty/releases)
-of the Dotty repository. Releases include three executables: `scalac` the Dotty compiler,
-`scaladoc` the [Scaladoc](./scaladoc/index.md) and `scala` the Dotty REPL.
+1. Download Java from [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html), or [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Refer to [JDK Compatibility](/overviews/jdk-compatibility/overview.html) for Scala/Java compatibility detail.
+2. Install [sbt](https://www.scala-sbt.org/download.html)
+
+
+
+## Create a “Hello, world” project with sbt
+
+To create a project, you can either use a command-line tool or an IDE.
+If you are familiar with the command line, we recommend that approach.
+
+
+### Using the command line
+
+sbt is a build tool for Scala.
+sbt compiles, runs, and tests your Scala code.
+(It can also publish libraries and do many other tasks.)
+
+To create a new Scala project with sbt:
+
+1. `cd` to an empty folder.
+1. Run this command `sbt new scala/scala3.g8`.
+This pulls the ['hello-world' template][template-url] from GitHub.
+It also creates a _target_ folder, which you can ignore.
+1. When prompted, name the application `hello world`.
+   This will create a project called "hello-world".
+1. Let’s take a look at what just got generated:
 
 ```
-.
-└── bin
-    ├── scalac
-    ├── scaladoc
-    └── scala
+hello-world/
+  project/           (sbt uses this for its own files)
+    build.properties
+  src/main/scala/    (all of your Scala code goes here)
+    Main.scala       (entry point of program)
+  build.sbt          (sbt’s build definition file)
 ```
+The scala file `Main.scala` in `src/main/scala` is all we need for now.
 
-Add these executables to your `PATH` and you will be able to run the corresponding commands directly
-from your console:
-```bash
-# Compile code using Dotty
-$ scalac HelloWorld.scala
+More documentation about sbt can be found in the [Scala Book](/scala3/book/scala-tools.html) and in the official sbt [documentation](https://www.scala-sbt.org/1.x/docs/index.html)
 
-# Run it with the proper classpath
-$ scala HelloWorld
 
-# Start a Dotty REPL
-$ scala
-Starting dotty REPL...
-scala>
-```
+{% comment %}
+### With IntelliJ IDEA
 
-If you're a Mac user, we also provide a [homebrew](https://brew.sh/) package that can be installed by running:
+You can skip the rest of this page and go directly to [Building a Scala Project with IntelliJ and sbt](/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html)
+{% endcomment %}
 
-```bash
-brew install lampepfl/brew/dotty
-```
 
-In case you have already installed Dotty via brew, you should instead update it:
+## Open the “Hello, world” project
 
-```bash
-brew upgrade dotty
-```
+Let’s use an IDE to open the project.
+The most popular ones are IntelliJ IDEA and VS Code.
+They both offer rich IDE features, but you can still use [many other editors.](https://scalameta.org/metals/docs/editors/overview.html)
 
-### Scala 3 for Scripting
-If you have followed the steps in "Standalone Installation" section and have the `scala` executable on your `PATH`, you can run `*.scala` files as scripts. Given a source named Test.scala:
+### Using IntelliJ IDEA
 
-```scala
-@main def Test(name: String): Unit =
-  println(s"Hello ${name}!")
-```
+1. Download and install [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
+1. Install the Scala plugin by following [the instructions on how to install IntelliJ plugins](https://www.jetbrains.com/help/idea/managing-plugins.html)
+1. Open the _build.sbt_ file, then choose _Open as a project_
+
+### Using VS Code with Metals
+
+1. Download [VS Code](https://code.visualstudio.com/Download)
+1. Install the Metals extension from [the Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals)
+1. Next, open the directory containing your _build.sbt_ file.
+   When prompted to do so, select _Import build_.
+
+>[Metals](https://scalameta.org/metals) is a “Scala language server” that provides support for writing Scala code in VS Code and other editors like [Atom, Sublime Text, and more](https://scalameta.org/metals/docs/editors/overview.html), using the Language Server Protocol.
+>
+> Under the hood, Metals communicates with the build tool by using
+> the [Build Server Protocol (BSP)](https://build-server-protocol.github.io/). For details on how Metals works, see, [“Write Scala in VS Code, Vim, Emacs, Atom and Sublime Text with Metals”](https://www.scala-lang.org/2019/04/16/metals.html).
+
+
+### View the source code
+
+View these two files in your IDE:
+
+- _build.sbt_
+- _src/main/scala/Main.scala_
+
+When you run your project in the next step, the configuration in _build.sbt_ will be used to run the code in _src/main/scala/Main.scala_.
+
+
+
+## Run the “Hello, world” project
+
+If you’re comfortable using your IDE, you can run the code in _Main.scala_ from your IDE.
+
+Otherwise, you can run the application from a terminal with these steps:
+
+1. `cd` into _hello-world_.
+1. Run `sbt`.
+   This opens up the sbt console.
+1. Type `~run`.
+   The `~` is optional and causes sbt to re-run on every file save, allowing for a fast edit/run/debug cycle.
+   sbt also generates a `target` directory for its own use, which you can ignore.
+
+When you’re finished experimenting with this project, press `[Enter]` to interrupt the `run` command.
+Then type `exit` or press `[Ctrl][d]` to exit sbt and return to your command line prompt.
+
+
+
+## Next steps
+
+Now that you’ve created a first “Hello, world” example with Scala 3, you’re ready for some next steps.
+Consider checking out:
+
+- [The Scala 3 Book](/scala3/book/introduction.html), which provides a set of short lessons introducing Scala’s main features
+- [The migration guide](/scala3/guides/migration/compatibility-intro.html) helps you to migrate your existing Scala 2 code base to Scala 3.
+
+When you want to connect with other Scala users, there are several mailing lists and real-time chat rooms available.
+Check out our [Scala community page](https://scala-lang.org/community/) for a list of these resources, and for where to reach out for help.
+
+
+<!-- Hidden elements whose content are used to provide OS-specific download instructions.
+ -- This is handled in `resources/js/functions.js`.
+ -->
+<div style="display:none" id="stepOne-linux">
+       <code class="hljs">$ curl -Lo cs https://git.io/coursier-cli-linux && chmod +x cs && ./cs setup </code> <br>
+</div>
+
+<div style="display:none" id="stepOne-unix">
+    <p>Follow <a href="https://get-coursier.io/docs/cli-overview.html#install-native-launcher" target="_blank">the instructions to install the <code>cs</code> launcher</a> then run:</p>
+    <p><code>$ ./cs setup</code></p>
+</div>
 
-You can run: `scala Test.scala World` to get an output `Hello World!`.
+<div style="display:none" id="stepOne-osx">
+    <p>If you use Homebrew:</p>
+    <div class="highlight">
+        <code class="hljs">$ brew install coursier/formulas/coursier && cs setup </code> <br>
+    </div>
+    <p>Alternatively, if you don’t use Homebrew:</p>
+    <div class="highlight">
+        <code class="hljs">$ curl -Lo cs https://git.io/coursier-cli-macos && chmod +x cs &&  (xattr -d com.apple.quarantine cs || true) && ./cs  setup </code> <br>
+    </div>
+</div>
 
-A "script" is an ordinary Scala file which contains a main method. The semantics of the `scala Script.scala` command is as follows:
+<div style="display:none" id="stepOne-windows">
+    <p>Download and execute <a href="https://git.io/coursier-cli-windows-exe">the Scala installer for Windows</a> based on coursier</p>
+</div>
 
-- Compile `Script.scala` with `scalac` into a temporary directory.
-- Detect the main method in the `*.class` files produced by the compilation.
-- Execute the main method.
+[template-url]: https://github.com/scala/scala3.g8
diff --git a/docs/docs/usage/ide-support.md b/docs/docs/usage/ide-support.md
index 515a0cad8de8..eabfe29ecf49 100644
--- a/docs/docs/usage/ide-support.md
+++ b/docs/docs/usage/ide-support.md
@@ -4,65 +4,4 @@ title: "IDE support for Scala 3"
 movedTo: https://docs.scala-lang.org/scala3/getting-started.html
 ---
 
-IDE support for Scala 3 is available in IDEs based on [Scala Metals](https://scalameta.org/metals/)
-(e.g., Visual Studio Code, vim) and in [IntelliJ IDEA](https://www.jetbrains.com/idea/).
-
-
-## Using Visual Studio Code
-
-To use Visual Studio Code on a Scala 3 project, ensure you have the
-[Metals](https://scalameta.org/metals/docs/editors/vscode.html) plugin installed. Then open the
-project directory in VS code and click the "Import build" button in notification.
-
-
-### Under the Hood
-
-VS Code implements semantic features (such as completions, "go to definition")
-using the [Language Server Protocol (LSP)](https://github.com/Microsoft/language-server-protocol),
-so it needs a language server implementation. Metals is the implementation of LSP for Scala. It
-extracts semantic information from [semanticdb](https://scalameta.org/docs/semanticdb/guide.html),
-which is generated directly by the Scala 3 compiler.
-
-You can read more about Scala 3 support in Metals in
-[this blog post](https://medium.com/virtuslab/introduction-to-metals-with-scala-3-79ebf3120a95).
-
-To communicate with the build tool (e.g., to import the project, trigger builds, run tests),
-Metals uses the [Build Server Protocol (BSP)](https://build-server-protocol.github.io/). The
-default BSP implementation used by metals is [Bloop](https://scalacenter.github.io/bloop/), which
-supports Scala 3 projects. Alternatively,
-[sbt can be used as a BSP server](https://scalameta.org/metals/blog/2020/11/06/sbt-BSP-support.html)
-as it directly implements BSP since version 1.4.
-
-
-## Using IntelliJ IDEA
-
-IntelliJ has its own implementation for semantic features, so it does not use Metals or the
-Language Server Protocol (LSP).
-
-In order to import a project into IntelliJ there are two possibilities:
-
-  - Use the built-in feature to import sbt builds
-  - Use IntelliJ's support for the
-    [Build Server Protocol (BSP)](https://www.jetbrains.com/help/idea/bsp-support.html)
-
-
-### Importing the sbt build
-
-To use IntelliJ's sbt import, go to "File" - "Open..." and select your project's `build.sbt` file.
-
-In this mode, IntelliJ starts sbt with a custom plugin to extract the project structure. After
-importing, IntelliJ no longer interacts with other sbt sessions. Building and running the project
-within the IDE is done by separate processes.
-
-
-### Importing the project using BSP
-
-To import a project using BSP, go to "File" - "New" - "Project from Existing Sources" and select
-the project directory. In the upcoming dialog select "BSP" to import the project. You may be asked
-to choose between "sbt" and "sbt with Bloop", the recommended option is "sbt".
-
-If the project import fails ("Problem executing BSP job"), navigate to your project in a terminal
-and just start `sbt`. Once sbt is running, open the "bsp" tab in IntelliJ click the "Reload" button.
-
-When using IntelliJ's BSP mode, build and run commands from the IDE are executed through sbt, so
-they have the same effect as building or running the project through sbt in the terminal.
+This page is deprecated. Plese go to [getting-started](getting-started.md)
diff --git a/docs/docs/usage/tools-worksheets.md b/docs/docs/usage/tools-worksheets.md
new file mode 100644
index 000000000000..e503e72f0c23
--- /dev/null
+++ b/docs/docs/usage/tools-worksheets.md
@@ -0,0 +1,56 @@
+---
+title: Worksheets
+type: section
+description: This section looks at worksheets, an alternative to Scala projects.
+num: 71
+previous-page: tools-sbt
+next-page: interacting-with-java
+---
+
+A worksheet is a Scala file that is evaluated on save, and the result of each expression is shown
+in a column to the right of your program. Worksheets are like a [REPL session] on steroids, and
+enjoy 1st class editor support: completion, hyperlinking, interactive errors-as-you-type, etc.
+Worksheets use the extension `.worksheet.sc`.
+
+In the following, we show how to use worksheets in IntelliJ, and in VS Code (with the Metals extension).
+
+1. Open a Scala project, or create one.
+   - To create a project in IntelliJ, select “File” -> “New” -> “Project…”, select “Scala”
+     in the left column, and click “Next” to set the project name and location.
+   - To create a project in VS Code, run the command “Metals: New Scala project”, select the
+     seed `scala/scala3.g8`, set the project location, open it in a new VS Code window, and
+     import its build.
+1. Create a file named `hello.worksheet.sc` in the directory `src/main/scala/`.
+   - In IntelliJ, right-click on the directory `src/main/scala/`, and select “New”, and
+     then “File”.
+   - In VS Code, right-click on the directory `src/main/scala/`, and select “New File”.
+1. Paste the following content in the editor:
+   ~~~
+   println("Hello, world!")
+
+   val x = 1
+   x + x
+   ~~~
+1. Evaluate the worksheet.
+   - In IntelliJ, click on the green arrow at the top of the editor to evaluate the worksheet.
+   - In VS Code, save the file.
+
+   You should see the result of the evaluation of every line on the right panel (IntelliJ), or
+   as comments (VS Code).
+
+![]({{ site.baseurl }}/resources/images/scala3-book/intellij-worksheet.png)
+
+A worksheet evaluated in IntelliJ.
+
+![]({{ site.baseurl }}/resources/images/scala3-book/metals-worksheet.png)
+
+A worksheet evaluated in VS Code (with the Metals extension).
+
+Note that the worksheet will use the Scala version defined by your project (set by the key `scalaVersion`,
+in your file `build.sbt`, typically).
+
+Also note that worksheets don’t have a [program entry point]. Instead, top-level statements and expressions
+are evaluated from top to bottom.
+
+[REPL session]: {% link _overviews/scala3-book/taste-repl.md %}
+[program entry point]: {% link _overviews/scala3-book/methods-main-methods.md %}
diff --git a/docs/docs/usage/worksheet-mode.md b/docs/docs/usage/worksheet-mode.md
deleted file mode 100644
index a9492c5f3fbc..000000000000
--- a/docs/docs/usage/worksheet-mode.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-layout: doc-page
-title: "Worksheet mode with Dotty IDE"
-movedTo: https://docs.scala-lang.org/scala3/book/tools-worksheets.html
----
-
-A worksheet is a Scala file that is evaluated on save, and the result of each
-expression is shown in a column to the right of your program. Worksheets are
-like a REPL session on steroids, and enjoy 1st class editor support: completion,
-hyperlinking, interactive errors-as-you-type, etc. Worksheet use the extension
-`.sc`.
-
-How to use the worksheets
-=========================
-The only supported client for the Worksheet mode is [Visual Studio
-Code](https://code.visualstudio.com/).
-
-To use the worksheets, start Dotty IDE by [following the
-instruction](ide-support.md) and create a new file `MyWorksheet.sc` and
-write some code:
-
-```scala
-val xyz = 123
-println("Hello, worksheets!")
-456 + xyz
-```
-
-On top of the buffer, the message `Run this worksheet` appears. Click it to
-evaluate the code of the worksheet. Each line of output is printed on the right
-of the expression that produced it. The worksheets run with the classes of your
-project and its dependencies on their classpath.
-
-![](images/worksheets/worksheet-run.png "Run worksheet")
-
-By default, the worksheets are also run when the file is saved. This can be
-configured in VSCode preferences:
-
-![](images/worksheets/config-autorun.png "Configure run on save")
-
-Note that the worksheet are fully integrated with the rest of Dotty IDE: While
-typing, errors are shown, completions are suggested, and you can use all the
-other features of Dotty IDE such as go to definition, find all references, etc.
-
-![](images/worksheets/worksheet-help.png "IDE features in the worksheet")
-
-Implementation details
-======================
-
-The implementation details of the worksheet mode and the information necessary to add support for
-other clients are available in [Worksheet mode - Implementation
-details](worksheet-mode-implementation-details.md).
diff --git a/docs/sidebar.yml b/docs/sidebar.yml
index c1a783451451..4b47033e64cb 100644
--- a/docs/sidebar.yml
+++ b/docs/sidebar.yml
@@ -5,7 +5,7 @@ sidebar:
       - page: docs/usage/getting-started.md
       - page: docs/usage/sbt-projects.md
       - page: docs/usage/ide-support.md
-      - page: docs/usage/worksheet-mode.md
+      - page: docs/usage/tools-worksheets.md
       - page: docs/usage/cbt-projects.md
       - page: docs/usage/scaladoc
   - title: Reference
diff --git a/project/CopyDocs.scala b/project/CopyDocs.scala
index 9d37d48bc4a3..5713f15e71ef 100644
--- a/project/CopyDocs.scala
+++ b/project/CopyDocs.scala
@@ -32,25 +32,37 @@ object CopyDocs {
 
   case class MyParams(newPath: String)
 
+  val commonTransformations: Set[(String, MyParams => String)] = Set(
+    jekyllLinkPattern -> jekyllLinkSubstitution,
+    jekyllLinkPattern2 -> jekyllLinkSubstitution2,
+    localLinkPattern -> localLinkSubstitution,
+  )
+
   /**
    * Structure for holding which transformations should be applied to which directories.
    * The outer map is holding morphism `directory prefix` -> `set of transformations`.
    * The inner set is a collection of pairs `regex pattern` -> `substitution value`.
    */
   val transformationMap: Map[String, Set[(String, MyParams => String)]] = Map(
-    "docs/docs/reference/" -> Set(
-      titlePattern -> ((p) => s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/${p.newPath}.html\n---"),
-      jekyllLinkPattern -> jekyllLinkSubstitution,
-      jekyllLinkPattern2 -> jekyllLinkSubstitution2,
-      localLinkPattern -> localLinkSubstitution,
+    "docs/docs/reference/" -> (commonTransformations +
+      (titlePattern -> ((p) => s"---\nlayout: doc-page\ntitle: $$1\nmovedTo: https://docs.scala-lang.org/scala3/reference/${p.newPath}.html\n---")),
+    ),
+
+    "docs/docs/usage/scaladoc/" -> (commonTransformations +
+      (titlePattern -> s"---\ntitle: $$1\n---"),
     ),
 
-    "docs/docs/usage/scaladoc/" -> Set(
-      titlePattern -> s"---\ntitle: $$1\n---",
-      jekyllLinkPattern -> jekyllLinkSubstitution,
-      jekyllLinkPattern2 -> jekyllLinkSubstitution2,
-      localLinkPattern -> localLinkSubstitution,
+    "docs/docs/usage/getting-started" -> (commonTransformations +
+      (titlePattern -> "---\nlayout: doc-page\ntitle: Getting Started: Users\nmovedTo: https://docs.scala-lang.org/scala3/getting-started.html\n---"),
     ),
+
+    "docs/docs/usage/tools-worksheets" -> (commonTransformations +
+      (titlePattern -> "---\nlayout: doc-page\ntitle: \"Worksheet mode with Dotty IDE\"\nmovedTo: https://docs.scala-lang.org/scala3/book/tools-worksheets.html\n---")
+    ),
+
+    "docs/docs/resources/talks" -> (commonTransformations +
+      (titlePattern -> "---\nlayout: doc-page\ntitle: Talks\nmovedTo: https://docs.scala-lang.org/scala3/talks.html\n---")
+    )
   )
 
   def copyDocs() = {