Docs: split the install and build-from-source guides

The install page (/how-to/install/) now covers only the recommended ghcup
route; building from source moves to its own page. The source-build page
keeps the /how-to/build/ permalink so existing deep links (notably
#test-and-benchmark) stay valid.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: hsyl20

_data/navigation.yml

@@ -50,6 +50,8 @@ docs:
     url: /how-to/
     children:
       - title: Install Plinth standalone compiler
+        url: /how-to/install/
+      - title: Build Plinth from source
         url: /how-to/build/
       - title: Use uplc-ghc in a project
         url: /how-to/use/

explanation/standalone-compiler.md

@@ -44,7 +44,7 @@ GHC, brings several benefits:
   Pinning the plugin to a specific GHC build keeps compiler and plugin in
   lockstep, which makes the generated Plutus Core reproducible and lets the whole
   thing be validated as a single unit (see the test and benchmark scripts in
-  [Install Plinth standalone compiler]({% link how-to/build.md %}#test-and-benchmark)).
+  [Build Plinth from source]({% link how-to/build.md %}#test-and-benchmark)).
 
 ## Further reading
 

how-to/build.md

@@ -1,53 +1,16 @@
 ---
-title: Install Plinth standalone compiler
+title: Build Plinth from source
 permalink: /how-to/build/
 ---
-This guide explains how to get `uplc-ghc`, the
-[Plinth standalone compiler]({% link explanation/standalone-compiler.md %}).
+This guide explains how to build `uplc-ghc`, the
+[Plinth standalone compiler]({% link explanation/standalone-compiler.md %}),
+from source. Most users do not need this: the recommended way to get
+`uplc-ghc` is to
+[install a released binary via ghcup]({% link how-to/install.md %}). Build
+from source when you work on the compiler itself, or when no binary
+distribution covers your platform.
 
-The recommended way is to [install a released binary via
-ghcup](#installing-via-ghcup). [Build from source](#building-from-source) when
-you work on the compiler itself, or when no binary distribution covers your
-platform.
-
-## Installing via ghcup
-
-`uplc-ghc` is distributed as a custom tool named `plinth` for
-[ghcup](https://www.haskell.org/ghcup/), the standard installer for Haskell
-toolchains. You need ghcup 0.2.1.0 or newer (check with `ghcup --version`).
-
-Add the Plinth release channel, then install and activate the tool:
-
-```console
-$ ghcup config add-release-channel https://raw.githubusercontent.com/input-output-hk/ghc-plinth/ghcup-channel/ghcup-plinth.yaml
-$ ghcup install plinth latest
-$ ghcup set plinth latest
-```
-
-`ghcup install` downloads the binary distribution for your platform and
-installs it under ghcup's own directory; `ghcup set` then symlinks `uplc-ghc`
-into ghcup's `bin` directory (`~/.ghcup/bin` by default), which is already on
-`PATH` for ghcup users. Verify with:
-
-```console
-$ uplc-ghc --version
-```
-
-Installing `plinth` does not affect any GHC installed by ghcup: the tool ships
-only the `uplc-*` binaries, so your regular `ghc` is left untouched.
-
-Binary distributions are published for:
-
-- Linux, x86_64 and aarch64 (glibc, and musl/Alpine)
-- macOS, Apple Silicon
-- Windows, x86_64
-
-List the available versions with `ghcup list -t plinth`. Once installed, head
-over to [Use uplc-ghc in a project]({% link how-to/use.md %}).
-
-## Building from source
-
-### Prerequisites
+## Prerequisites
 
 `plinth-build.sh` expects the following tools on `PATH`:
 
@@ -64,7 +27,7 @@ over to [Use uplc-ghc in a project]({% link how-to/use.md %}).
 `happy` and `alex` are built locally into `_build/tools/` if they are not
 found, so they are effectively optional. The others must be present.
 
-### 1. Clone with submodules
+## 1. Clone with submodules
 
 The `plutus` submodule provides `plutus-tx`, `plutus-tx-plugin`, and
 `plutus-core`, so clone recursively:
@@ -79,7 +42,7 @@ If you already cloned without `--recurse-submodules`, fetch them with:
 $ git submodule update --init --recursive
 ```
 
-### 2. Run the build script
+## 2. Run the build script
 
 From the root of the repository:
 
@@ -90,7 +53,7 @@ $ ./plinth-build.sh
 The script bootstraps GHC and then builds `uplc-ghc`. What it produces is
 described under [Build outputs](#build-outputs) below.
 
-### Build options
+## Build options
 
 `plinth-build.sh` is controlled by environment variables. The two most common
 force a full rebuild or select the release flavour:
@@ -110,7 +73,7 @@ It also honours tool-location overrides such as `GHC`, `CABAL`, `HAPPY`,
 `FLAVOUR`, when you need to point it at specific tools or change the build
 flavour.
 
-### Build outputs
+## Build outputs
 
 When `plinth-build.sh` finishes it has produced two things.
 

how-to/index.md

@@ -5,7 +5,8 @@ permalink: /how-to/
 *Task-oriented recipes.* Each guide assumes you already know the basics and
 shows the steps to get one specific job done.
 
-- [Install Plinth standalone compiler]({% link how-to/build.md %})
+- [Install Plinth standalone compiler]({% link how-to/install.md %})
+- [Build Plinth from source]({% link how-to/build.md %})
 - [Use uplc-ghc in a project]({% link how-to/use.md %})
 - [Generate a blueprint]({% link how-to/generate-blueprint.md %})
 - [Test a Plinth contract locally]({% link how-to/test.md %})

how-to/install.md

@@ -0,0 +1,48 @@
+---
+title: Install Plinth standalone compiler
+permalink: /how-to/install/
+---
+`uplc-ghc`, the
+[Plinth standalone compiler]({% link explanation/standalone-compiler.md %}),
+is distributed as a custom tool named `plinth` for
+[ghcup](https://www.haskell.org/ghcup/), the standard installer for Haskell
+toolchains. Installing it via ghcup, as described here, is the recommended way
+to get it. To work on the compiler itself, or when no binary distribution
+covers your platform, [build it from source]({% link how-to/build.md %})
+instead.
+
+## Install via ghcup
+
+You need ghcup 0.2.1.0 or newer (check with `ghcup --version`). Add the Plinth
+release channel, then install and activate the tool:
+
+```console
+$ ghcup config add-release-channel https://raw.githubusercontent.com/input-output-hk/ghc-plinth/ghcup-channel/ghcup-plinth.yaml
+$ ghcup install plinth latest
+$ ghcup set plinth latest
+```
+
+`ghcup install` downloads the binary distribution for your platform and
+installs it under ghcup's own directory; `ghcup set` then symlinks `uplc-ghc`
+into ghcup's `bin` directory (`~/.ghcup/bin` by default), which is already on
+`PATH` for ghcup users. Verify with:
+
+```console
+$ uplc-ghc --version
+```
+
+Installing `plinth` does not affect any GHC installed by ghcup: the tool ships
+only the `uplc-*` binaries, so your regular `ghc` is left untouched.
+
+## Supported platforms
+
+Binary distributions are published for:
+
+- Linux, x86_64 and aarch64 (glibc, and musl/Alpine)
+- macOS, Apple Silicon
+- Windows, x86_64
+
+List the available versions with `ghcup list -t plinth`.
+
+Once installed, head over to
+[Use uplc-ghc in a project]({% link how-to/use.md %}).

how-to/test.md

@@ -190,7 +190,7 @@ experimentation, not production.
   `unsafeApplyCode`.
 - [How smart contracts run: Plutus Core and the CEK machine]({% link explanation/plutus-core.md %})
   — why off-chain evaluation and costing are faithful to the chain.
-- [Install Plinth standalone compiler]({% link how-to/build.md %}) — the
+- [Build Plinth from source]({% link how-to/build.md %}) — the
   tasty/golden test mechanism the compiler's own suites use.
 - [Generate a blueprint]({% link how-to/generate-blueprint.md %}) — the
   other main thing off-chain code does with a `CompiledCode`.

how-to/use.md

@@ -4,7 +4,7 @@ permalink: /how-to/use/
 ---
 
 The recommended way to use the Plinth standalone compiler is to set it once in
-`cabal.project`. If you [installed it via ghcup]({% link how-to/build.md %})
+`cabal.project`. If you [installed it via ghcup]({% link how-to/install.md %})
 (the recommended way), `uplc-ghc` is on `PATH` and its name alone is enough:
 
 ```haskell

reference/index.md

@@ -7,4 +7,4 @@ from or follow as a procedure.
 
 There are no reference pages yet. The build script's prerequisites, options, and
 outputs currently live in
-[Install Plinth standalone compiler]({% link how-to/build.md %}).
+[Build Plinth from source]({% link how-to/build.md %}).

tutorials/first-smart-contract.md

@@ -13,7 +13,7 @@ later.
 ## Before you start
 
 You need `uplc-ghc` installed. If you do not have it yet, follow
-[Install Plinth standalone compiler]({% link how-to/build.md %}) first —
+[Install Plinth standalone compiler]({% link how-to/install.md %}) first —
 this tutorial waits for you here. If you installed it via ghcup (the
 recommended way), the binary is simply `uplc-ghc` on your `PATH`: wherever
 this tutorial says `/path/to/uplc-ghc`, write plain `uplc-ghc` instead. If