From d9ee97a0b7e02924484ce4723ece8ac91cc5a792 Mon Sep 17 00:00:00 2001
From: Brian McGee <brian@bmcgee.ie>
Date: Wed, 1 May 2024 14:00:06 +0100
Subject: [PATCH] doc: refine formatter spec

Signed-off-by: Brian McGee <brian@bmcgee.ie>
---
 docs/.vitepress/config.mts |  2 +-
 docs/formatter-spec.md     | 26 ++++++++++++++------------
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index df8f9e7..e4a7295 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -18,7 +18,7 @@ export default defineConfig({
       { text: 'Quick Start', link: '/quick-start' },
       { text: 'Overview', link: '/overview' },
       { text: 'Usage', link: '/usage' },
-      { text: 'Formatter Spec', link: '/formatter-spec' },
+      { text: 'Formatter Specification', link: '/formatter-spec' },
       { text: 'Contributing', link: '/contributing' },
       { text: 'FAQ', link: '/faq' },
     ],
diff --git a/docs/formatter-spec.md b/docs/formatter-spec.md
index a536f4b..0b3c5f6 100644
--- a/docs/formatter-spec.md
+++ b/docs/formatter-spec.md
@@ -4,19 +4,22 @@ outline: deep
 
 # Formatter Specification
 
-In order to keep the design of `treefmt` simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.
+In order to keep the design of `treefmt` simple, we only supports formatters that adhere to a certain standard. This
+document outlines that standard.
+
+If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script
+that transforms the usage to match the specification.
 
 In this design, we rely on `treefmt` to do the tree traversal, and only invoke
 the code formatter on the selected files.
 
 ## Rules
 
-In order for the formatter to comply to this spec, it MUST follow the
-following rules:
+In order for the formatter to comply to this spec, it **MUST** comply with the following:
 
 ### 1. Files passed as arguments
 
-In order to be integrated to `treefmt`'s workflow, the formatter's CLI must adhere to the following specification:
+In order to be integrated with `treefmt`'s workflow, the formatter's CLI must be of the form:
 
 ```
 <command> [options] [...<files>]
@@ -34,22 +37,21 @@ Example:
 $ rustfmt --edition 2018 src/main.rs src/lib.rs
 ```
 
-It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.
+> [!IMPORTANT]
+> It _SHOULD_ processes only the specified files. Files that are not passed _SHOULD_ never be formatted.
 
 ### 2. Write to changed files
 
-Whenever there is a change to the code formatting, the code formatter MUST
-write to the changes back to the original location.
+Whenever there is a change to the code formatting, the code formatter **MUST** write to the changes back to the
+original location.
 
-If there is no changes to the original file, the formatter MUST NOT write to
-the original location.
+If there is no changes to the original file, the formatter **MUST** NOT write to the original location.
 
 ### 3. Idempotent
 
-The code formatter SHOULD be indempotent. Meaning that it produces stable
+The code formatter _SHOULD_ be indempotent. Meaning that it produces stable
 outputs.
 
 ### 4. Reliable
 
-We expect the formatter to be reliable and not break the semantic of the
-formatted files.
+We expect the formatter to be reliable and not break the semantics of the formatted files.