website: updates

Author: ilg-ul

website/docs/getting-started/index.mdx

@@ -46,33 +46,33 @@ import ReleaseSchedule from './_release-schedule.mdx'
 To be **reproducible**, an operation must remain stable over time and
 across different environments. In other words, if builds are repeated
 after some time, possibly on a different machine or platform, the
-resulting behavior must be functionally equivalent.
+resulting behaviour must be functionally equivalent.
 
 </details>
 
 <Overview/>
 
 
 
-## What are xpm packages? (xPacks)
+## What are xpm packages? (xPacks) {#xpm-packages}
 
 **xpm packages**, abbreviated as **xPacks**, are versatile,
 language-neutral software packages. They have been successfully
 utilised in C/C++ projects.
 
 <details>
-<summary>What the heck are xpm packages / xPacks? Please, do not introduce another package format!</summary>
+<summary>What the heck are xpm packages (xPacks)? Please, do not introduce another package format!</summary>
 
-While the initial appearance may seem complex, utilizing
+Although the initial appearance may seem complex, utilising
 xpm packages is, in fact, straightforward.
 The design rationale is to automate frequent
-operations that occur during software development, in this case the
+operations that occur during software development, such as the
 installation of
 dependencies, and to ensure reproducibility.
 
 These packages are managed by **[xpm](https://xpack.github.io/xpm/)**
 (the xPack Project Manager),
-a program that complements the **[npm](https://docs.npmjs.com/cli/)** CLI
+a programme that complements the **[npm](https://docs.npmjs.com/cli/)** CLI
 (the popular JavaScript package manager), with new language-neutral features.
 
 The xPacks Framework **does NOT introduce a new package format**; instead,
@@ -87,34 +87,40 @@ are extracted into separate folders within the project.
 
 Based on the content, there are two types of xpm packages:
 
-- **source packages** (that install source files, usually libraries) and
-- **binary packages** (that install executables/binary files, usually tools).
+- packages with source libraries (**source** xpm packages)
+- packages with executables, usually platform-specific binary
+tools (**binary** xpm packages)
 
-Binary packages include references to archives with the platform specific
-binaries (such as `.tar.gz` for Unix or `.zip` for Windows).
+**Source xpm packages** are regular npm packages that include **library
+source files**, typically in **C/C++**, though there are no language
+restrictions.
 
-These archives are also expanded along the package metadata. Since they
-include executables, links/forwarders to
+**Binary xpm packages** are also regular npm packages, but with minimal
+content, typically just the `package.json` file. Since these packages
+provide executables for multiple platforms, some of which are quite
+large, it is not practical to include all binaries within the npm
+package itself. Instead, the `package.json` file contains references
+(URLs) to platform-specific binary archives (e.g., `.tar.gz` for Unix or
+`.zip` for Windows).
+
+These archives are also expanded along with the package metadata.
+Links/forwarders to
 these executables are created in a `.bin` folder,
 eliminating the need to add multiple folders to the `PATH`.
 
-Given that some binary packages, such as toolchains, can have very large
-archives, the packages are extracted only once into a user global location to
-conserve space. In projects, instead of duplicating the content of these
-archives, symbolic links are created.
-
-Simply put, xpm packages can be used to further automate the
-installation of source libraries and tools.
+In summary, xpm packages can enhance and automate the installation
+process for source libraries and tools.
 
 </details>
 
 ## Features
 
 All binaries are:
 
-- **self-contained** (include all required libraries)
-- **file-system relocatable** (can be installed in any location)
-- built on slightly older systems (to make them run on both old and new systems)
+- **Self-contained** (include all required libraries).
+- **File-system relocatable** (can be installed in any location).
+- Built on slightly older systems (to ensure compatibility with both
+old and new systems).
 
 <details>
 <summary>Compatibility with older systems</summary>
@@ -143,17 +149,17 @@ location, including in user folders.
 
 The main advantages of using the **xPack Binary Development Tools** are:
 
-- a convenient, uniform and portable install/uninstall/upgrade
+- A convenient, uniform and portable install/uninstall/upgrade
 procedure; the same procedure is used for all major
-  platforms (**x64 Windows**, **x64 macOS**, **arm64 macOS**, **x64 GNU/Linux**, **arm64 GNU/Linux**, **arm GNU/Linux**)
-- multiple versions of the same package can be installed at the same time on
-  the same system
-- no need to worry about dependent libraries, they are all included
-- not affected by system updates that
-  might change the versions of the dependent libraries
-- significantly lighter and easier to use than Docker images that provide
-  similar functionality and are GNU/Linux centric
-- projects can be tied to specific tools versions; this provides a good
+  platforms (**x64 Windows**, **x64 macOS**, **arm64 macOS**, **x64 GNU/Linux**, **arm64 GNU/Linux**, **arm GNU/Linux**).
+- Multiple versions of the same package can be installed at the same time on
+  the same system.
+- No need to worry about dependent libraries, they are all included.
+- Not affected by system updates that
+  might change the versions of the dependent libraries.
+- Significantly lighter and easier to use than Docker images that provide
+  similar functionality and are GNU/Linux centric.
+- Projects can be tied to specific tools versions; this provides a good
   reproducibility, especially useful in **CI/CD** environments.
 
 <OtherBenefits/>

website/docusaurus.config.ts

@@ -102,9 +102,12 @@ const config: Config = {
   organizationName: 'xpack-dev-tools', // Usually your GitHub org/user name.
   projectName: 'xpack-dev-tools.github.io', // Usually your repo name.
 
+  onBrokenAnchors: 'throw',
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'throw',
 
+  onDuplicateRoutes: 'throw',
+
   // Useful for the sitemap.xml, to avoid redirects, since
   // GitHub redirects all to trailing slash.
   trailingSlash: true,