Merge pull request #467 from hydephp/447-add-simple-optional-search-f…

…eature-to-documentation-pages

Make the search feature configurable and toggleable

.github/dev-docs/documentation-pages.md

@@ -208,3 +208,19 @@ You can also disable the feature completely.
 	'smooth_page_scrolling' => true,
 ],
 ```
+
+### Search feature
+
+The HydeSearch plugin was introduced in v0.29.0-beta and adds a search feature to documentation pages.
+
+The search feature is enabled by default.
+You can disable it by removing the `documentationSearch` from the Hyde `Features` config array.
+
+The search works by generating a JSON search index which the JavaScript plugin loads asynchronously.
+
+Two types of search methods are added, one is a full page search screen that will saved to `docs/search.html`.
+<small><blockquote>The full page can be disabled by setting `create_search_page` to `false` in the `docs` config.</blockquote></small>
+
+The second method is a button added to the documentation pages, similar to how Algolia DocSearch works.
+Opening it will open a dialog modal with an integrated search screen.
+You can also open the dialog using the keyboard shortcut `/`.

config/hyde.php

@@ -119,6 +119,7 @@
 
         // Frontend Features
         Features::darkmode(),
+        Features::documentationSearch(),
 
         // Integrations
         Features::torchlight(),

resources/views/layouts/docs.blade.php

@@ -70,19 +70,19 @@
 		</article>
 	</main>
 
+	@if(Hyde\Framework\Helpers\Features::hasDocumentationSearch())
 	@include('hyde::components.docs.search')
+		<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/HydeSearch.min.js" defer></script>
+		<script>
+			window.addEventListener('load', function() {
+				const searchIndexLocation = 'search.json';
+				const Search = new HydeSearch(searchIndexLocation);
 
-    @include('hyde::layouts.scripts')
-
-	<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/HydeSearch.min.js" defer></script>
-
-	<script>
-		window.addEventListener('load', function() {
-			const searchIndexLocation = 'search.json';
-			const Search = new HydeSearch(searchIndexLocation);
-
-			Search.init();
-		});
+				Search.init();
+			});
 	</script>
+	@endif
+
+	@include('hyde::layouts.scripts')
 </body>
 </html>

src/Commands/HydeBuildSearchCommand.php

@@ -5,6 +5,7 @@
 use Hyde\Framework\Actions\GeneratesDocumentationSearchIndexFile;
 use Hyde\Framework\Hyde;
 use Hyde\Framework\Models\DocumentationPage;
+use Hyde\Framework\Services\CollectionService;
 use LaravelZero\Framework\Commands\Command;
 
 /**
@@ -40,14 +41,27 @@ public function handle(): int
         $actionTime = microtime(true);
 
         $this->comment('Generating documentation site search index...');
+        $this->line('<fg=gray> > This will take an estimated '.round($this->guesstimateGenerationTime() / 1000).' seconds. Terminal may seem non-responsive.</>');
         GeneratesDocumentationSearchIndexFile::run();
+
         $this->line(' > Created <info>'.GeneratesDocumentationSearchIndexFile::$filePath.'</> in '.
             $this->getExecutionTimeInMs($actionTime)."ms\n");
 
+        if (config('docs.create_search_page', true)) {
+            $this->createSearchPage();
+        }
+
+        return 0;
+    }
+
+    /**
+     * @todo Use the config defined output path.
+     */
+    protected function createSearchPage(): void
+    {
         $actionTime = microtime(true);
-        $this->comment('Generating search page...');
 
-        // Todo move into action which is run in the build loop
+        $this->comment('Generating search page...');
         file_put_contents(Hyde::path('_site/docs/search.html'),
         view('hyde::layouts.docs')->with([
             'page' => new DocumentationPage([], '', 'Search', 'search'),
@@ -56,7 +70,13 @@ public function handle(): int
             'currentPage' => 'docs/search',
         ])->render());
 
-        return 0;
+        $this->line(' > Created <info>_site/docs/search.html</> in '.
+        $this->getExecutionTimeInMs($actionTime)."ms\n");
+    }
+
+    protected function guesstimateGenerationTime(): float
+    {
+        return count(CollectionService::getDocumentationPageList()) * 52.5;
     }
 
     protected function getExecutionTimeInMs(float $timeStart): string

src/Commands/HydeBuildStaticSiteCommand.php

@@ -143,6 +143,10 @@ public function runPostBuildActions(): void
         if (RssFeedService::canGenerateFeed()) {
             Artisan::call('build:rss', outputBuffer: $this->output);
         }
+
+        if (Features::hasDocumentationSearch()) {
+            Artisan::call('build:search', outputBuffer: $this->output);
+        }
     }
 
     /** @internal */

src/Helpers/Features.php

@@ -19,7 +19,15 @@ class Features
      */
     public static function enabled(string $feature): bool
     {
-        return in_array($feature, config('hyde.features', []));
+        return in_array($feature, config('hyde.features', [
+            static::blogPosts(),
+            static::bladePages(),
+            static::markdownPages(),
+            static::documentationPages(),
+            static::documentationSearch(),
+            static::darkmode(),
+            static::torchlight(),
+        ]));
     }
 
     /**
@@ -47,6 +55,12 @@ public static function hasDocumentationPages(): bool
         return static::enabled(static::documentationPages());
     }
 
+    public static function hasDocumentationSearch(): bool
+    {
+        return static::enabled(static::documentationSearch())
+            && static::hasDocumentationPages();
+    }
+
     public static function hasDarkmode(): bool
     {
         return static::enabled(static::darkmode());
@@ -88,6 +102,11 @@ public static function documentationPages(): string
         return 'documentation-pages';
     }
 
+    public static function documentationSearch(): string
+    {
+        return 'documentation-search';
+    }
+
     public static function darkmode(): string
     {
         return 'darkmode';