sass-site/tool/typedoc-theme.js

const {DefaultTheme, DefaultThemeRenderContext, JSX, UrlMapping} = require('typedoc');

function bind(fn, first) {
  return (...r) => fn(first, ...r);
}

class SassSiteRenderContext extends DefaultThemeRenderContext {
  // Link to the external documentation of external APIs. Unfortunately, there's
  // no way to use `addUnknownSymbolResolver` for names that don't come from npm
  // packages.
  attemptExternalResolution = function(symbol) {
    if (symbol.escapedName === 'URL') {
      return 'https://developer.mozilla.org/en-US/docs/Web/API/URL';
    } else if (symbol.escapedName === 'Buffer') {
      return 'https://nodejs.org/api/buffer.html';
    } else {
      return null;
    }
  };

  // We don't include Typedoc's JS, so the default means of displaying overloads
  // as multiple togglable definitions within a single member documentation
  // doesn't work. Instead, we emit each overload as a separate entry with its
  // own panel.
  oldMember = this.member;
  member = bind(function(context, props) {
    const signatures = props?.signatures;
    if (signatures && signatures.length > 1) {
      const element = JSX.createElement(JSX.Fragment, null,
        ...signatures.map(signature => {
          props.signatures = [signature];
          return context.oldMember(props);
        }));
      props.signatures = signatures;
      return element;
    }

    return context.oldMember(props);
  }, this);

  // Make categories visible in the sidebar as well as in the main page's index.
  // Hopefully this will no longer be necessary once TypeStrong/typedoc#1532 is
  // implemented.
  oldNavigation = this.navigation;
  navigation = bind(function(context, props) {
    const navigation = context.oldNavigation(props);
    const childrenByCategories = context._groupByCategory(props.model);
    if (childrenByCategories.size === 0) return navigation;

    const secondary = context._getNthChild(navigation, 1);
    if (!secondary) return navigation;

    const firstLI = context._getNthChild(context._getNthChild(secondary, 0), 0);
    const ul = firstLI.props["class"].startsWith("current ")
        ? context._getNthChild(firstLI, 1)
        : context._getNthChild(secondary, 0);

    ul.children = Array.from(childrenByCategories).map(([title, children]) =>
        JSX.createElement(JSX.Fragment, null,
            JSX.createElement("li", {class: "sl-tsd-category-label"},
                JSX.createElement("span", null, title)),
            ...children.map(child =>
                JSX.createElement("li", {class: child.cssClasses},
                    JSX.createElement("a", {
                      href: context.urlTo(child), class: "tsd-kind-icon"
                    }, child.name)))));

    return navigation;
  }, this);

  // Returns the `n`-th child of a JSX node. For some reason, JSX nodes created
  // by TypeDoc can contain nested arrays, so this traverses them.
  _getNthChild = (node, n) => {
    let i = 0;

    function traverse(array) {
      for (const element of array) {
        if (element instanceof Array) {
          const result = traverse(element);
          if (result != undefined) return result;
        } else {
          if (i === n) return element;
          i++;
        }
      }
    }

    return traverse(node.children);
  };

  // Returns a map from category titles to the set of members of those
  // categories.
  _groupByCategory = (model) => {
    const map = new Map();
    function addCategoriesToMap(categories) {
      for (const category of categories) {
        const children = map.get(category.title);
        if (children) {
          children.push(...category.children);
        } else {
          map.set(category.title, [...category.children]);
        }
      }
    }

    if (model.categories) {
      addCategoriesToMap(model.categories);
    } else if (model.groups) {
      for (const group of model.groups) {
        if (group.categories) addCategoriesToMap(group.categories);
      }
    }

    return map;
  };

  // Add compatibility indicators to the beginning of documentation blocks.
  oldComment = this.comment;
  comment = bind((context, props) => {
    const compatibilityTags = props.comment?.tags
        .filter(tag => tag.tagName === "compatibility");
    props.comment?.removeTags("compatibility");

    const parent = this.oldComment(props);
    if (!parent) return;

    parent.children.unshift(...compatibilityTags.map(compat => {
      // The first line is arguments to impl_status, anything after that is the
      // contents of the block.
      const lineBreak = compat.text.indexOf("\n");
      const firstLine =
          lineBreak === -1 ? compat.text : compat.text.substring(0, lineBreak);
      const rest =
          lineBreak === -1 ? null : compat.text.substring(lineBreak + 1).trim();

      return JSX.createElement(JSX.Raw, {
        html: `<% impl_status(${firstLine}) ${rest ? 'do' : ''} %>` +
            context.markdown(rest) +
            (rest ? '<% end %>' : '')
      });
    }));

    return parent;
  }, this);

  // Convert paragraphs that start with **Heads up!** or **Fun fact!** into
  // proper callouts.
  oldMarkdown = this.markdown;
  markdown = bind((context, text) =>
      context.oldMarkdown(text)
          .replace(
              /<p><strong>Heads up!<\/strong>([^]*?)<\/p>/g,
              '<% heads_up do %>$1<% end %>')
          .replace(
              /<p><strong>Fun fact!<\/strong>([^]*?)<\/p>/g,
              '<% fun_fact do %>$1<% end %>'),
      this);
}

class SassSiteTheme extends DefaultTheme {
  constructor(renderer) {
    super(renderer);

    // This is an ugly monkeypatch but it's necessary to work around
    // TypeStrong/typedoc#1731.
    //
    // Relative URLs don't work well for index pages since they can be rendered at
    // different directory levels, so we just convert all URLs to absolute to be
    // safe.
    const ContextAwareRendererComponent =
        Object.getPrototypeOf(this.markedPlugin.constructor);
    const oldGetRelativeUrl =
        ContextAwareRendererComponent.prototype.getRelativeUrl;
    ContextAwareRendererComponent.prototype.getRelativeUrl = function(url) {
      const relative = oldGetRelativeUrl.call(this, url);

      const absolute = new URL(
        relative,
        `relative:///documentation/js-api/${this.location}`
      );
      absolute.pathname = absolute.pathname
        .replace(/\.html$/, '')
        .replace(/\/index$/, '');
      return absolute.toString().replace(/^relative:\/\//, '');
    };
  }

  getRenderContext() {
    this.contextCache ??=
        new SassSiteRenderContext(this, this.application.options);
    return this.contextCache;
  }

  render(page) {
    const context = this.getRenderContext(page);

    // The default header includes a search bar that we don't want, so we just
    // render title on its own.
    const breadcrumb = page.model.parent
      ? `<ul class="tsd-breadcrumb">${JSX.renderElement(
          context.breadcrumb(page.model)
        )}</ul>`
      : '';
    const heading =
      (page.model.kindString === 'Project'
        ? ''
        : `${page.model.kindString || ''} `) +
      page.model.name +
      (page.model.typeParameters
        ? `&lt;${page.model.typeParameters
            .map(item => item.name)
            .join(', ')}&gt;`
        : '');

    // The default template renders a full HTML document, but for the Sass site
    // we want it to be a page within the normal layout so we just render the
    // contents with a header that provides the title tag. We also wrap it in a
    // div with class "typedoc" so we can isolate the typedoc-specific CSS.
    return `---
title: ${JSON.stringify(`${page.model.name} | JS API`)}
---

<div class="typedoc">
  <header>
    <div class="tsd-page-title">
      <div class="container">
        ${breadcrumb}
        <h1>${heading}</h1>
      </div>
    </div>    
  </header>

  <div class="container container-main">
    <div class="row">
      <div class="col-8 col-content">
        ${JSX.renderElement(page.template(page))}
      </div>
      <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
        ${JSX.renderElement(context.navigation(page))}
      </div>
    </div>
  </div>
</div>
`;
  }

  getUrls(project) {
    return super
      .getUrls(project)
      .map(
        mapping =>
          new UrlMapping(`${mapping.url}.erb`, mapping.model, mapping.template)
      );
  }
}

// TODO: See if there's a graceful way to support "Heads up!" and Compatibility
// annotations as @-tags rather than needing to write out the HTML by hand.

exports.load = app => {
  app.renderer.addUnknownSymbolResolver('immutable', (name) =>
      `https://immutable-js.com/docs/latest@main/${name}/`);
  app.renderer.addUnknownSymbolResolver('source-map-js', (name) => {
    if (name === 'RawSourceMap') {
      return 'https://github.com/mozilla/source-map/blob/58819f09018d56ef84dc41ba9c93f554e0645169/source-map.d.ts#L15-L23';
    }
  });

  app.renderer.defineTheme('sass-site', SassSiteTheme);
};