refactor: improve directory handling and markdown conversion for better performance

scripts/docs/directory_extension.dart

@@ -19,7 +19,10 @@ extension DirectoryExtension on Directory {
 
           final Directory dir = .new(filePath);
 
-          await for (final file in dir.list(recursive: recursive)) {
+          await for (final file in dir.list(
+            recursive: recursive,
+            followLinks: false,
+          )) {
             if (file is! File) continue;
             filesToPreserveContents[file] = await file.readAsBytes();
           }
@@ -37,14 +40,13 @@ extension DirectoryExtension on Directory {
     }
 
     await delete(recursive: true);
-    await create();
 
-    for (final entry in filesToPreserveContents.entries) {
-      if (!await entry.key.parent.exists()) {
-        await entry.key.parent.create(recursive: true);
+    for (final MapEntry(:key, :value) in filesToPreserveContents.entries) {
+      if (key.parent case final parent) {
+        if (!await parent.exists()) await parent.create(recursive: true);
       }
 
-      await entry.key.writeAsBytes(entry.value, flush: true);
+      await key.writeAsBytes(value, flush: true);
     }
   }
 }

scripts/docs/generate.dart

@@ -32,7 +32,7 @@ void main() async {
 
   final converter = MarkdownToHtmlConverter(directory: docRootDir);
 
-  await for (final (file, content) in converter.convert()) {
+  await for (final (file, content) in converter.convert(recursive: true)) {
     await file.writeAsString(content);
   }
 }

scripts/docs/generate/commands.dart

@@ -48,18 +48,22 @@ Future<void> _recursiveDocsGenerate({
 }) async {
   final StringBuffer buffer = .new(header);
 
-  if (parentCommandName case final String name) {
+  final noSpaceCommandName = command.name.replaceAll(" ", "_");
+
+  if (parentCommandName case final String parentCommandName) {
+    final noSpaceParentCommandName = parentCommandName.replaceAll(" ", "_");
+
     buffer
       ..writeAll([
-        "### [$name](commands_${name.replaceAll(" ", "_")}.md)",
-        "[${command.name}](commands_${name.replaceAll(" ", "_")}_${command.name.replaceAll(" ", "_")}.md)",
+        "### [$parentCommandName](commands_$noSpaceParentCommandName.md)",
+        "[${command.name}](commands_${noSpaceParentCommandName}_$noSpaceCommandName.md)",
       ], " / ")
       ..writeln()
       ..writeln();
   } else {
     buffer
       ..writeln(
-        "### [${command.name}](commands_${command.name.replaceAll(" ", "_")}.md)",
+        "### [${command.name}](commands_$noSpaceCommandName.md)",
       )
       ..writeln();
   }

scripts/docs/markdown_to_html_converter.dart

@@ -10,9 +10,9 @@ final class MarkdownToHtmlConverter {
 
   final Directory directory;
 
-  Stream<(File file, String content)> convert() async* {
+  Stream<(File, String)> convert({bool recursive = false}) async* {
     final entities = await directory
-        .list(recursive: true)
+        .list(recursive: recursive, followLinks: false)
         .where((e) => e is File && extension(e.path) == _mdExt)
         .toList();