docs: add notes to stateful pin commands (#562)

crates/typlite/src/library.rs

@@ -11,6 +11,11 @@ pub fn library() -> Scopes<Value> {
     scopes.define("md-alter", md_alter as RawFunc);
     scopes.define("image", image as RawFunc);
     scopes.define("figure", figure as RawFunc);
+    scopes.define("note-box", note as RawFunc);
+    scopes.define("tip-box", tip as RawFunc);
+    scopes.define("important-box", important_box as RawFunc);
+    scopes.define("warning-box", warning_box as RawFunc);
+    scopes.define("caution-box", caution_box as RawFunc);
     scopes
 }
 
@@ -74,3 +79,53 @@ pub fn md_alter(mut args: Args) -> Result<Value> {
 
     Ok(Value::Content(right.0))
 }
+
+/// Evaluate a note.
+pub fn note(mut args: Args) -> Result<Value> {
+    let body = get_pos_named!(args, body: Content);
+
+    Ok(note_box("NOTE", body))
+}
+
+/// Evaluate a tip note box.
+pub fn tip(mut args: Args) -> Result<Value> {
+    let body = get_pos_named!(args, body: Content);
+
+    Ok(note_box("TIP", body))
+}
+
+/// Create a important note box.
+pub fn important_box(mut args: Args) -> Result<Value> {
+    let body = get_pos_named!(args, body: Content);
+
+    Ok(note_box("IMPORTANT", body))
+}
+
+/// Create a warning note box.
+pub fn warning_box(mut args: Args) -> Result<Value> {
+    let body = get_pos_named!(args, body: Content);
+
+    Ok(note_box("WARNING", body))
+}
+
+/// Create a caution note box.
+pub fn caution_box(mut args: Args) -> Result<Value> {
+    let body = get_pos_named!(args, body: Content);
+
+    Ok(note_box("CAUTION", body))
+}
+
+fn note_box(title: &str, body: Content) -> Value {
+    let mut res = EcoString::new();
+    res.push_str("> [!");
+    res.push_str(title);
+    res.push_str("]\n");
+    let body = body.0;
+    for line in body.lines() {
+        res.push_str("> ");
+        res.push_str(line);
+        res.push('\n');
+    }
+
+    Value::Content(res)
+}

docs/tinymist/frontend/neovim.typ

@@ -47,7 +47,11 @@ vim.lsp.buf.execute_command({ command = 'tinymist.pinMain', arguments = { vim.ap
 vim.lsp.buf.execute_command({ command = 'tinymist.pinMain', arguments = { nil } })
 ```
 
-There is also a plan to support multiple-file project by workspace configuration, but I don’t know what is neovim’s way, so it needs further discussion.
+There is also a plan to support multiple-file project by workspace configuration, but I don’t know whether it is neovim’s way, so it needs further discussion.
+
+#note-box[
+  `tinymist.pinMain` is a stateful command, and tinymist doesn't remember it between sessions (closing and opening the editor).
+]
 
 == Troubleshooting
 <troubleshooting>

docs/tinymist/frontend/vscode.typ

@@ -142,6 +142,10 @@ You can pin a main file by command.
 - Use command `Typst Pin Main` (tinymist.pinMainToCurrent) to set the current file as the main file.
 - Use command `Typst Unpin Main` (tinymist.unpinMain) to unset the main file.
 
+#note-box[
+  `tinymist.pinMain` is a stateful command, and tinymist doesn't remember it between sessions (closing and opening the editor).
+]
+
 === Passing Extra CLI Arguments
 <passing-extra-cli-arguments>
 There is a *global* configuration `tinymist.typstExtraArgs` to pass extra arguments to tinymist LSP, like what you usually do with `typst-cli` CLI. For example, you can set it to `["--input=awa=1", "--input=abaaba=2", "main.typ"]` to configure `sys.inputs` and entry for compiler, which is equivalent to make LSP run like a `typst-cli` with such arguments:

docs/tinymist/mod.typ

@@ -37,3 +37,5 @@
     },
   )
 })
+
+#let note-box = pro-tip

editors/neovim/README.md

@@ -65,7 +65,12 @@ vim.lsp.buf.execute_command({ command = 'tinymist.pinMain', arguments = { vim.ap
 vim.lsp.buf.execute_command({ command = 'tinymist.pinMain', arguments = { nil } })
 ```
 
-There is also a plan to support multiple-file project by workspace configuration, but I don’t know what is neovim’s way, so it needs further discussion.
+There is also a plan to support multiple-file project by workspace configuration, but I don’t know whether it is neovim’s way, so it needs further discussion.
+
+> [!NOTE]
+> 
+>   `tinymist.pinMain` is a stateful command, and tinymist doesn't remember it between sessions (closing and opening the editor).
+
 
 ## Troubleshooting
 

editors/vscode/README.md

@@ -141,6 +141,11 @@ You can pin a main file by command.
 - Use command `Typst Pin Main` (tinymist.pinMainToCurrent) to set the current file as the main file.
 - Use command `Typst Unpin Main` (tinymist.unpinMain) to unset the main file.
 
+> [!NOTE]
+> 
+>   `tinymist.pinMain` is a stateful command, and tinymist doesn't remember it between sessions (closing and opening the editor).
+
+
 ### Passing Extra CLI Arguments
 
 There is a **global** configuration `tinymist.typstExtraArgs` to pass extra arguments to tinymist LSP, like what you usually do with `typst-cli` CLI. For example, you can set it to `["--input=awa=1", "--input=abaaba=2", "main.typ"]` to configure `sys.inputs` and entry for compiler, which is equivalent to make LSP run like a `typst-cli` with such arguments: