Sync the reference docs somewhat in layout

Author: wkillerud

astro.config.mjs

@@ -16,7 +16,7 @@ export default defineConfig({
 					label: 'Introduction',
 					items: [
 						{ label: 'Getting started', link: '/introduction/getting-started/' },
-						{ label: 'Why MetricsJS', link: '/introduction/why-metrics-js/' },
+						{ label: 'Why MetricsJS', link: '/introduction/why-metricsjs/' },
 					],
 				},
 				{

src/content/docs/index.md

@@ -6,7 +6,7 @@ editUrl: false
 lastUpdated: false
 hero:
   title: Streaming metrics for Node.js
-  tagline: Gather metrics from your dependency tree
+  tagline: Gather metrics from your dependency tree, without dependency hell.
   image:
     file: ../../assets/metrics-js-logo.png
   actions:

src/content/docs/introduction/getting-started.md

@@ -2,23 +2,17 @@
 title: Getting started
 ---
 
+Metrics JS is an open source project for isolated instrumentation of independent modules. You can measure the things you feel are important, such as:
 
-
-MetricsJS consists of three main parts:
-
-1. A [client](../../reference/client/), which is the interface to produce metrics.
-2. A [guard](../../reference/guard/), which helps avoid excessive metric permutation creation in a stream.
-3. A [consumer](../../reference/prometheus-consumer/), which takes one or more metrics streams and sends data to a service such as Prometheus.
-
-The consumer and guard is something you typically set up once in the root of your application, while the client is used throughout your codebase.
-
-## Hello, MetricsJS
+- The time it takes to complete an operation.
+- The number of incoming requests.
+- The CPU load on the server.
 
 Let's go through an example where we produce and read some metrics.
 
-### Install dependencies
+## Install dependencies
 
-First, install the client, guard, and Prometheus client and consumer:
+First, install these packages:
 
 ```bash
 npm install @metrics/client \
@@ -27,7 +21,15 @@ npm install @metrics/client \
   prom-client
 ```
 
-### Generate metrics
+MetricsJS consists of three main parts:
+
+1. A [client](../../reference/client/), which is the interface to produce metrics.
+2. A [guard](../../reference/guard/), which helps avoid excessive metric permutation creation in a stream.
+3. A [consumer](../../reference/prometheus-consumer/), which takes one or more metrics streams and sends data to a service such as Prometheus.
+
+The consumer and guard is something you typically set up once in the root of your application, while the client is used throughout your codebase (or that of your dependencies).
+
+## Generate metrics
 
 The client supports 4 types of metric creation use cases:
 
@@ -53,7 +55,7 @@ counter.inc();
 
 See the [client reference](../../reference/client/) for API documentation and more examples.
 
-### Create a consumer
+## Create a consumer
 
 Create a Prometheus consumer singleton in the root of your application, and add a guard:
 
@@ -75,7 +77,7 @@ guard.on('drop', (metric) => {
 });
 ```
 
-### Pipe client data to the consumer
+## Pipe client data to the consumer
 
 MetricsJS works on streams, so you need to pipe the client data to the consumer:
 
@@ -96,9 +98,9 @@ Any number of streams can be piped to the consumer. In other words:
 
 See the [client reference](../../reference/client/#composing-metric-streams) for code examples.
 
-### Expose metrics
+## Read the metrics
 
-Finally, expose the metrics on an endpoint in your application for the Prometheus scraper:
+Finally, expose the metrics on an endpoint:
 
 ```js
 app.get('/metrics', (req, res) => {
@@ -107,3 +109,5 @@ app.get('/metrics', (req, res) => {
     );
 });
 ```
+
+This endpoint can be scraped by Prometheus.

src/content/docs/introduction/why-metrics-js.md renamed to src/content/docs/introduction/why-metricsjs.md

@@ -2,15 +2,7 @@
 title: Why MetricsJS?
 ---
 
-Metrics JS is an open source project for isolated instrumentation of independent modules.
-
-With Metrics JS, it's possible to instrument a Node.js module, measuring the things you feel are important such as:
-
-- The time it takes to complete an operation.
-- The number of incoming requests.
-- The CPU load on the server.
-
-You can measure these things without needing to know which system the metrics will be collected into. It's up to the final consumer to decide whether the metrics will be pushed to [Prometheus](../../reference/prometheus-consumer/), Data Dog or something else.
+With Metrics JS, it's possible to instrument a Node.js module, measuring the things you feel are important such as operation timing or counts, without needing to know which system the metrics will be collected into. It's up to the final consumer to decide whether the metrics will be pushed to Prometheus, Data Dog or something else.
 
 ## Resilient design
 

src/content/docs/reference/client.md

@@ -9,6 +9,46 @@ A streaming metric producer. Allows producing counters, gauges, time series in a
 
 Additionally, you can pipe together different metrics streams before finally consuming them all in a single location.
 
+## Usage
+
+```bash
+npm install @metrics/client
+```
+
+First, instantiate a new client:
+
+```js
+const Metrics = require('@metrics/client');
+
+const client = new Metrics();
+```
+
+Next, use the client for instrumentation:
+
+```js
+const counter = client.counter({
+    name: 'unique_metric_name',
+    description: 'Description of metric being collected',
+});
+
+counter.inc();
+```
+
+The client supports 4 types of metric creation use cases.
+
+-   Counters are supported via the `client.counter` method
+-   Gauges are supported via the `client.gauge` method
+-   Histograms are supported via the `client.histogram` method
+-   Summaries are supported via the `client.summary` method
+
+
+Lastly, the metrics stream needs to be piped to a consumer:
+
+```js
+client.pipe(consumer);
+```
+
+If you're writing a library, you skip this step. Instead, expose the `client` so your users can pipe the metrics to their chosen `consumer`.
 
 ## API
 
@@ -388,48 +428,6 @@ client.on('drop', (metric) => {
 });
 ```
 
-## Usage
-
-The client is intended to be used in the following way:
-
-### Step 1.
-
-Instantiate a new client
-
-```js
-const Metrics = require('@metrics/client');
-
-const client = new Metrics();
-```
-
-### Step 2.
-
-Use the client for instrumentation
-
-```js
-const counter = client.counter({
-    name: 'unique_metric_name',
-    description: 'Description of metric being collected',
-});
-
-counter.inc();
-```
-
-### Step 3.
-
-Pipe collected metrics to a collector
-
-```js
-client.pipe(consumer);
-```
-
-The client supports 4 types of metric creation use cases.
-
--   Counters are supported via the `client.counter` method
--   Gauges are supported via the `client.gauge` method
--   Histograms are supported via the `client.histogram` method
--   Summaries are supported via the `client.summary` method
-
 ## Examples
 
 ### Counter

src/content/docs/reference/daemon.md

@@ -4,16 +4,21 @@ tableOfContents:
   maxHeadingLevel: 4
 ---
 
-Daemon for collecting metrics over a network. Provides a stream for further piping of metrics.
+This module makes it possible to create a socket you can recieve metrics over. The socket can
+be of different protocols (UDP, TCP etc) but the data trasmitted over it is expected to be of
+the [`@metrics/metric`](../metric) type. The recieved metrics can
+be piped to other metric modules for further handling.
+
+For sending metrics over a socket you are expected to use the [`@metrics/emitter`](../emitter) module.
+
+The main purpose of this is to be able to collect metrics from multiple processes.
 
-## Installation
+## Usage
 
 ```bash
-$ npm install @metrics/daemon
+npm install @metrics/daemon
 ```
 
-## Example
-
 Set up a daemon with UDP on port 6000 as transport and pipes the incomming metrics into the [`@metrics/client`](https://github.com/metrics-js/client):
 
 ```js
@@ -28,18 +33,7 @@ daemon.pipe(client);
 daemon.listen();
 ```
 
-## Description
-
-This module makes it possible to create a socket one can recieve metrics over. The socket can
-be of different protocols (UDP, TCP etc) but the data trasmitted over it is expected to be of
-the [`@metrics/metric`](https://github.com/metrics-js/metric) type. The recieved metrics can
-be piped to other metric modules for further handling.
-
-For sending metrics over a socket one are expected to use the [`@metrics/emitter`](https://github.com/metrics-js/emitter) module.
-
-The main purpose of this is to be able to collect metrics from multiple processes. Here is a
-simplified example of each worker in a cluster pushing metrics to the master and the master
-pushing the metric further:
+Here is a simplified example of each worker in a cluster pushing metrics to the master and the master pushing the metric further:
 
 ```js
 const master = () => {
@@ -81,7 +75,10 @@ if (cluster.isWorker) {
 See the [cluster example](https://github.com/metrics-js/daemon/tree/master/example/cluster.js)
 in examples for a full example.
 
-## Constructor
+## API
+
+
+### constructor(options)
 
 Create a new Daemon instance.
 
@@ -90,26 +87,25 @@ const Daemon = require('@metrics/daemon');
 const daemon = new Daemon(transport, options);
 ```
 
-### transport (required)
+#### transport (required)
 
 What type of transport to use. Supported values are:
 
  * `udp` - For UDP transport.
 
-### options (optional)
+#### options (optional)
 
-An Object containing misc configuration for the selected transport. Please see each
-transport for which option which can be passed in.
+An Object containing misc configuration for the selected transport. Please see each transport for which option which can be passed in.
 
-### returns
+#### returns
 
 Returns a Readable stream in object mode.
 
-## API
-
 The Daemon instance has the following API:
 
-### .listen()
+### instance methods
+
+#### .listen()
 
 Starts the daemon with the selected transport.
 

src/content/docs/reference/emitter.md

@@ -4,16 +4,22 @@ tableOfContents:
   maxHeadingLevel: 4
 ---
 
-Emitter for sending metrics over a network to a [daemon](../daemon).
 
-## Installation
+This module makes it possible stream metrics over a socket to a daemon. The socket can
+be of different protocols (UDP, TCP etc) but the data trasmitted over it is expected to be of
+the [`@metrics/metric`](../metric) type.
+
+For recieving metrics over a socket one are expected to use the [`@metrics/daemon`](../daemon) module.
+
+The main purpose of this is to be able to send metrics from multiple processes to a sentral
+service (daemon) for further handling.
+
+## Usage
 
 ```bash
-$ npm install @metrics/emitter
+npm install @metrics/emitter
 ```
 
-## Example
-
 Set up an emitter which connects to a daemon on UDP on port 6000 and  pipes the metrics from the [`@metrics/client`](https://github.com/metrics-js/client):
 
 ```js
@@ -26,16 +32,7 @@ const client = new Client();
 client.pipe(emitter);
 ```
 
-## Description
-
-This module makes it possible stream metrics over a socket to a daemon. The socket can
-be of different protocols (UDP, TCP etc) but the data trasmitted over it is expected to be of
-the [`@metrics/metric`](https://github.com/metrics-js/metric) type.
-
-For recieving metrics over a socket one are expected to use the [`@metrics/daemon`](https://github.com/metrics-js/daemon) module.
-
-The main purpose of this is to be able to send metrics from multiple processes to a sentral
-service (daemon) for further handling. Here is a simplified example of each worker in a
+Here is a simplified example of each worker in a
 cluster pushing metrics to the master and the master pushing the metric further:
 
 ```js
@@ -78,7 +75,9 @@ if (cluster.isWorker) {
 See the [cluster example](https://github.com/metrics-js/daemon/tree/master/example/cluster.js)
 in daemon for a full example.
 
-## Constructor
+## API
+
+### constructor(options)
 
 Create a new Emitter instance.
 
@@ -87,18 +86,18 @@ const Emitter = require('@metrics/emitter');
 const emitter = new Emitter(transport, options);
 ```
 
-### transport (required)
+#### transport (required)
 
 What type of transport to use. Supported values are:
 
  * `udp` - For UDP transport.
 
-### options (optional)
+#### options (optional)
 
 An Object containing misc configuration for the selected transport. Please see each
 transport for which option which can be passed in.
 
-### returns
+#### returns
 
 Returns a Writable stream in object mode.