style: apply mdformat to docs

orestis-z · claude · orestis-z · commit ab043d777ff7 · 2026-07-11T17:17:30.000Z
Co-Authored-By: Claude Sonnet 4.6 (1M context) &lt;noreply@anthropic.com&gt;
Signed-off-by: Orestis Zambounis &lt;orestis.zambounis@gmail.com&gt;
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
@@ -1,7 +1,6 @@
----
-name: pr-review
-description: Review a GitHub PR with design-first analysis, posted as a GitHub review.
----
+______________________________________________________________________
+
+## name: pr-review description: Review a GitHub PR with design-first analysis, posted as a GitHub review.
 
 # PR Review
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,12 +21,7 @@ To make the contribution process as smooth as possible, we ask that you coordina
 
 ### When should you check in?
 
-| **Let's chat first if...**                      | **Feel free to dive right in for...**   |
-| :---------------------------------------------- | :-------------------------------------- |
-| Adding new training algorithms or model support | Fixing typos or improving documentation |
-| Modifying the data pipeline or CLI/API          | Small bug fixes (generally < 20 lines)  |
-| Large refactors or performance optimizations    | Adding missing type annotations         |
-| Changes affecting 3+ files                      | Minor dependency updates                |
+| **Let's chat first if...** | **Feel free to dive right in for...** | | :---------------------------------------------- | :-------------------------------------- | | Adding new training algorithms or model support | Fixing typos or improving documentation | | Modifying the data pipeline or CLI/API | Small bug fixes (generally < 20 lines) | | Large refactors or performance optimizations | Adding missing type annotations | | Changes affecting 3+ files | Minor dependency updates |
 
 *Maintainers typically respond in 2-3 business days. If you haven’t heard from us after a week, please feel free to give the thread a nudge!*
 
diff --git a/README.md b/README.md
@@ -59,8 +59,7 @@ ______________________________________________________________________
 - **Standardized, Extensible Format:** Provides a Hugging Face-compatible format for defining speculative models, with tools to convert from external research repositories into a standard speculators format for easy adoption.
 - **Seamless vLLM Integration:** Built for direct deployment into vLLM, enabling low-latency, production-grade inference with minimal overhead.
 
-> [!TIP]
-> Read more about Speculators features in this [vLLM blog post](https://blog.vllm.ai/2025/12/13/speculators-v030.html).
+> [!TIP] Read more about Speculators features in this [vLLM blog post](https://blog.vllm.ai/2025/12/13/speculators-v030.html).
 
 ## Supported Models
 
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -2,5 +2,4 @@
 
 This section contains the auto-generated Python API documentation for Speculators.
 
-!!! warning
-    Using the Python API directly is **not officially supported** at this time and there are **no guarantees of backward compatibility** between releases. We recommend using the [CLI commands](../cli/index.md) as the primary entrypoints for interacting with Speculators.
+!!! warning Using the Python API directly is **not officially supported** at this time and there are **no guarantees of backward compatibility** between releases. We recommend using the [CLI commands](../cli/index.md) as the primary entrypoints for interacting with Speculators.
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -6,13 +6,7 @@ This page provides a comprehensive reference for all command-line interface (CLI
 
 Speculators provides the following CLI scripts for different stages of the speculative decoding workflow:
 
-| Script                       | Purpose                                                      | Reference                               |
-| ---------------------------- | ------------------------------------------------------------ | --------------------------------------- |
-| `prepare_data.py`            | Preprocess and tokenize datasets for training                | [→ Details](prepare_data.md)            |
-| `data_generation_offline.py` | Generate hidden states offline using vLLM                    | [→ Details](data_generation_offline.md) |
-| `launch_vllm.py`             | Launch vLLM server configured for hidden states extraction   | [→ Details](launch_vllm.md)             |
-| `train.py`                   | Train speculator models with online or offline hidden states | [→ Details](train.md)                   |
-| `response_regeneration/`     | Regenerate dataset responses using a vLLM-served model       | [→ Details](response_regeneration.md)   |
+| Script | Purpose | Reference | | ---------------------------- | ------------------------------------------------------------ | --------------------------------------- | | `prepare_data.py` | Preprocess and tokenize datasets for training | [→ Details](prepare_data.md) | | `data_generation_offline.py` | Generate hidden states offline using vLLM | [→ Details](data_generation_offline.md) | | `launch_vllm.py` | Launch vLLM server configured for hidden states extraction | [→ Details](launch_vllm.md) | | `train.py` | Train speculator models with online or offline hidden states | [→ Details](train.md) | | `response_regeneration/` | Regenerate dataset responses using a vLLM-served model | [→ Details](response_regeneration.md) |
 
 ## Common Workflows
 
diff --git a/docs/cli/response_regeneration.md b/docs/cli/response_regeneration.md
@@ -4,10 +4,7 @@ Regenerates assistant responses in existing datasets using a vLLM-served model.
 
 The pipeline consists of two scripts:
 
-| Script       | Purpose                                                        |
-| ------------ | -------------------------------------------------------------- |
-| `run_all.sh` | End-to-end pipeline: starts vLLM, regenerates responses, stops |
-| `script.py`  | Standalone response regeneration against a running vLLM server |
+| Script | Purpose | | ------------ | -------------------------------------------------------------- | | `run_all.sh` | End-to-end pipeline: starts vLLM, regenerates responses, stops | | `script.py` | Standalone response regeneration against a running vLLM server |
 
 ## run_all.sh
 
@@ -110,10 +107,7 @@ python scripts/response_regeneration/script.py \
 
 ## Supported Datasets
 
-| Dataset   | HuggingFace ID                                    | Prompt Field  | Default Split |
-| --------- | ------------------------------------------------- | ------------- | ------------- |
-| Magpie    | `Magpie-Align/Magpie-Llama-3.1-Pro-300K-Filtered` | `instruction` | `train`       |
-| UltraChat | `HuggingFaceH4/ultrachat_200k`                    | `prompt`      | `train_sft`   |
+| Dataset | HuggingFace ID | Prompt Field | Default Split | | --------- | ------------------------------------------------- | ------------- | ------------- | | Magpie | `Magpie-Align/Magpie-Llama-3.1-Pro-300K-Filtered` | `instruction` | `train` | | UltraChat | `HuggingFaceH4/ultrachat_200k` | `prompt` | `train_sft` |
 
 ## Output Format
 
diff --git a/docs/developer/branding.md b/docs/developer/branding.md
@@ -37,21 +37,7 @@ Speculators is an open, unified library for creating and storing speculative dec
 
 All files reside in `docs/assets/branding`.
 
-| Category   | Variant / Name    | SVG                                                                                                     | PNG                                                                                                     | Notes                           |
-| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| Logo       | Black             | [`speculators-logo-black.svg`](../assets/branding/speculators-logo-black.svg)                           | [`speculators-logo-black.png`](../assets/branding/speculators-logo-black.png)                           | Default on light backgrounds    |
-| Logo       | Blue              | [`speculators-logo-blue.svg`](../assets/branding/speculators-logo-blue.svg)                             | [`speculators-logo-blue.png`](../assets/branding/speculators-logo-blue.png)                             | Accent / section headers        |
-| Logo       | White             | [`speculators-logo-white.svg`](../assets/branding/speculators-logo-white.svg)                           | [`speculators-logo-white.png`](../assets/branding/speculators-logo-white.png)                           | Use on dark imagery/backgrounds |
-| Icon       | Black             | [`speculators-icon-black.svg`](../assets/branding/speculators-icon-black.svg)                           | [`speculators-icon-black.png`](../assets/branding/speculators-icon-black.png)                           | App tile / light UI             |
-| Icon       | Blue              | [`speculators-icon-blue.svg`](../assets/branding/speculators-icon-blue.svg)                             | [`speculators-icon-blue.png`](../assets/branding/speculators-icon-blue.png)                             | Accent                          |
-| Icon       | White             | [`speculators-icon-white.svg`](../assets/branding/speculators-icon-white.svg)                           | [`speculators-icon-white.png`](../assets/branding/speculators-icon-white.png)                           | Dark backgrounds                |
-| Icon       | White-Orange      | [`speculators-icon-white-orange.svg`](../assets/branding/speculators-icon-white-orange.svg)             | [`speculators-icon-white-orange.png`](../assets/branding/speculators-icon-white-orange.png)             | Limited highlight               |
-| Model Icon | Black             | [`speculators-model-icon-black.svg`](../assets/branding/speculators-model-icon-black.svg)               | [`speculators-model-icon-black.png`](../assets/branding/speculators-model-icon-black.png)               | Architecture visuals            |
-| Model Icon | Blue              | [`speculators-model-icon-blue.svg`](../assets/branding/speculators-model-icon-blue.svg)                 | [`speculators-model-icon-blue.png`](../assets/branding/speculators-model-icon-blue.png)                 | Architecture visuals            |
-| Model Icon | White             | [`speculators-model-icon-white.svg`](../assets/branding/speculators-model-icon-white.svg)               | [`speculators-model-icon-white.png`](../assets/branding/speculators-model-icon-white.png)               | Dark backgrounds                |
-| Model Icon | White-Orange      | [`speculators-model-icon-white-orange.svg`](../assets/branding/speculators-model-icon-white-orange.svg) | [`speculators-model-icon-white-orange.png`](../assets/branding/speculators-model-icon-white-orange.png) | Highlight sparingly             |
-| Diagram    | User Flow (Light) | [`speculators-user-flow-light.svg`](../assets/branding/speculators-user-flow-light.svg)                 | [`speculators-user-flow-light.png`](../assets/branding/speculators-user-flow-light.png)                 | Light docs / print              |
-| Diagram    | User Flow (Dark)  | [`speculators-user-flow-dark.svg`](../assets/branding/speculators-user-flow-dark.svg)                   | [`speculators-user-flow-dark.png`](../assets/branding/speculators-user-flow-dark.png)                   | Dark slides / sites             |
+| Category | Variant / Name | SVG | PNG | Notes | | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------- | | Logo | Black | [`speculators-logo-black.svg`](../assets/branding/speculators-logo-black.svg) | [`speculators-logo-black.png`](../assets/branding/speculators-logo-black.png) | Default on light backgrounds | | Logo | Blue | [`speculators-logo-blue.svg`](../assets/branding/speculators-logo-blue.svg) | [`speculators-logo-blue.png`](../assets/branding/speculators-logo-blue.png) | Accent / section headers | | Logo | White | [`speculators-logo-white.svg`](../assets/branding/speculators-logo-white.svg) | [`speculators-logo-white.png`](../assets/branding/speculators-logo-white.png) | Use on dark imagery/backgrounds | | Icon | Black | [`speculators-icon-black.svg`](../assets/branding/speculators-icon-black.svg) | [`speculators-icon-black.png`](../assets/branding/speculators-icon-black.png) | App tile / light UI | | Icon | Blue | [`speculators-icon-blue.svg`](../assets/branding/speculators-icon-blue.svg) | [`speculators-icon-blue.png`](../assets/branding/speculators-icon-blue.png) | Accent | | Icon | White | [`speculators-icon-white.svg`](../assets/branding/speculators-icon-white.svg) | [`speculators-icon-white.png`](../assets/branding/speculators-icon-white.png) | Dark backgrounds | | Icon | White-Orange | [`speculators-icon-white-orange.svg`](../assets/branding/speculators-icon-white-orange.svg) | [`speculators-icon-white-orange.png`](../assets/branding/speculators-icon-white-orange.png) | Limited highlight | | Model Icon | Black | [`speculators-model-icon-black.svg`](../assets/branding/speculators-model-icon-black.svg) | [`speculators-model-icon-black.png`](../assets/branding/speculators-model-icon-black.png) | Architecture visuals | | Model Icon | Blue | [`speculators-model-icon-blue.svg`](../assets/branding/speculators-model-icon-blue.svg) | [`speculators-model-icon-blue.png`](../assets/branding/speculators-model-icon-blue.png) | Architecture visuals | | Model Icon | White | [`speculators-model-icon-white.svg`](../assets/branding/speculators-model-icon-white.svg) | [`speculators-model-icon-white.png`](../assets/branding/speculators-model-icon-white.png) | Dark backgrounds | | Model Icon | White-Orange | [`speculators-model-icon-white-orange.svg`](../assets/branding/speculators-model-icon-white-orange.svg) | [`speculators-model-icon-white-orange.png`](../assets/branding/speculators-model-icon-white-orange.png) | Highlight sparingly | | Diagram | User Flow (Light) | [`speculators-user-flow-light.svg`](../assets/branding/speculators-user-flow-light.svg) | [`speculators-user-flow-light.png`](../assets/branding/speculators-user-flow-light.png) | Light docs / print | | Diagram | User Flow (Dark) | [`speculators-user-flow-dark.svg`](../assets/branding/speculators-user-flow-dark.svg) | [`speculators-user-flow-dark.png`](../assets/branding/speculators-user-flow-dark.png) | Dark slides / sites |
 
 ## Usage Guidelines
 
@@ -81,13 +67,7 @@ All files reside in `docs/assets/branding`.
 
 ## Do and Avoid
 
-| Do                                    | Avoid                              |
-| ------------------------------------- | ---------------------------------- |
-| Use supplied SVG for scalable quality | Recreating marks from scratch      |
-| Maintain clear space and aspect ratio | Distorting, squeezing, or rotating |
-| Choose color for sufficient contrast  | Recoloring to arbitrary hues       |
-| Use a single primary mark per surface | Layering multiple logos            |
-| Attribute the project when citing     | Using assets to imply endorsement  |
+| Do | Avoid | | ------------------------------------- | ---------------------------------- | | Use supplied SVG for scalable quality | Recreating marks from scratch | | Maintain clear space and aspect ratio | Distorting, squeezing, or rotating | | Choose color for sufficient contrast | Recoloring to arbitrary hues | | Use a single primary mark per surface | Layering multiple logos | | Attribute the project when citing | Using assets to imply endorsement |
 
 ## License & Attribution
 
diff --git a/docs/index.md b/docs/index.md
@@ -31,8 +31,7 @@ Speculators standardizes this process by providing a productionized end-to-end f
 - **Standardized, Extensible Format:** Provides a Hugging Face-compatible format for defining speculative models, with tools to convert from external research repositories into a standard speculators format for easy adoption.
 - **Seamless vLLM Integration:** Built for direct deployment into vLLM, enabling low-latency, production-grade inference with minimal overhead.
 
-!!! tip
-    Read more about Speculators features in this [vLLM blog post](https://blog.vllm.ai/2025/12/13/speculators-v030.html).
+!!! tip Read more about Speculators features in this [vLLM blog post](https://blog.vllm.ai/2025/12/13/speculators-v030.html).
 
 ## Quick Start
 
diff --git a/docs/user_guide/algorithms/decision_guide.md b/docs/user_guide/algorithms/decision_guide.md
@@ -16,13 +16,7 @@ Eagle-3, P-EAGLE, and DFlash can be paired with any supported verifier model (in
 
 ## Current Support
 
-|                     | Eagle-3       | P-EAGLE             | DFlash              | MTP                         |
-| ------------------- | ------------- | ------------------- | ------------------- | --------------------------- |
-| **Draft layers**    | Llama-style   | Llama-style         | Qwen3-style         | Native MTP layers           |
-| **Verifier models** | Any supported | Any supported       | Any supported       | Models with native MTP only |
-| **Training mode**   | From scratch  | From scratch        | From scratch        | Finetune existing MTP head  |
-| **Speculators**     | Mature        | Newer, growing fast | Newer, growing fast | Newer, growing fast         |
-| **vLLM**            | Mature        | Newer, growing fast | Newer, growing fast | Newer, growing fast         |
+| | Eagle-3 | P-EAGLE | DFlash | MTP | | ------------------- | ------------- | ------------------- | ------------------- | --------------------------- | | **Draft layers** | Llama-style | Llama-style | Qwen3-style | Native MTP layers | | **Verifier models** | Any supported | Any supported | Any supported | Models with native MTP only | | **Training mode** | From scratch | From scratch | From scratch | Finetune existing MTP head | | **Speculators** | Mature | Newer, growing fast | Newer, growing fast | Newer, growing fast | | **vLLM** | Mature | Newer, growing fast | Newer, growing fast | Newer, growing fast |
 
 Eagle-3 has been available longer and has broader support in both Speculators and vLLM. P-EAGLE, DFlash, and MTP were added more recently and support is improving rapidly.
 
diff --git a/docs/user_guide/algorithms/dflash.md b/docs/user_guide/algorithms/dflash.md
@@ -21,9 +21,7 @@ The target model produces hidden states (fused target context features) and deco
 
 Pretrained DFlash speculator models are available on HuggingFace from the [RedHatAI speculator models collection](https://huggingface.co/collections/RedHatAI/speculator-models):
 
-| Verifier                | Speculator                                                                                                      |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `google/gemma-4-31B-it` | [`RedHatAI/gemma-4-31B-it-speculator.dflash`](https://huggingface.co/RedHatAI/gemma-4-31B-it-speculator.dflash) |
+| Verifier | Speculator | | ----------------------- | --------------------------------------------------------------------------------------------------------------- | | `google/gemma-4-31B-it` | [`RedHatAI/gemma-4-31B-it-speculator.dflash`](https://huggingface.co/RedHatAI/gemma-4-31B-it-speculator.dflash) |
 
 > **Note:** DFlash is under active development. Not all hardware configurations have been validated yet — refer to individual model cards for details.
 
@@ -33,11 +31,7 @@ Domino is a lightweight causal correction head that can be added on top of the D
 
 The overhead is negligible: a single GRU layer and a two-layer MLP operate only on the suffix tokens within each block, adding a tiny fraction of the backbone transformer's FLOPs and requiring no additional sequential passes.
 
-|                           | DFlash               | DFlash + Domino                               |
-| ------------------------- | -------------------- | --------------------------------------------- |
-| **Draft path**            | Base logits → argmax | Base logits → GRU correction → refined logits |
-| **Per-position accuracy** | Good                 | Better (GRU conditions on prior tokens)       |
-| **Training cost**         | ~1×                  | Negligible overhead                           |
+| | DFlash | DFlash + Domino | | ------------------------- | -------------------- | --------------------------------------------- | | **Draft path** | Base logits → argmax | Base logits → GRU correction → refined logits | | **Per-position accuracy** | Good | Better (GRU conditions on prior tokens) | | **Training cost** | ~1× | Negligible overhead |
 
 Select Domino via `--projector-type domino` when training (see the [Train DFlash tutorial](../tutorials/train_dflash_online.md#domino-variant)).
 
diff --git a/docs/user_guide/algorithms/eagle3.md b/docs/user_guide/algorithms/eagle3.md
diff --git a/docs/user_guide/algorithms/peagle.md b/docs/user_guide/algorithms/peagle.md
diff --git a/docs/user_guide/tutorials/train_dflash_online.md b/docs/user_guide/tutorials/train_dflash_online.md
diff --git a/docs/user_guide/tutorials/train_peagle_offline.md b/docs/user_guide/tutorials/train_peagle_offline.md
