Test more NPM snippets

crates/solidity/outputs/npm/tests/src/doc-examples/reconstruct-source.sol

@@ -0,0 +1 @@
+pragma solidity ^0.8.0;

crates/solidity/outputs/npm/tests/src/doc-examples/reconstruct-source.ts

@@ -0,0 +1,39 @@
+// --8<-- [start:intro]
+import { Language } from "@nomicfoundation/slang/language";
+import { RuleKind } from "@nomicfoundation/slang/kinds";
+import { Cursor } from "@nomicfoundation/slang/cursor";
+
+const source = "int256 constant z = 1 + 2;";
+const language = new Language("0.8.11");
+
+let parseOutput = language.parse(RuleKind.SourceUnit, source);
+// --8<-- [end:intro]
+
+// --8<-- [start:step-1]
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const data = fs.readFileSync(path.join(__dirname, "reconstruct-source.sol"), "utf8");
+
+parseOutput = language.parse(RuleKind.SourceUnit, data);
+let cursor: Cursor = parseOutput.createTreeCursor();
+// --8<-- [end:step-1]
+// --8<-- [start:step-2]
+import { TokenNode } from "@nomicfoundation/slang/cst";
+
+let output = "";
+while (cursor.goToNext()) {
+  let node = cursor.node();
+  if (node instanceof TokenNode) {
+    output += node.text;
+  }
+}
+
+// --8<-- [end:step-2]
+// We wrap this in a Jest test so that we can verify that the output is correct
+test("reconstruct source", () => {
+  // --8<-- [start:step-2-assertion]
+  // Jest-style assertion for clarity
+  expect(output).toEqual("pragma solidity ^0.8.0;\n");
+  // --8<-- [end:step-2-assertion]
+});

documentation/mkdocs.yml

@@ -64,6 +64,7 @@ markdown_extensions:
   - "pymdownx.snippets":
       base_path: !ENV "REPO_ROOT"
       check_paths: true
+      dedent_subsections: true
   - "pymdownx.superfences"
   - "pymdownx.tabbed":
       alternate_style: true

documentation/public/user-guide/npm-package/how-to-parse-a-file/index.md

@@ -40,20 +40,16 @@ Let's try the same example, only now using the API directly.
 
 We'll start with this file:
 
-```solidity
-// file: file.sol
-pragma solidity ^0.8.0;
+```solidity title="reconstruct-source.sol"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/reconstruct-source.sol"
 ```
 
 #### Step 1: Parse the Solidity file
 
 Let's naively (ignore the errors) read the file and parse it:
 
-```ts
-import { fs } from "node:fs";
-const data = fs.readFileSync("file.sol", "utf8");
-
-let parseTree = language.parse(RuleKind.SourceUnit, data);
+```{ .ts }
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/reconstruct-source.ts:step-1"
 ```
 
 #### Step 2: Reconstruct the source code
@@ -62,19 +58,9 @@ The `Cursor` visits the tree nodes in a depth-first search (DFS) fashion. Since
 
 Let's do that:
 
-```ts
-import { TokenNode } from "@nomicfoundation/slang/cst";
-
-let output = "";
-while (cursor.goToNext()) {
-    let node = cursor.node();
-    if (node instanceof TokenNode) {
-        output += node.text;
-    }
-}
-
-// Jest-style assertion for clarity
-expect(output).toEqual("pragma solidity ^0.8.0\n");
+```{ .ts }
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/reconstruct-source.ts:step-2"
+--8<-- "crates/solidity/outputs/npm/tests/src/doc-examples/reconstruct-source.ts:step-2-assertion"
 ```
 
 ### Example 2: List the top-level contracts and their names

documentation/public/user-guide/rust-crate/how-to-parse-a-file/index.md

@@ -54,8 +54,7 @@ Since the the parse tree is simply a structured view of the underlying source co
 
 We'll start with a bare-bones file:
 
-```solidity
-// file: file.sol
+```solidity title="file.sol"
 pragma solidity ^0.8.0;
 ```
 
@@ -156,7 +155,7 @@ To do that, we need to:
 Given this file:
 
 ```solidity
-// file: file.sol
+// file: title="file.sol"
 contract Foo {}
 contract Bar {}
 contract Baz {}
@@ -228,8 +227,7 @@ Let's try the same example, but this time we'll use the API directly.
 
 We'll start with this file:
 
-```solidity
-// file: file.sol
+```solidity title="file.sol"
 pragma solidity ^0.8.0;
 ```