[Plugin] April Fools Languages joke

_layouts/spec.html

@@ -118,7 +118,8 @@
                 {%- if defaultCodeblockVariant == nil -%}
                 {%- assign defaultCodeblockVariant = site.primerSpec.defaultCodeblockVariant -%}
                 {%- endif -%}
-                defaultCodeblockVariant: "{{ defaultCodeblockVariant | default: 'enhanced' }}"
+                defaultCodeblockVariant: "{{ defaultCodeblockVariant | default: 'enhanced' }}",
+                disableJokes: {{ site.primerSpec.disableJokes | default: false }}
             };
         </script>
         <script src="{{ base_url }}/assets/{{ layout.version_string }}/js/primer_spec_plugin.min.js" crossorigin="anonymous" defer></script>

_sass/jekyll-theme-primer-spec.scss

@@ -5,6 +5,8 @@
 @import '@primer/css/markdown/index.scss';
 @import '@primer/css/box/index.scss';
 @import '@primer/css/buttons/index.scss';
+@import '@primer/css/dropdown/index.scss';
+@import '@primer/css/popover/index.scss';
 @import '@primer/css/tooltips/index.scss';
 @import 'spec/base.scss';
 @import 'spec/rouge.scss';

docs/USAGE_ADVANCED.md

@@ -38,6 +38,7 @@ See the [Primer Spec README](../README.md) for the main usage instructions. This
     - [`defaultSubthemeMode`: String](#defaultsubthememode-string)
     - [`defaultCodeblockVariant`: CodeblockVariant (String)](#defaultcodeblockvariant-codeblockvariant-string-1)
     - [`sitemap`: Boolean \| {label: String; externalLinks: Array}](#sitemap-boolean--label-string-externallinks-array)
+    - [`disableJokes`: Boolean](#disablejokes-boolean)
 - [Pinning to a specific version](#pinning-to-a-specific-version)
 - [Using without Jekyll](#using-without-jekyll)
 
@@ -416,6 +417,14 @@ To exclude a page from the sitemap, set [`excludeFromSitemap: true`](#excludefro
 **NOTE:** A sitemap will only be rendered if your site has multiple pages.
 </div>
 
+#### `disableJokes`: Boolean
+
+Primer Spec displays Easter Eggs to students around Halloween and April Fools. The jokes do not interefere with the spec's content without students' explicit consent. (See the [Halloween joke](https://github.com/eecs485staff/primer-spec/pull/157) as an example.)
+
+If you'd prefer for Primer Spec to not render jokes on your website, add the config `disableJokes: false` to the Primer Spec config in `_config.yml`.
+
+We hope you'll keep the jokes enabled as a fun way to engage students around these holidays! If you _do_ end up disabling these jokes, we'd appreciate your feedback on why you chose to do so. Please feel free to open an [issue](https://github.com/eecs485staff/primer-spec/issues/new/) or [discussion](https://github.com/eecs485staff/primer-spec/discussions/new) on the Primer Spec repo, and we can follow up there :)
+
 ## Pinning to a specific version
 
 We take care to release new versions of Primer Spec on the `main` branch only between semesters at the University of Michigan. However, if your site needs an even stronger guarantee of stability, you can pin your site to a specific _minor_ version of Primer Spec.

package.json

@@ -25,6 +25,7 @@
     "anchor-js": "^4.3.1",
     "clsx": "^1.1.1",
     "jsx-dom": "*",
+    "pig-latinizer": "^1.0.6",
     "preact": "^10.5.14"
   },
   "devDependencies": {

src_js/conditional_plugins/conditional_plugins.ts

@@ -1,33 +1,39 @@
-import { initialize as initializeHalloweenPlugin } from './halloween.plugin';
+/**
+ * Conditional plugins are loaded asynchronously and are intentionally
+ * isolated from the rest of Primer Spec. This is because this conditional
+ * plugin framework was designed to build temporary pranks and jokes! (We don't
+ * want these jokes to affect the page load time and the spec-reading
+ * experience.)
+ *
+ * Plugins run based on conditions defined in the `shouldLoadPlugin()` method.
+ * They can also be force-enabled by inserting
+ * `?enable_<plugin_id>=1` in the URL.
+ */
 
 import type { ConditionalPluginInput } from './types.d';
+import { shouldLoadPlugin } from './should_load_plugin';
+import { loadPlugin } from './load_plugin';
 
-const PLUGINS = [initializeHalloweenPlugin()]
-  .filter((pluginDefinition) => {
-    const forceEnableOption = pluginForceEnableOption(pluginDefinition.id);
-    if (forceEnableOption !== null) {
-      return forceEnableOption;
-    }
-    return pluginDefinition.shouldRun();
-  })
-  .map((pluginDefinition) => pluginDefinition.plugin);
+/**
+ * When adding a new Plugin:
+ * 1. Add the plugin definition to `./plugins/[your-plugin].plugin.ts`
+ * 2. Choose a plugin ID, then add it to this list
+ * 3. Add a condition to `shouldLoadPlugin()` for this plugin ID
+ * 4. Update `loadPlugin()` to load the plugin definition from (1)
+ */
+const PLUGIN_IDS = ['halloween', 'april_fools_languages'];
+
+const pluginsPromises = PLUGIN_IDS.filter((pluginId) =>
+  shouldLoadPlugin(pluginId),
+).map((pluginId) => loadPlugin(pluginId));
 
 export async function executePlugins(
   input: ConditionalPluginInput,
 ): Promise<void> {
+  const plugins = await Promise.all(pluginsPromises);
   await Promise.all(
-    PLUGINS.map(async (plugin) => {
-      await plugin(input);
+    plugins.map(async (plugin) => {
+      await plugin?.(input);
     }),
   );
 }
-
-function pluginForceEnableOption(pluginId: string): boolean | null {
-  const match = window.location.search.match(
-    new RegExp(`enable_${pluginId}=([0|1])`),
-  );
-  if (match) {
-    return match[1] === '1';
-  }
-  return null;
-}

src_js/conditional_plugins/load_plugin.ts

@@ -0,0 +1,23 @@
+import { Plugin } from './types.d';
+
+/**
+ * Given a plugin ID, lazy-load the appropriate JS module containing the plugin
+ * definition and return the plugin.
+ *
+ * Notice that we use the dynamic `import()` syntax. Webpack identifies this as
+ * an opportunity to split the JS bundle, hence decreasing the size of the main
+ * Primer Spec JS bundle. Additionally, we won't download the JS code for all
+ * plugins, only the ones that need to run.
+ */
+export async function loadPlugin(pluginId: string): Promise<Plugin | null> {
+  let plugin: Plugin | null = null;
+  switch (pluginId) {
+    case 'halloween':
+      plugin = (await import('./plugins/halloween.plugin')).default;
+      break;
+    case 'april_fools_languages':
+      plugin = (await import('./plugins/april_fools_languages.plugin')).default;
+      break;
+  }
+  return plugin;
+}