more config type safety; drop config.deploy; more markdown-it options (#1263)

* more config type safety; drop config.deploy

* quotes

* more docs

* typographer: false

Author: mbostock

docs/config.md

@@ -262,3 +262,15 @@ export default {
   markdownIt: (md) => md.use(MarkdownItFootnote)
 };
 ```
+
+## typographer <a href="https://github.com/observablehq/framework/pull/1263" class="observablehq-version-badge" data-version="prerelease" title="Added in #1263"></a>
+
+If true, enables simple typographic replacements in Markdown, such as replacing `(c)` with `©` and converting straight quotes to curly quotes. See also the [quotes](#quotes) option, which should be set for non-English languages if the **typographer** option is enabled. For the full list of replacements, see [markdown-it](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs). Defaults to false.
+
+## quotes <a href="https://github.com/observablehq/framework/pull/1263" class="observablehq-version-badge" data-version="prerelease" title="Added in #1263"></a>
+
+The set of replacements for straight double and single quotes used when the [**typographer** option](#typographer) is enabled. Defaults to `["“", "”", "‘", "’"]` which is suitable for English. For example, you can use `["«", "»", "„", "“"]` for Russian, `["„", "“", "‚", "‘"]` for German, and `["«\xa0", "\xa0»", "‹\xa0", "\xa0›"]` for French.
+
+## linkify <a href="https://github.com/observablehq/framework/pull/1263" class="observablehq-version-badge" data-version="prerelease" title="Added in #1263"></a>
+
+If true (the default), automatically convert URL-like text to links in Markdown.

src/config.ts

@@ -54,13 +54,59 @@ export interface Config {
   footer: string | null; // defaults to “Built with Observable on [date].”
   toc: TableOfContents;
   style: null | Style; // defaults to {theme: ["light", "dark"]}
-  deploy: null | {workspace: string; project: string};
   search: boolean; // default to false
   md: MarkdownIt;
   loaders: LoaderResolver;
   watchPath?: string;
 }
 
+interface ConfigSpec {
+  root?: unknown;
+  output?: unknown;
+  base?: unknown;
+  sidebar?: unknown;
+  style?: unknown;
+  theme?: unknown;
+  search?: unknown;
+  scripts?: unknown;
+  head?: unknown;
+  header?: unknown;
+  footer?: unknown;
+  interpreters?: unknown;
+  title?: unknown;
+  pages?: unknown;
+  pager?: unknown;
+  toc?: unknown;
+  linkify?: unknown;
+  typographer?: unknown;
+  quotes?: unknown;
+  cleanUrls?: unknown;
+  markdownIt?: unknown;
+}
+
+interface ScriptSpec {
+  src?: unknown;
+  async?: unknown;
+  type?: unknown;
+}
+
+interface SectionSpec {
+  name?: unknown;
+  open?: unknown;
+  collapsible?: unknown;
+  pages?: unknown;
+}
+
+interface PageSpec {
+  name?: unknown;
+  path?: unknown;
+}
+
+interface TableOfContentsSpec {
+  label?: unknown;
+  show?: unknown;
+}
+
 /**
  * Returns the absolute path to the specified config file, which is specified as a
  * path relative to the given root (if any). If you want to import this, you should
@@ -72,7 +118,7 @@ function resolveConfig(configPath: string, root = "."): string {
 
 // By using the modification time of the config, we ensure that we pick up any
 // changes to the config on reload.
-async function importConfig(path: string): Promise<any> {
+async function importConfig(path: string): Promise<ConfigSpec> {
   const {mtimeMs} = await stat(path);
   return (await import(`${pathToFileURL(path).href}?${mtimeMs}`)).default;
 }
@@ -116,73 +162,63 @@ function readPages(root: string, md: MarkdownIt): Page[] {
   return pages;
 }
 
-let currentDate = new Date();
+let currentDate: Date | null = null;
 
-export function setCurrentDate(date = new Date()): void {
+/** For testing only! */
+export function setCurrentDate(date: Date | null): void {
   currentDate = date;
 }
 
 // The config is used as a cache key for other operations; for example the pages
 // are used as a cache key for search indexing and the previous & next links in
 // the footer. When given the same spec (because import returned the same
 // module), we want to return the same Config instance.
-const configCache = new WeakMap<any, Config>();
+const configCache = new WeakMap<ConfigSpec, Config>();
 
-export function normalizeConfig(spec: any = {}, defaultRoot = "docs", watchPath?: string): Config {
+export function normalizeConfig(spec: ConfigSpec = {}, defaultRoot = "docs", watchPath?: string): Config {
   const cachedConfig = configCache.get(spec);
   if (cachedConfig) return cachedConfig;
-  let {
-    root = defaultRoot,
-    output = "dist",
-    base = "/",
-    sidebar,
-    style,
-    theme = "default",
-    search,
-    deploy,
-    scripts = [],
-    head = "",
-    header = "",
-    footer = `Built with <a href="https://observablehq.com/" target="_blank">Observable</a> on <a title="${formatIsoDate(
-      currentDate
-    )}">${formatLocaleDate(currentDate)}</a>.`,
-    interpreters
-  } = spec;
-  root = String(root);
-  output = String(output);
-  base = normalizeBase(base);
-  if (style === null) style = null;
-  else if (style !== undefined) style = {path: String(style)};
-  else style = {theme: (theme = normalizeTheme(theme))};
-  const md = createMarkdownIt(spec);
-  let {title, pages, pager = true, toc = true} = spec;
-  if (title !== undefined) title = String(title);
-  if (pages !== undefined) pages = normalizePages(pages);
-  if (sidebar !== undefined) sidebar = Boolean(sidebar);
-  pager = Boolean(pager);
-  scripts = Array.from(scripts, normalizeScript);
-  head = stringOrNull(head);
-  header = stringOrNull(header);
-  footer = stringOrNull(footer);
-  toc = normalizeToc(toc);
-  deploy = deploy ? {workspace: String(deploy.workspace).replace(/^@+/, ""), project: String(deploy.project)} : null;
-  search = Boolean(search);
-  interpreters = normalizeInterpreters(interpreters);
-  const config = {
+  const root = spec.root === undefined ? defaultRoot : String(spec.root);
+  const output = spec.output === undefined ? "dist" : String(spec.output);
+  const base = spec.base === undefined ? "/" : normalizeBase(spec.base);
+  const style =
+    spec.style === null
+      ? null
+      : spec.style !== undefined
+      ? {path: String(spec.style)}
+      : {theme: normalizeTheme(spec.theme === undefined ? "default" : spec.theme)};
+  const md = createMarkdownIt({
+    linkify: spec.linkify === undefined ? undefined : Boolean(spec.linkify),
+    typographer: spec.typographer === undefined ? undefined : Boolean(spec.typographer),
+    quotes: spec.quotes === undefined ? undefined : (spec.quotes as any),
+    cleanUrls: spec.cleanUrls === undefined ? undefined : Boolean(spec.cleanUrls),
+    markdownIt: spec.markdownIt as any
+  });
+  const title = spec.title === undefined ? undefined : String(spec.title);
+  const pages = spec.pages === undefined ? undefined : normalizePages(spec.pages);
+  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 head = spec.head === undefined ? "" : stringOrNull(spec.head);
+  const header = spec.header === undefined ? "" : stringOrNull(spec.header);
+  const footer = spec.footer === undefined ? defaultFooter() : stringOrNull(spec.footer);
+  const search = Boolean(spec.search);
+  const interpreters = normalizeInterpreters(spec.interpreters as any);
+  const config: Config = {
     root,
     output,
     base,
     title,
-    sidebar,
-    pages,
+    sidebar: sidebar!, // see below
+    pages: pages!, // see below
     pager,
     scripts,
     head,
     header,
     footer,
     toc,
     style,
-    deploy,
     search,
     md,
     loaders: new LoaderResolver({root, interpreters}),
@@ -194,45 +230,49 @@ export function normalizeConfig(spec: any = {}, defaultRoot = "docs", watchPath?
   return config;
 }
 
-function normalizeBase(base: any): string {
-  base = String(base);
+function defaultFooter(): string {
+  const date = currentDate ?? new Date();
+  return `Built with <a href="https://observablehq.com/" target="_blank">Observable</a> on <a title="${formatIsoDate(
+    date
+  )}">${formatLocaleDate(date)}</a>.`;
+}
+
+function normalizeBase(spec: unknown): string {
+  let base = String(spec);
   if (!base.startsWith("/")) throw new Error(`base must start with slash: ${base}`);
   if (!base.endsWith("/")) base += "/";
   return base;
 }
 
-export function normalizeTheme(spec: any): string[] {
-  return resolveTheme(typeof spec === "string" ? [spec] : spec === null ? [] : Array.from(spec, String));
+export function normalizeTheme(spec: unknown): string[] {
+  return resolveTheme(typeof spec === "string" ? [spec] : spec === null ? [] : Array.from(spec as any, String));
 }
 
-function normalizeScript(spec: any): Script {
-  if (typeof spec === "string") spec = {src: spec};
-  let {src, async = false, type} = spec;
-  src = String(src);
-  async = Boolean(async);
-  type = type == null ? null : String(type);
+function normalizeScript(spec: unknown): Script {
+  const script = typeof spec === "string" ? {src: spec} : (spec as ScriptSpec);
+  const src = String(script.src);
+  const async = script.async === undefined ? false : Boolean(script.async);
+  const type = script.type == null ? null : String(script.type);
   return {src, async, type};
 }
 
-function normalizePages(spec: any): Config["pages"] {
-  return Array.from(spec, (spec: any) =>
-    "pages" in spec ? normalizeSection(spec, (spec: any) => normalizePage(spec)) : normalizePage(spec)
+function normalizePages(spec: unknown): Config["pages"] {
+  return Array.from(spec as any, (spec: SectionSpec | PageSpec) =>
+    "pages" in spec ? normalizeSection(spec, (spec: PageSpec) => normalizePage(spec)) : normalizePage(spec)
   );
 }
 
-function normalizeSection<T>(spec: any, normalizePage: (spec: any) => T): Section<T> {
-  let {name, open, collapsible = open === undefined ? false : true, pages} = spec;
-  name = String(name);
-  collapsible = Boolean(collapsible);
-  open = collapsible ? Boolean(open) : true;
-  pages = Array.from(pages, normalizePage);
+function normalizeSection<T>(spec: SectionSpec, normalizePage: (spec: PageSpec) => T): Section<T> {
+  const name = String(spec.name);
+  const collapsible = spec.collapsible === undefined ? spec.open !== undefined : Boolean(spec.collapsible);
+  const open = collapsible ? Boolean(spec.open) : true;
+  const pages = Array.from(spec.pages as any, normalizePage);
   return {name, collapsible, open, pages};
 }
 
-function normalizePage(spec: any): Page {
-  let {name, path} = spec;
-  name = String(name);
-  path = String(path);
+function normalizePage(spec: PageSpec): Page {
+  const name = String(spec.name);
+  let path = String(spec.path);
   if (isAssetPath(path)) {
     const u = parseRelativeUrl(join("/", path)); // add leading slash
     let {pathname} = u;
@@ -243,19 +283,18 @@ function normalizePage(spec: any): Page {
   return {name, path};
 }
 
-function normalizeInterpreters(spec: any): Record<string, string[] | null> {
+function normalizeInterpreters(spec: {[key: string]: unknown} = {}): {[key: string]: string[] | null} {
   return Object.fromEntries(
-    Object.entries<any>(spec ?? {}).map(([key, value]): [string, string[] | null] => {
-      return [String(key), value == null ? null : Array.from(value, String)];
+    Object.entries(spec).map(([key, value]): [string, string[] | null] => {
+      return [String(key), value == null ? null : Array.from(value as any, String)];
     })
   );
 }
 
-function normalizeToc(spec: any): TableOfContents {
-  if (typeof spec === "boolean") spec = {show: spec};
-  let {label = "Contents", show = true} = spec;
-  label = String(label);
-  show = Boolean(show);
+function normalizeToc(spec: TableOfContentsSpec | boolean = true): TableOfContents {
+  const toc = typeof spec === "boolean" ? {show: spec} : (spec as TableOfContentsSpec);
+  const label = toc.label === undefined ? "Contents" : String(toc.label);
+  const show = toc.show === undefined ? true : Boolean(toc.show);
   return {label, show};
 }
 

src/deploy.ts

@@ -98,17 +98,6 @@ export async function deploy(
     );
   }
 
-  const legacyConfig = config as unknown as {deploy: null | {project: string; workspace: string}};
-  if (legacyConfig.deploy && deployConfig.projectId) {
-    if (!deployConfig.projectSlug || !deployConfig.workspaceLogin) {
-      clack.log.info("Copying deploy information from the config file to deploy.json.");
-      deployConfig.projectSlug = legacyConfig.deploy.project;
-      deployConfig.workspaceLogin = legacyConfig.deploy.workspace.replace(/^@/, "");
-      effects.setDeployConfig(config.root, deployConfig);
-    }
-    clack.log.info("The `deploy` section of your config file is obsolete and can be deleted.");
-  }
-
   let currentUser: GetCurrentUserResponse | null = null;
   let authError: null | "unauthenticated" | "forbidden" = null;
   try {
@@ -351,7 +340,7 @@ export async function deploy(
   });
 
   // Create the new deploy on the server
-  let deployId;
+  let deployId: string;
   try {
     deployId = await apiClient.postDeploy({projectId: deployTarget.project.id, message});
   } catch (error) {
@@ -375,7 +364,7 @@ export async function deploy(
   uploadSpinner.start("");
 
   const rateLimiter = new RateLimiter(5);
-  const waitForRateLimit = buildFilePaths.length <= 300 ? () => {} : () => rateLimiter.wait();
+  const waitForRateLimit = buildFilePaths.length <= 300 ? async () => {} : () => rateLimiter.wait();
 
   await runAllWithConcurrencyLimit(
     buildFilePaths,

src/markdown.ts

@@ -308,13 +308,19 @@ export interface ParseOptions {
 
 export function createMarkdownIt({
   markdownIt,
+  linkify = true,
+  quotes = "“”‘’",
+  typographer = false,
   cleanUrls = true
 }: {
   markdownIt?: (md: MarkdownIt) => MarkdownIt;
+  linkify?: boolean;
+  quotes?: string | string[];
+  typographer?: boolean;
   cleanUrls?: boolean;
 } = {}): MarkdownIt {
-  const md = MarkdownIt({html: true, linkify: true});
-  md.linkify.set({fuzzyLink: false, fuzzyEmail: false});
+  const md = MarkdownIt({html: true, linkify, typographer, quotes});
+  if (linkify) md.linkify.set({fuzzyLink: false, fuzzyEmail: false});
   md.use(MarkdownItAnchor, {permalink: MarkdownItAnchor.permalink.headerLink({class: "observablehq-header-anchor"})});
   md.inline.ruler.push("placeholder", transformPlaceholderInline);
   md.core.ruler.before("linkify", "placeholder", transformPlaceholderCore);

test/config-test.ts

@@ -35,10 +35,6 @@ describe("readConfig(undefined, root)", () => {
       header: "",
       footer:
         'Built with <a href="https://observablehq.com/" target="_blank">Observable</a> on <a title="2024-01-10T16:00:00">Jan 10, 2024</a>.',
-      deploy: {
-        workspace: "acme",
-        project: "bi"
-      },
       search: false,
       watchPath: resolve("test/input/build/config/observablehq.config.js")
     });
@@ -62,7 +58,6 @@ describe("readConfig(undefined, root)", () => {
       header: "",
       footer:
         'Built with <a href="https://observablehq.com/" target="_blank">Observable</a> on <a title="2024-01-10T16:00:00">Jan 10, 2024</a>.',
-      deploy: null,
       search: false,
       watchPath: undefined
     });
@@ -164,20 +159,6 @@ describe("normalizeConfig(spec, root)", () => {
   it("populates default pager", () => {
     assert.strictEqual(config({pages: []}, root).pager, true);
   });
-  describe("deploy", () => {
-    it("considers deploy optional", () => {
-      assert.strictEqual(config({pages: []}, root).deploy, null);
-    });
-    it("coerces workspace", () => {
-      assert.strictEqual(config({pages: [], deploy: {workspace: 538, project: "bi"}}, root).deploy?.workspace, "538");
-    });
-    it("strips leading @ from workspace", () => {
-      assert.strictEqual(config({pages: [], deploy: {workspace: "@acme"}}, root).deploy?.workspace, "acme");
-    });
-    it("coerces project", () => {
-      assert.strictEqual(config({pages: [], deploy: {workspace: "adams", project: 42}}, root).deploy?.project, "42");
-    });
-  });
 });
 
 describe("mergeToc(spec, toc)", () => {