deprecate the scripts config option (#1296)

* deprecate the scripts config option

closes #1272

* only warn once; scripts, not script

---------

Co-authored-by: Mike Bostock <mbostock@gmail.com>

Author: Fil

docs/config.md

@@ -162,26 +162,6 @@ An HTML fragment to add to the header. Defaults to the empty string.
 
 An HTML fragment to add to the footer. Defaults to “Built with Observable.”
 
-## scripts
-
-Additional scripts to add to the head, such as for analytics. For example, this:
-
-```js run=false
-export default {
-  scripts: [{type: "module", async: true, src: "analytics.js"}]
-};
-```
-
-Is equivalent to setting the **head** option:
-
-```js run=false
-export default {
-  head: `<script type="module" async src="analytics.js"></script>`
-};
-```
-
-We recommend you use the **head** option instead of this option.
-
 ## base
 
 The base path when serving the site. Currently this only affects the custom 404 page, if any.

src/config.ts

@@ -50,7 +50,7 @@ export interface Config {
   sidebar: boolean; // defaults to true if pages isn’t empty
   pages: (Page | Section<Page>)[];
   pager: boolean; // defaults to true
-  scripts: Script[]; // defaults to empty array
+  scripts: Script[]; // deprecated; defaults to empty array
   head: string | null; // defaults to null
   header: string | null; // defaults to null
   footer: string | null; // defaults to “Built with Observable on [date].”
@@ -201,7 +201,7 @@ export function normalizeConfig(spec: ConfigSpec = {}, defaultRoot?: string, wat
   const pager = spec.pager === undefined ? true : Boolean(spec.pager);
   const toc = normalizeToc(spec.toc as any);
   const sidebar = spec.sidebar === undefined ? undefined : Boolean(spec.sidebar);
-  const scripts = spec.scripts === undefined ? [] : Array.from(spec.scripts as any, normalizeScript);
+  const scripts = spec.scripts === undefined ? [] : normalizeScripts(spec.scripts);
   const head = spec.head === undefined ? "" : stringOrNull(spec.head);
   const header = spec.header === undefined ? "" : stringOrNull(spec.header);
   const footer = spec.footer === undefined ? defaultFooter() : stringOrNull(spec.footer);
@@ -270,6 +270,11 @@ export function normalizeTheme(spec: unknown): string[] {
   return resolveTheme(typeof spec === "string" ? [spec] : spec === null ? [] : Array.from(spec as any, String));
 }
 
+function normalizeScripts(spec: unknown): Script[] {
+  console.warn(`${yellow("Warning:")} the ${bold("scripts")} option is deprecated; use ${bold("head")} instead.`);
+  return Array.from(spec as any, normalizeScript);
+}
+
 function normalizeScript(spec: unknown): Script {
   const script = typeof spec === "string" ? {src: spec} : (spec as ScriptSpec);
   const src = String(script.src);