Flutter-Bounty-Hunters · matthew-carroll · May 27, 2025
diff --git a/packages/static_shock_docs/source/concepts/_data.yaml b/packages/static_shock_docs/source/concepts/_data.yaml
@@ -16,8 +16,34 @@ docs_menu:
           id: data-index
         - title: Pages Index
           id: pages-index
-        - title: Plugins
-          id: plugins
+    - title: Plugins
+      id: plugins
+      subPath: plugins/
+      items:
+        - title: Overview
+          id: overview
+        - title: Pickers
+          id: pickers
+        - title: Excluders
+          id: excluders
+        - title: Remote Picking
+          id: pick-remote
+        - title: Data Loaders
+          id: data-loaders
+        - title: Asset Loaders
+          id: asset-loaders
+        - title: Asset Transformers
+          id: asset-transformers
+        - title: Page Loaders
+          id: page-loaders
+        - title: Page Transformers
+          id: page-transformers
+        - title: Page Filters
+          id: page-filters
+        - title: Page Renderers
+          id: page-renderers
+        - title: Finishers
+          id: finishers
     - title: Markdown
       id: markdown
       subPath: markdown/

diff --git a/packages/static_shock_docs/source/concepts/plugins/asset-loaders.md b/packages/static_shock_docs/source/concepts/plugins/asset-loaders.md
@@ -0,0 +1,4 @@
+---
+title: Asset Loaders
+---
+TODO: Fill out guide.
diff --git a/packages/static_shock_docs/source/concepts/plugins/asset-transformers.md b/packages/static_shock_docs/source/concepts/plugins/asset-transformers.md
@@ -0,0 +1,4 @@
+---
+title: Asset Transformers
+---
+TODO: Fill out guide.
diff --git a/packages/static_shock_docs/source/concepts/plugins/data-loaders.md b/packages/static_shock_docs/source/concepts/plugins/data-loaders.md
@@ -0,0 +1,53 @@
+---
+title: Data Loaders
+contentRenderers:
+  - jinja
+  - markdown
+---
+Plugins can load data into the `DataIndex` by registering `DataLoader`s with
+the pipeline.
+
+[Learn more]({{ "concepts/how-it-works/data-index" | local_link }}) about the `DataIndex`.
+
+To load data in a plugin, first define a `DataLoader` implementation, and
+then register that `DataLoader` with the pipeline.
+
+The `DataLoader` can load whatever data it wants, from any source that it
+wants. The data returned from the `DataLoader` is merged into the `DataIndex`
+beginning at the root `/` of the index.
+
+```dart
+class MyDataLoader implements DataLoader {
+  MyDataLoader();
+
+  @override
+  Future<Map<String, Object>> loadData(StaticShockPipelineContext context) async {
+    // Load data from wherever you'd like.
+
+    // Return the data that you want merged into the `DataIndex`. To avoid
+    // data conflicts, it's recommended that you create a namespace for
+    // the data.
+    return {
+      "io.staticshock": {
+        "thing1": "some value",
+        "thing2": "some value",
+      },
+    };
+  }
+}
+```
+
+Register the `DataLoader` with the pipeline from within the plugin.
+
+```dart
+@override
+FutureOr<void> configure(
+  StaticShockPipeline pipeline,
+  StaticShockPipelineContext context,
+  StaticShockCache pluginCache,
+) {
+  pipeline.loadData(
+    MyDataLoader(),
+  );
+}
+```
diff --git a/packages/static_shock_docs/source/concepts/plugins/excluders.md b/packages/static_shock_docs/source/concepts/plugins/excluders.md
@@ -0,0 +1,32 @@
+---
+title: Excluders
+---
+Sometimes it's difficult to pick only the files that you need. For example,
+it might be convenient to pick an entire directory, but there might be a few
+files in that directory that an author doesn't want to include. To solve this
+problem, Static Shock provides `Excluder`s.
+
+An `Excluder` is similar to a `Picker`, except every file that matches the
+`Excluder` is kept out of the pipeline.
+
+Consider the common Mac file called `.DS_Store`. This pesky file is autogenerated
+by Mac in most directories. This file should probably never be picked for
+processing. For this reason, by default, Static Shock registers an `Excluder`
+for any file that begins with a `.`.
+
+```dart
+const FilePrefixExcluder(".")
+```
+
+Plugins can register their own `Excluder`s.
+
+```dart
+@override
+FutureOr<void> configure(
+  StaticShockPipeline pipeline,
+  StaticShockPipelineContext context,
+  StaticShockCache pluginCache,
+) {
+  pipeline.exclude(const FilePrefixExcluder("."));
+}
+```
diff --git a/packages/static_shock_docs/source/concepts/plugins/finishers.md b/packages/static_shock_docs/source/concepts/plugins/finishers.md
@@ -0,0 +1,4 @@
+---
+title: Finishers
+---
+TODO: Fill out guide.
diff --git a/...s/source/concepts/how-it-works/plugins.md → ..._docs/source/concepts/plugins/overview.md b/...s/source/concepts/how-it-works/plugins.md → ..._docs/source/concepts/plugins/overview.md
@@ -1,28 +1,32 @@
 ---
-title: Plugins
+title: Overview
+contentRenderers:
+  - jinja
+  - markdown
 ---
 Plugins are a major part of Static Shock. Static Shock is designed to be as
 pluggable as possible, with the express purpose of empowering plugins.
 
 Static Shock ships with support for the following:
- * Markdown parsing
- * Jinja templating
- * Sass compilation
- * Tailwind compilation
- * Pretty URLs
- * Redirect generation
- * RSS feeds
- * Website screenshotting
- * Pub package metadata scraping
- * GitHub repository metadata scraping
- * and more...
+* Markdown parsing
+* Jinja templating
+* Sass compilation
+* Tailwind compilation
+* Pretty URLs
+* Redirect generation
+* RSS feeds
+* Website screenshotting
+* Pub package metadata scraping
+* GitHub repository metadata scraping
+* and more...
 
 Despite the fact that Static Shock ships these tools, each of these tools is
 implemented as it's own plugin. Each behavior is accomplished by registering
 these plugins with Static Shock.
 
 For example, the Dart file for this very website looks like the following.
 
+{% raw %}
 ```dart
 final staticShock = StaticShock(
     site: SiteMetadata(
@@ -64,6 +68,7 @@ final staticShock = StaticShock(
     )
     ..loadData(/*...*/);
 ```
+{% endraw %}
 
 Notice that nearly all of the Static Shock website's configuration is the
 selection and configuration of plugins.
@@ -81,6 +86,7 @@ whatever pieces it wants.
 
 The interface for a plugin is as follows.
 
+{% raw %}
 ```dart
 abstract class StaticShockPlugin {
   const StaticShockPlugin();
@@ -102,12 +108,14 @@ abstract class StaticShockPlugin {
   ) {}
 }
 ```
+{% endraw %}
 
 A plugin is defined entirely by what it chooses to register within its `configure()` method.
 
 The following is the implementation for the drafting plugin, which removes any pages
 that are in draft mode.
 
+{% raw %}
 ```dart
 @override
 FutureOr<void> configure(
@@ -120,10 +128,12 @@ FutureOr<void> configure(
   );
 }
 ```
+{% endraw %}
 
 The following is the implementation of the Sass plugin, which compiles Sass files
 to CSS.
 
+{% raw %}
 ```dart
 @override
   FutureOr<void> configure(
@@ -147,7 +157,20 @@ to CSS.
     );
 }
 ```
+{% endraw %}
+
+## Plugin Hooks
+Static Shock provides a variety of hooks with which a plugin can register.
+
+ * [`Picker`s]({{ "concepts/plugins/pickers" | local_link }}): Pick files from the source directory for processing in the pipeline.
+ * [`Excluder`s]({{ "concepts/plugins/excluders" | local_link }}): Exclude files that would otherwise be picked.
+ * [Remote Picking]({{ "concepts/plugins/pick-remote" | local_link }}): Pick files from a server.
+ * [`DataLoader`s]({{ "concepts/plugins/data-loaders" | local_link }}): Load data into the `DataIndex`.
+ * [`AssetLoader`s]({{ "concepts/plugins/asset-loaders" | local_link }}): Load assets into the pipeline.
+ * [`AssetTransformer`s]({{ "concepts/plugins/asset-transformers" | local_link }}): Transform assets in the pipeline.
+ * [`PageLoader`s]({{ "concepts/plugins/page-loaders" | local_link }}): Load pages into the pipeline.
+ * [`PageTransformer`s]({{ "concepts/plugins/page-transformers" | local_link }}): Transform pages in the pipeline.
+ * [`PageFilter`s]({{ "concepts/plugins/page-filters" | local_link }}): Remote pages before final rendering.
+ * [`PageRenderer`s]({{ "concepts/plugins/page-renderers" | local_link }}): Render pages to HTML files.
+ * [`Finisher`s]({{ "concepts/plugins/finishers" | local_link }}): Take final actions after all pages and assets are rendered.
 
-The objects that plugins register with Static Shock are the various hooks
-supported by the `StaticShockPipeline`. See [the pipeline](concepts/how-it-works/the-pipeline)
-documentation to learn more about pipeline steps and hooks.
diff --git a/packages/static_shock_docs/source/concepts/plugins/page-filters.md b/packages/static_shock_docs/source/concepts/plugins/page-filters.md
@@ -0,0 +1,4 @@
+---
+title: Page Filters
+---
+TODO: Fill out guide.
diff --git a/packages/static_shock_docs/source/concepts/plugins/page-loaders.md b/packages/static_shock_docs/source/concepts/plugins/page-loaders.md
@@ -0,0 +1,4 @@
+---
+title: Page Loaders
+---
+TODO: Fill out guide.
diff --git a/packages/static_shock_docs/source/concepts/plugins/page-renderers.md b/packages/static_shock_docs/source/concepts/plugins/page-renderers.md
@@ -0,0 +1,4 @@
+---
+title: Page Renderers
+---
+TODO: Fill out guide.
diff --git a/packages/static_shock_docs/source/concepts/plugins/page-transformers.md b/packages/static_shock_docs/source/concepts/plugins/page-transformers.md
@@ -0,0 +1,4 @@
+---
+title: Page Transformers
+---
+TODO: Fill out guide.
diff --git a/packages/static_shock_docs/source/concepts/plugins/pick-remote.md b/packages/static_shock_docs/source/concepts/plugins/pick-remote.md
@@ -0,0 +1,41 @@
+---
+title: Pick From Remote Sources
+---
+It can be convenient to load pages, assets, and data from remote sources, such
+as servers. 
+
+For example, consider Flutter Bounty Hunter (FBH) documentation websites.
+FBH maintains many packages, with many documentation websites. It's convenient
+for many of those documentation websites to share visual styling and contribution
+instructions. With remote picking, each documentation website can pick layouts
+and content from a single set of files hosted on GitHub.
+
+Plugins can pick remote data, pages, assets, layouts, and components.
+
+```dart
+@override
+FutureOr<void> configure(
+  StaticShockPipeline pipeline,
+  StaticShockPipelineContext context,
+  StaticShockCache pluginCache,
+) {
+  pipeline.pickRemote(
+    layouts: {
+      RemoteInclude(
+        url: "https://raw.githubusercontent.com/my-repo/_includes/layouts/post.jinja?raw=true",
+        name: "post",
+        extension: "jinja",
+      ),
+    },
+    components: {/*...*/},
+    data: {/*...*/},
+    assets: {
+      RemoteFile(
+        url: "https://raw.githubusercontent.com/my-repo/images/flutter-logo.svg?raw=true",
+        buildPath: FileRelativePath("images/branding/", "flutter-logo", "svg"),
+      ),
+    },
+    pages: {/*...*/},
+  );
+}
+```
diff --git a/packages/static_shock_docs/source/concepts/plugins/pickers.md b/packages/static_shock_docs/source/concepts/plugins/pickers.md
@@ -0,0 +1,25 @@
+---
+title: Pickers
+---
+Static Shock runs on a given source directory. However, by default, Static Shock
+doesn't pick any of the files in that directory for processing. Instead, Static
+Shock websites must pick which files are pushed through the pipeline.
+
+Plugins pick files by registering `Picker`s. Static Shock provides `Picker`s
+for targeting directories, files, and extensions.
+
+`Picker`s are registered during plugin registration.
+
+The following shows how the Markdown plugin picks all the Markdown files from
+the source directory for processing.
+
+```dart
+@override
+FutureOr<void> configure(
+  StaticShockPipeline pipeline,
+  StaticShockPipelineContext context,
+  StaticShockCache pluginCache,
+) {
+  pipeline.pick(const ExtensionPicker("md"));
+}
+```