zio · adamgfraser · Apr 12, 2023 · Apr 10, 2023 · Apr 11, 2023 · Apr 11, 2023
diff --git a/build.sbt b/build.sbt
@@ -789,8 +789,9 @@ lazy val docs = project.module
     scalacOptions ~= { _ filterNot (_ startsWith "-Ywarn") },
     scalacOptions ~= { _ filterNot (_ startsWith "-Xlint") },
     crossScalaVersions --= List(Scala212, Scala3),
-    mdocIn  := (LocalRootProject / baseDirectory).value / "docs",
-    mdocOut := (LocalRootProject / baseDirectory).value / "website" / "docs",
+    mdocIn             := (LocalRootProject / baseDirectory).value / "docs",
+    mdocOut            := (LocalRootProject / baseDirectory).value / "website" / "docs",
+    mdocExtraArguments := Seq("--check-link-hygiene"),
     ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(
       core.jvm,
       streams.jvm,

diff --git a/docs/contributing-to-documentation.md b/docs/contributing-to-documentation.md
@@ -6,7 +6,7 @@ title: "Contributing to The ZIO Documentation"
 
 The ZIO documentation is provided by a worldwide community, just like the project itself. So if you are reading this page, you can help us to improve the documentation.
 
-Please read the [Contributor Guideline](contributing.md) before contributing to documentation.
+Please read the [Contributor Guideline](contributor-guidelines.md) before contributing to documentation.
 
 ## Toolchain
 
@@ -78,7 +78,7 @@ npm run start --watch
 
 It will be served on [localhost](http://127.0.0.1:3000/) address.
 
-5. When we are finished with the documentation, we can commit those changes and [create a pull request](contributing.md#create-a-pull-request).
+5. When we are finished with the documentation, we can commit those changes and [create a pull request](contributor-guidelines.md#create-a-pull-request).
 
 
 ## Giving Feedback

diff --git a/docs/ecosystem/officials/index.md b/docs/ecosystem/officials/index.md
@@ -3,7 +3,7 @@ id: index
 title: "ZIO Ecosystem Official Libraries"
 ---
 
-Official ZIO libraries are hosted in the [ZIO organization](https://github.com/zio/) on Github, and are generally maintained by core contributors to ZIO.
+Official ZIO libraries are hosted in the [ZIO organization](https://github.com/zio/) on GitHub, and are generally maintained by core contributors to ZIO.
 
 ## Development Status
 

diff --git a/docs/guides/migrate/migration-guide.md b/docs/guides/migrate/migration-guide.md
@@ -2686,7 +2686,7 @@ for {
 } yield ()
 ```
 
-Visit the [Hub](../../reference/concurrency/hub) page to learn more about it.
+Visit the [Hub](../../reference/concurrency/hub.md) page to learn more about it.
 
 ### ZIO Aspects
 

diff --git a/docs/reference/di/examples.md b/docs/reference/di/examples.md
@@ -245,7 +245,7 @@ object MainApp extends ZIOAppDefault {
 
 ## An Example of How to Get Fresh Layers
 
-Having covered the topic of [acquiring fresh layers](#acquiring-a-fresh-version), let's see an example of using the `ZLayer#fresh` operator.
+Having covered the topic of [acquiring fresh layers](../../reference/di/dependency-memoization.md#acquiring-a-fresh-version), let's see an example of using the `ZLayer#fresh` operator.
 
 `DocumentRepo` and `UserRepo` services are dependent on an in-memory cache service. On the other hand, let's assume the cache service is quite simple, and we might be prone to cache conflicts between services. While sharing the cache service may cause some problems for our business logic, we should separate the cache service for both `DocumentRepo` and `UserRepo`:
 
@@ -268,7 +268,7 @@ object MainApp extends ZIOAppDefault {
 
 ## An Example of Pass-through Dependencies
 
-Notice that in the previous examples, both `UserRepo` and `DocuemntRepo` have some [hidden dependencies](#hidden-versus-passed-through-dependencies), such as `Cache`, `Database`, and `BlobStorage`.  So these hidden dependencies are no longer expressed in the type signature of the `layers`. From the perspective of a caller, `layers` just outputs a `UserRepo` and `DocuemntRepo` and requires no inputs. The caller does not need to be concerned with the internal implementation details of how the `UserRepo` and `DocumentRepo` are constructed.
+Notice that in the previous examples, both `UserRepo` and `DocuemntRepo` have some [hidden dependencies](../../reference/di/manual-layer-construction.md#hidden-versus-passed-through-dependencies), such as `Cache`, `Database`, and `BlobStorage`.  So these hidden dependencies are no longer expressed in the type signature of the `layers`. From the perspective of a caller, `layers` just outputs a `UserRepo` and `DocuemntRepo` and requires no inputs. The caller does not need to be concerned with the internal implementation details of how the `UserRepo` and `DocumentRepo` are constructed.
 
 An upstream dependency that is used by many other services can be "passed-through" and included in a layer's output. This can be done with the `>+>` operator, which provides the output of one layer to another layer, returning a new layer that outputs the services of _both_.
 
@@ -295,7 +295,7 @@ object MainApp extends ZIOAppDefault {
 
 ## An Example of Updating Hidden Dependencies
 
-One of the use cases of having explicit all dependencies in the final layer is that we can [update](#updating-local-dependencies) those hidden layers using `ZLayer#update`. In the following example, we are replacing the `InmemoryCache` with another implementation called `PersistentCache`:
+One of the use cases of having explicit all dependencies in the final layer is that we can [update](../../reference/di/examples.md#an-example-of-updating-hidden-dependencies) those hidden layers using `ZLayer#update`. In the following example, we are replacing the `InmemoryCache` with another implementation called `PersistentCache`:
 
 ```scala mdoc:compile-only
 import zio._

diff --git a/docs/reference/error-management/recovering/catching.md b/docs/reference/error-management/recovering/catching.md
@@ -273,7 +273,7 @@ trait ZIO[-R, +E, +A] {
 }
 ```
 
-In case of occurring any [fatal error](#3-fatal-errors), it will die.
+In case of occurring any [fatal error](#catching-traces), it will die.
 
 ```scala
 openFile("data.json").catchNonFatalOrDie(_ => openFile("backup.json"))

diff --git a/docs/reference/fiber/fiber.md b/docs/reference/fiber/fiber.md
@@ -556,7 +556,7 @@ for {
 
 ### Interrupting Blocking Operations
 
-The `ZIO#attemptBlocking` is interruptible by default, but its interruption will not translate to JVM thread interruption. Instead, we can use `ZIO#attemptBlockingInterrupt` to translate the ZIO interruption of that effect into JVM thread interruption. For details and examples on interrupting blocking operations see [here](../core/zio/zio.md#blocking-operations).
+The `ZIO#attemptBlocking` is interruptible by default, but its interruption will not translate to JVM thread interruption. Instead, we can use `ZIO#attemptBlockingInterrupt` to translate the ZIO interruption of that effect into JVM thread interruption. For details and examples on interrupting blocking operations see [here](../core/zio/zio.md#blocking-synchronous-side-effects).
 
 ### Automatic Interruption
 
@@ -613,7 +613,7 @@ Fibers are designed to be **cooperative** which means that **they will yield to
 
 What if though, we have a CPU Work operation that takes a really long time to run? Let's say 30 seconds it does pure CPU Work very computationally intensive? What happens if we take that single gigantic function and put that into a `ZIO#attempt`? In that case there is no way for the ZIO Runtime to force that fiber to yield to other fibers. In this situation, the ZIO Runtime cannot preserve some level of fairness, and that single big CPU operation monopolizes the underlying thread. It is not a good practice to monopolize the underlying thread.
 
-ZIO has a special thread pool that can be used to do these computations. That's the **blocking thread pool**. The `ZIO#blocking` operator and its variants (see [here](../core/zio/#blocking-operations)) can be used to run a big CPU Work on a dedicated thread. So, it doesn't interfere with all the other work that is going on simultaneously in the ZIO Runtime system.
+ZIO has a special thread pool that can be used to do these computations. That's the **blocking thread pool**. The `ZIO#blocking` operator and its variants (see [here](../core/zio/zio.md#blocking-synchronous-side-effects)) can be used to run a big CPU Work on a dedicated thread. So, it doesn't interfere with all the other work that is going on simultaneously in the ZIO Runtime system.
 
 If a CPU Work doesn't yield quickly, then that is going to monopolize a thread. So how can we determine that our CPU Work can yield quickly or not? 
 - If that overall CPU Work composes many ZIO operations, then due to the composition of ZIO operations, it has a chance to yield quickly to other fibers and doesn't monopolize a thread.

diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -107,7 +107,7 @@ IO supports 5 types of Metrics:
 - **[Gauge](observability/metrics/gauge.md)** — The gauge is a single numerical value that can arbitrary goes up or down over time like _memory usage_.
 - **[Histogram](observability/metrics/histogram.md)** — The Histogram is used to track the distribution of a set of observed values across a set of buckets like _request latencies_.
 - **[Summary](observability/metrics/summary.md)** — The Summary represents a sliding window of a time series along with metrics for certain percentiles of the time series, referred to as quantiles like _request latencies_.
-- **[Frequency](observability/metrics/setcount.md)** — The Frequency is a metric that counts the number of occurrences of distinct string values.
+- **[Frequency](observability/metrics/frequency.md)** — The Frequency is a metric that counts the number of occurrences of distinct string values.
 
 ## Testing
 

diff --git a/docs/reference/observability/logging.md b/docs/reference/observability/logging.md
@@ -58,6 +58,6 @@ ZIO Logging calculates the running duration of that span and includes that in th
 
 ## Further Reading
 
-* [ZIO Logging](../../ecosystem/officials/zio-logging.md)
+* [ZIO Logging](../../ecosystem/officials/index.md)
 * [How to Enable Logging in a ZIO Application](../../guides/tutorials/enable-logging-in-a-zio-application.md)
 * [How to Create a Custom Logger for a ZIO Application?](../../guides/tutorials/create-custom-logger-for-a-zio-application.md)
diff --git a/docs/reference/observability/metrics/index.md b/docs/reference/observability/metrics/index.md
@@ -13,7 +13,7 @@ ZIO supports 5 types of Metrics:
 * **[Gauge](gauge.md)** — The gauge is a single numerical value that can arbitrary goes up or down over time like _memory usage_.
 * **[Histogram](histogram.md)** — The Histogram is used to track the distribution of a set of observed values across a set of buckets like _request latencies_.
 * **[Summary](summary.md)** — The Summary represents a sliding window of a time series along with metrics for certain percentiles of the time series, referred to as quantiles like _request latencies_.
-* **[Frequency](setcount.md)** — The Frequency is a metric that counts the number of occurrences of distinct string values.
+* **[Frequency](frequency.md)** — The Frequency is a metric that counts the number of occurrences of distinct string values.
 
 All ZIO Metrics are defined in the form of ZIO Aspects that can be applied to effects without changing the signature of the effect it is applied to:
 

diff --git a/docs/reference/observability/tracing.md b/docs/reference/observability/tracing.md
@@ -8,4 +8,4 @@ Although logs and metrics are useful to understand the behavior of individual se
 
 In a distributed system, a request can span multiple services and each service can make multiple requests to other services to fulfill the request. In such a scenario, we need to have a way to track the lifetime of a request across multiple services to diagnose what services are the bottlenecks and where the request is spending most of its time.
 
-ZIO Telemetry supports tracing through the OpenTelemetry API. To learn more about tracing, please refer to the ZIO Telemetry [documentation](../../ecosystem/officials/zio-telemetry.md).
+ZIO Telemetry supports tracing through the OpenTelemetry API. To learn more about tracing, please refer to the ZIO Telemetry [documentation](../../ecosystem/officials/index.md).
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -122,7 +122,7 @@ const config = {
             },
             {
               label: 'Contributing to The ZIO Documentation',
-              href: '/contributing-to-the-documentation'
+              href: '/contributing-to-documentation'
             },
             {
               label: 'Coding Guidelines',
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,4 +8,4 @@ Although logs and metrics are useful to understand the behavior of individual se

		In a distributed system, a request can span multiple services and each service can make multiple requests to other services to fulfill the request. In such a scenario, we need to have a way to track the lifetime of a request across multiple services to diagnose what services are the bottlenecks and where the request is spending most of its time.

		ZIO Telemetry supports tracing through the OpenTelemetry API. To learn more about tracing, please refer to the ZIO Telemetry [documentation](../../ecosystem/officials/zio-telemetry.md).
		ZIO Telemetry supports tracing through the OpenTelemetry API. To learn more about tracing, please refer to the ZIO Telemetry [documentation](../../ecosystem/officials/index.md).