From 6895b7a1e10cde0dbf8fb77b7fd713892b23ec5c Mon Sep 17 00:00:00 2001
From: Nickolay <asqueella@gmail.com>
Date: Thu, 15 Feb 2024 18:24:21 +0300
Subject: [PATCH] Add some documentation to the playground page

The minimal UI of the Playground could benefit from some documentation to make it easier for the newer users to understand what's going on. Also added a link to the new documentation from the local playground.

Closes https://github.com/tree-sitter/tree-sitter/issues/1305
---
 cli/src/playground.html        |  4 ++++
 docs/assets/css/style.scss     |  4 ++++
 docs/section-7-playground.html | 14 ++++++++++++++
 3 files changed, 22 insertions(+)

diff --git a/cli/src/playground.html b/cli/src/playground.html
index b69f9351..420cd28d 100644
--- a/cli/src/playground.html
+++ b/cli/src/playground.html
@@ -29,6 +29,10 @@
         <span id="update-time"></span>
       </div>
 
+      <div class=header-item>
+        <a href="https://tree-sitter.github.io/tree-sitter/playground#about">(?)</a>
+      </div>
+
       <select id="language-select" style="display: none;">
         <option value="parser">Parser</option>
       </select>
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
index 2b7a018b..0f4a47a6 100644
--- a/docs/assets/css/style.scss
+++ b/docs/assets/css/style.scss
@@ -162,6 +162,10 @@ a > span {
   .CodeMirror div.CodeMirror-cursor {
     border-left: 3px solid red;
   }
+
+  h4#about {
+    margin: 10ex 0 0 0;
+  }
 }
 
 #output-container {
diff --git a/docs/section-7-playground.html b/docs/section-7-playground.html
index 3c6b90db..03cb0541 100644
--- a/docs/section-7-playground.html
+++ b/docs/section-7-playground.html
@@ -51,6 +51,20 @@ permalink: playground
   <pre id="output-container" class="highlight"></pre>
 </div>
 
+<h4 id="about">About </h4>
+<p>You can try out tree-sitter with a few pre-selected grammars on this page.
+  You can also run playground locally (with your own grammar) using the
+  <a href="/creating-parsers">CLI</a>'s <code>tree-sitter playground</code> subcommand.</p>
+<p>The syntax tree should update as you type in the code. As you move around the
+  code, the current node should be highlighted in the tree; you can also click any
+  node in the tree to select the corresponding part of the code.</p>
+<p>Logging (if enabled) can be viewed in the browser's console.</p>
+<p>You can enter one or more <a href="/using-parsers#pattern-matching-with-queries">patterns</a>
+  into the Query panel. If the query is valid, its captures will be
+  highlighted both in the Code and in the Query panels. Otherwise
+  the problematic parts of the query will be underlined, and detailed
+  diagnostics will be available on hover. Note that to see any results
+  you must use at least one capture, like <code>(node_name) @capture-name</code></p>
 </div>
 
 <script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.45.0/codemirror.min.js"></script>