From 87718a53e218ba6694910560227b40ca71c6ff58 Mon Sep 17 00:00:00 2001
From: Greg Annandale <greg@raspberrypi.org>
Date: Tue, 31 Mar 2026 17:20:51 +0100
Subject: [PATCH] chore(docs): update README docs on formatting and linting

---
 packages/docs/README.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/docs/README.md b/packages/docs/README.md
index d1ecacb4e..2ea142ec2 100644
--- a/packages/docs/README.md
+++ b/packages/docs/README.md
@@ -33,17 +33,25 @@ This command generates static content into the `build` directory and can be serv
 npm run serve
 ```
 
-The build folder is now served at http://localhost:3000/.
+The build folder is now served at http://localhost:3000/
 
-## Linting
+## Formatting and linting
 
 ```bash
 # check formatting:
 npm run format:check
 # fix formatting:
 npm run format
+# check linting:
+npm run lint
+# fix linting:
+npm run lint:fix
 ```
 
+Prettier is used for formatting JavaScript files (the `format` script).
+
+ESlint is used for linting `.md` and `.mdx` files due to poor support for these in Prettier (the `lint` script).
+
 ## Generating reference docs
 
 The API reference pages are auto-generated from the Blockly TypeScript source using `@microsoft/api-extractor` and `@microsoft/api-documenter`. This is a separate step from the Docusaurus build and must be run from the `packages/blockly` directory: