From 22be6df4d524e2b2c55aca7f3d6e0e3923c3024a Mon Sep 17 00:00:00 2001 From: Matt Carroll Date: Tue, 27 May 2025 00:23:14 -0700 Subject: [PATCH] WIP: Plugin guides under the 'concepts' section --- .../source/concepts/_data.yaml | 30 ++++++++++- .../source/concepts/plugins/asset-loaders.md | 4 ++ .../concepts/plugins/asset-transformers.md | 4 ++ .../source/concepts/plugins/data-loaders.md | 53 +++++++++++++++++++ .../source/concepts/plugins/excluders.md | 32 +++++++++++ .../source/concepts/plugins/finishers.md | 4 ++ .../plugins.md => plugins/overview.md} | 53 +++++++++++++------ .../source/concepts/plugins/page-filters.md | 4 ++ .../source/concepts/plugins/page-loaders.md | 4 ++ .../source/concepts/plugins/page-renderers.md | 4 ++ .../concepts/plugins/page-transformers.md | 4 ++ .../source/concepts/plugins/pick-remote.md | 41 ++++++++++++++ .../source/concepts/plugins/pickers.md | 25 +++++++++ 13 files changed, 245 insertions(+), 17 deletions(-) create mode 100644 packages/static_shock_docs/source/concepts/plugins/asset-loaders.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/asset-transformers.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/data-loaders.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/excluders.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/finishers.md rename packages/static_shock_docs/source/concepts/{how-it-works/plugins.md => plugins/overview.md} (70%) create mode 100644 packages/static_shock_docs/source/concepts/plugins/page-filters.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/page-loaders.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/page-renderers.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/page-transformers.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/pick-remote.md create mode 100644 packages/static_shock_docs/source/concepts/plugins/pickers.md diff --git a/packages/static_shock_docs/source/concepts/_data.yaml b/packages/static_shock_docs/source/concepts/_data.yaml index b5ea572..5970d3e 100644 --- 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 new file mode 100644 index 0000000..8c5db3a --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/asset-loaders.md @@ -0,0 +1,4 @@ +--- +title: Asset Loaders +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/asset-transformers.md b/packages/static_shock_docs/source/concepts/plugins/asset-transformers.md new file mode 100644 index 0000000..aa7264e --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/asset-transformers.md @@ -0,0 +1,4 @@ +--- +title: Asset Transformers +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/data-loaders.md b/packages/static_shock_docs/source/concepts/plugins/data-loaders.md new file mode 100644 index 0000000..da24c3c --- /dev/null +++ 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> 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 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 new file mode 100644 index 0000000..604eb8c --- /dev/null +++ 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 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 new file mode 100644 index 0000000..bd16821 --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/finishers.md @@ -0,0 +1,4 @@ +--- +title: Finishers +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/how-it-works/plugins.md b/packages/static_shock_docs/source/concepts/plugins/overview.md similarity index 70% rename from packages/static_shock_docs/source/concepts/how-it-works/plugins.md rename to packages/static_shock_docs/source/concepts/plugins/overview.md index b1e097b..c3f2301 100644 --- a/packages/static_shock_docs/source/concepts/how-it-works/plugins.md +++ b/packages/static_shock_docs/source/concepts/plugins/overview.md @@ -1,21 +1,24 @@ --- -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 @@ -23,6 +26,7 @@ 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 configure( @@ -120,10 +128,12 @@ FutureOr configure( ); } ``` +{% endraw %} The following is the implementation of the Sass plugin, which compiles Sass files to CSS. +{% raw %} ```dart @override FutureOr 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. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/page-filters.md b/packages/static_shock_docs/source/concepts/plugins/page-filters.md new file mode 100644 index 0000000..b177fe9 --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/page-filters.md @@ -0,0 +1,4 @@ +--- +title: Page Filters +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/page-loaders.md b/packages/static_shock_docs/source/concepts/plugins/page-loaders.md new file mode 100644 index 0000000..983b97d --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/page-loaders.md @@ -0,0 +1,4 @@ +--- +title: Page Loaders +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/page-renderers.md b/packages/static_shock_docs/source/concepts/plugins/page-renderers.md new file mode 100644 index 0000000..e185029 --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/page-renderers.md @@ -0,0 +1,4 @@ +--- +title: Page Renderers +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/page-transformers.md b/packages/static_shock_docs/source/concepts/plugins/page-transformers.md new file mode 100644 index 0000000..bc6dba2 --- /dev/null +++ b/packages/static_shock_docs/source/concepts/plugins/page-transformers.md @@ -0,0 +1,4 @@ +--- +title: Page Transformers +--- +TODO: Fill out guide. \ No newline at end of file diff --git a/packages/static_shock_docs/source/concepts/plugins/pick-remote.md b/packages/static_shock_docs/source/concepts/plugins/pick-remote.md new file mode 100644 index 0000000..0b32bc7 --- /dev/null +++ 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 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 new file mode 100644 index 0000000..b5797d1 --- /dev/null +++ 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 configure( + StaticShockPipeline pipeline, + StaticShockPipelineContext context, + StaticShockCache pluginCache, +) { + pipeline.pick(const ExtensionPicker("md")); +} +```