feat: allow importing code surrounded by a token

packages/kit-docs/src/node/markdown-plugin/parser/plugins/import-code-plugin/create-import-code-block-rule.ts

@@ -10,7 +10,7 @@ const MIN_LENGTH = 9;
 const START_CODES = [64, 91, 99, 111, 100, 101];
 
 // Regexp to match the import syntax.
-const SYNTAX_RE = /^@\[code(?:{(?:(\d+)?-(\d+)?)})?(?: ([^\]]+))?\]\(([^)]*)\)/;
+const SYNTAX_RE = /^@\[code(?:{(?:(\d+|[\w-]+)?-?(\d+)?)})?(?: ([^\]]+))?\]\(([^)]*)\)/;
 
 export const createImportCodeBlockRule =
   (): RuleBlock =>
@@ -45,7 +45,7 @@ export const createImportCodeBlockRule =
 
     const meta: ImportCodeTokenMeta = {
       importPath,
-      lineStart: lineStart ? Number.parseInt(lineStart, 10) : 0,
+      lineStart: lineStart ?? 0,
       lineEnd: lineEnd ? Number.parseInt(lineEnd, 10) : undefined,
     };
 

packages/kit-docs/src/node/markdown-plugin/parser/plugins/import-code-plugin/import-code-token-meta.ts

@@ -1,5 +1,5 @@
 export type ImportCodeTokenMeta = {
   importPath: string;
-  lineStart: number;
+  lineStart: number | string;
   lineEnd?: number;
 };

packages/kit-docs/src/node/markdown-plugin/parser/plugins/import-code-plugin/resolve-import-code.ts

@@ -35,13 +35,24 @@ export const resolveImportCode = (
   // Read file content.
   const fileContent = fs.readFileSync(importFilePath).toString();
 
+  let importCode = fileContent.split('\n');
+
+  if (!Number.isNaN(Number(lineStart))) {
+    lineStart = Number(lineStart);
+    importCode = importCode.slice(lineStart ? lineStart - 1 : lineStart, lineEnd);
+  } else if (typeof lineStart === 'string') {
+    importCode = importCode.slice(
+      1 + importCode.findIndex((line) => line.includes(lineStart as string)),
+    );
+    let end = importCode.findIndex((line) => line.includes(lineStart as string));
+    if (end > -1) {
+      importCode = importCode.slice(0, end - 1);
+    }
+  }
+
   // Resolve partial import.
   return {
     importFilePath,
-    importCode: fileContent
-      .split('\n')
-      .slice(lineStart ? lineStart - 1 : lineStart, lineEnd)
-      .join('\n')
-      .replace(/\n?$/, '\n'),
+    importCode: importCode.join('\n').replace(/\n?$/, '\n'),
   };
 };

packages/kit-docs/src/routes/docs/[...3]markdown/[...2]extensions/+page.md

@@ -171,7 +171,7 @@ You should NOT do this.
 
 ## Steps
 
-````md copy
+`````md copy
 :::steps
 
 !!!step title="Step 1"|description="This is a description for step 1."
@@ -191,7 +191,6 @@ const step = 2;
 !!!
 
 :::
-````
 
 :::steps
 
@@ -228,6 +227,7 @@ const step = 1;
 
 :::
 ````
+`````
 
 :::steps
 
@@ -446,12 +446,33 @@ You can import code blocks from files with the following syntax:
 @[code](../foo.js)
 ```
 
-If you want to partially import the file:
+If you want to partially import the file, you can do it via line numbers:
 
 ```md
 @[code{1-10}](../foo.js)
 ```
 
+Or via a token that surrounds the desired code snippet:
+
+```md
+@[code{snippet-1}](../foo.js)
+```
+
+```js title=foo.js
+
+willNotShow();
+
+// start of snippet-1
+
+if(...) {
+  doSomething();
+}
+
+// end of snippet-1
+
+thisWontShowEither();
+```
+
 The code language is inferred from the file extension, however, you can specify it like so:
 
 ```md
@@ -463,4 +484,4 @@ supports all the syntax mentioned above:
 
 ```md
 @[code js|title=file.js|copy{2,4-5}](../foo.js)
-```
+```