Merge branch 'port-documentation-var-interp-atrules' of github.com:oddbird/sass-site into port-documentation-var-interp-atrules

.prettierignore

@@ -5,6 +5,7 @@
 .yarnrc
 .yarnrc.yml
 /_site/
+/data/
 /old_source/
 /source/_data/versionCache.json
 /source/blog/*.md

config.rb

@@ -52,7 +52,7 @@ page '/blog/*',                    :layout => :blog
 
 for dir in ['docs/yardoc', 'documentation'] do
   redirect "#{dir}/file.SASS_REFERENCE.html", to: '/documentation'
-  redirect "#{dir}/file.SASS_CHANGELOG.html", to: 'https://github.com/sass/dart-sass/blob/main/CHANGELOG.md'
+  redirect "#{dir}/file.SASS_CHANGELOG.html", to: 'https://github.com/sass/dart-sass/blob/master/CHANGELOG.md'
   redirect "#{dir}/file.INDENTED_SYNTAX.html", to: '/documentation/syntax'
   redirect "#{dir}/file.SCSS_FOR_SASS_USERS.html", to: '/documentation/syntax'
   redirect "#{dir}/Sass/Script/Functions.html", to: '/documentation/modules'
@@ -60,13 +60,13 @@ for dir in ['docs/yardoc', 'documentation'] do
   redirect "#{dir}/functions.html", to: '/documentation/modules'
   redirect "#{dir}/functions/css.html", to: '/documentation/at-rules/function#plain-css-functions'
 
-  Dir['old_source/documentation/modules/*.html.md.erb'].each do |file|
+  Dir['source/documentation/modules/*.html.md.erb'].each do |file|
     module_name = File.basename(file, ".html.md.erb")
     redirect "#{dir}/functions/#{module_name}.html", to: "/documentation/modules/#{module_name}"
   end
 end
 
-Dir['old_source/documentation/breaking-changes/**'].each do |file|
+Dir['source/documentation/breaking-changes/**'].each do |file|
   basename = File.basename(file).gsub(/\..*/, '')
   redirect "d/#{basename}.html", to: "/documentation/breaking-changes/#{basename}"
 end
@@ -154,7 +154,7 @@ end
 
 after_render do |content, path, locs|
   # Only modify the original page's rendering.
-  next if path.include?("old_source/layouts/")
+  next if path.include?("source/layouts/")
 
   content.gsub(%r{^<(h[0-6])(.*?)</\1>}m) do |header_text|
     header = Nokogiri::HTML::DocumentFragment.parse(header_text).children.first

data/color.yml

@@ -1,57 +1,57 @@
 colors:
   - name: hopbush
-    hex: 'c69'
+    hex:  "c69"
   - name: bouquet
-    hex: 'b37399'
+    hex:  "b37399"
   - name: venus
-    hex: '998099'
+    hex:  "998099"
   - name: patina
-    hex: '699'
+    hex:  "699"
   - name: nebula
-    hex: 'd2e1dd'
+    hex:  "d2e1dd"
   - name: white
-    hex: 'fff'
+    hex:  "fff"
   - name: dawn-pink
-    hex: 'f2ece4'
+    hex:  "f2ece4"
   - name: wafer
-    hex: 'e1d7d2'
+    hex:  "e1d7d2"
   - name: iron
-    hex: 'dadbdf'
+    hex:  "dadbdf"
   - name: regent-grey
-    hex: '808c99'
+    hex:  "808c99"
   - name: pale-sky
-    hex: '6b717f'
+    hex:  "6b717f"
   - name: midnight-blue
-    hex: '036'
+    hex:  "036"
 
 semantic_colors:
-  - name: shadow
-    value: 'rgba($black, .125)'
-  - name: primary
-    value: '$hopbush'
-  - name: accent
-    value: '$patina'
-  - name: background
-    value: '$white'
-  - name: background-shade
-    value: '$iron'
-  - name: background-invert
-    value: '$hopbush'
-  - name: text
-    value: 'darken($pale-sky, 15%)'
-  - name: text-weak
-    value: 'darken($regent-grey, 10%)'
-  - name: text-strong
-    value: '$midnight-blue'
-  - name: text-heading
-    value: '$regent-grey'
-  - name: text-invert
-    value: '$color-background'
-  - name: text-strong-invert
-    value: '$color-background'
-  - name: text-link
-    value: '$color-primary'
-  - name: text-link-hover
-    value: '$midnight-blue'
-  - name: border
-    value: '$iron'
+  - name:  shadow
+    value: "rgba($black, .125)"
+  - name:  primary
+    value: "$hopbush"
+  - name:  accent
+    value: "$patina"
+  - name:  background
+    value: "$white"
+  - name:  background-shade
+    value: "$iron"
+  - name:  background-invert
+    value: "$hopbush"
+  - name:  text
+    value: "darken($pale-sky, 15%)"
+  - name:  text-weak
+    value: "darken($regent-grey, 10%)"
+  - name:  text-strong
+    value: "$midnight-blue"
+  - name:  text-heading
+    value: "$regent-grey"
+  - name:  text-invert
+    value: "$color-background"
+  - name:  text-strong-invert
+    value: "$color-background"
+  - name:  text-link
+    value: "$color-primary"
+  - name:  text-link-hover
+    value: "$midnight-blue"
+  - name:  border
+    value: "$iron"

data/documentation.yml

@@ -1,77 +1,77 @@
 toc:
-  - Syntax: /documentation/syntax
+- Syntax: /documentation/syntax
+  :children:
+  - Parsing a Stylesheet: /documentation/syntax/parsing
+  - Structure of a Stylesheet: /documentation/syntax/structure
+  - Comments: /documentation/syntax/comments
+  - Special Functions: /documentation/syntax/special-functions
+- Style Rules: /documentation/style-rules
+  :children:
+  - Property Declarations: /documentation/style-rules/declarations
+  - Parent Selector: /documentation/style-rules/parent-selector
+  - Placeholder Selectors: /documentation/style-rules/placeholder-selectors
+- Variables: /documentation/variables
+- Interpolation: /documentation/interpolation
+- At-Rules: /documentation/at-rules
+  :children:
+  - <code>@use</code>: /documentation/at-rules/use
+  - <code>@forward</code>: /documentation/at-rules/forward
+  - <code>@import</code>: /documentation/at-rules/import
+  - <code>@mixin</code> and <code>@include</code>: /documentation/at-rules/mixin
+  - <code>@function</code>: /documentation/at-rules/function
+  - <code>@extend</code>: /documentation/at-rules/extend
+  - <code>@error</code>: /documentation/at-rules/error
+  - <code>@warn</code>: /documentation/at-rules/warn
+  - <code>@debug</code>: /documentation/at-rules/debug
+  - <code>@at-root</code>: /documentation/at-rules/at-root
+  - Flow Control: /documentation/at-rules/control
     :children:
-      - Parsing a Stylesheet: /documentation/syntax/parsing
-      - Structure of a Stylesheet: /documentation/syntax/structure
-      - Comments: /documentation/syntax/comments
-      - Special Functions: /documentation/syntax/special-functions
-  - Style Rules: /documentation/style-rules
-    :children:
-      - Property Declarations: /documentation/style-rules/declarations
-      - Parent Selector: /documentation/style-rules/parent-selector
-      - Placeholder Selectors: /documentation/style-rules/placeholder-selectors
-  - Variables: /documentation/variables
-  - Interpolation: /documentation/interpolation
-  - At-Rules: /documentation/at-rules
-    :children:
-      - <code>@use</code>: /documentation/at-rules/use
-      - <code>@forward</code>: /documentation/at-rules/forward
-      - <code>@import</code>: /documentation/at-rules/import
-      - <code>@mixin</code> and <code>@include</code>: /documentation/at-rules/mixin
-      - <code>@function</code>: /documentation/at-rules/function
-      - <code>@extend</code>: /documentation/at-rules/extend
-      - <code>@error</code>: /documentation/at-rules/error
-      - <code>@warn</code>: /documentation/at-rules/warn
-      - <code>@debug</code>: /documentation/at-rules/debug
-      - <code>@at-root</code>: /documentation/at-rules/at-root
-      - Flow Control: /documentation/at-rules/control
-        :children:
-          - <code>@if</code> and <code>@else</code>: /documentation/at-rules/control/if
-          - <code>@each</code>: /documentation/at-rules/control/each
-          - <code>@for</code>: /documentation/at-rules/control/for
-          - <code>@while</code>: /documentation/at-rules/control/while
-      - From CSS: /documentation/at-rules/css
-  - Values: /documentation/values
-    :children:
-      - Numbers: /documentation/values/numbers
-      - Strings: /documentation/values/strings
-      - Colors: /documentation/values/colors
-      - Lists: /documentation/values/lists
-      - Maps: /documentation/values/maps
-      - <code>true</code> and <code>false</code>: /documentation/values/booleans
-      - <code>null</code>: /documentation/values/null
-      - Calculations: /documentation/values/calculations
-      - Functions: /documentation/values/functions
-  - Operators: /documentation/operators
-    :children:
-      - Equality: /documentation/operators/equality
-      - Relational: /documentation/operators/relational
-      - Numeric: /documentation/operators/numeric
-      - String: /documentation/operators/string
-      - Boolean: /documentation/operators/boolean
-  - Built-In Modules: /documentation/modules
-    :children:
-      - <code>sass:color</code>: /documentation/modules/color
-      - <code>sass:list</code>: /documentation/modules/list
-      - <code>sass:map</code>: /documentation/modules/map
-      - <code>sass:math</code>: /documentation/modules/math
-      - <code>sass:meta</code>: /documentation/modules/meta
-      - <code>sass:selector</code>: /documentation/modules/selector
-      - <code>sass:string</code>: /documentation/modules/string
-  - Breaking Changes: /documentation/breaking-changes
-    :children:
-      - Strict Unary Operators: /documentation/breaking-changes/strict-unary
-      - Random With Units: /documentation/breaking-changes/random-with-units
-      - Invalid Combinators: /documentation/breaking-changes/bogus-combinators
-      - Media Queries Level 4: /documentation/breaking-changes/media-logic
-      - <code>/</code> as Division: /documentation/breaking-changes/slash-div
-      - Function Units: /documentation/breaking-changes/function-units
-      - <code>-moz-document</code>: /documentation/breaking-changes/moz-document
-      - Extending Compound Selectors: /documentation/breaking-changes/extend-compound
-      - CSS Variable Syntax: /documentation/breaking-changes/css-vars
-  - Command Line: /documentation/cli
-    :children:
-      - Dart Sass: /documentation/cli/dart-sass
-      - Ruby Sass: /documentation/cli/ruby-sass
-      - Migrator: /documentation/cli/migrator
-  - JavaScript API: /documentation/js-api
+    - <code>@if</code> and <code>@else</code>: /documentation/at-rules/control/if
+    - <code>@each</code>: /documentation/at-rules/control/each
+    - <code>@for</code>: /documentation/at-rules/control/for
+    - <code>@while</code>: /documentation/at-rules/control/while
+  - From CSS: /documentation/at-rules/css
+- Values: /documentation/values
+  :children:
+  - Numbers: /documentation/values/numbers
+  - Strings: /documentation/values/strings
+  - Colors: /documentation/values/colors
+  - Lists: /documentation/values/lists
+  - Maps: /documentation/values/maps
+  - <code>true</code> and <code>false</code>: /documentation/values/booleans
+  - <code>null</code>: /documentation/values/null
+  - Calculations: /documentation/values/calculations
+  - Functions: /documentation/values/functions
+- Operators: /documentation/operators
+  :children:
+  - Equality: /documentation/operators/equality
+  - Relational: /documentation/operators/relational
+  - Numeric: /documentation/operators/numeric
+  - String: /documentation/operators/string
+  - Boolean: /documentation/operators/boolean
+- Built-In Modules: /documentation/modules
+  :children:
+  - <code>sass:color</code>: /documentation/modules/color
+  - <code>sass:list</code>: /documentation/modules/list
+  - <code>sass:map</code>: /documentation/modules/map
+  - <code>sass:math</code>: /documentation/modules/math
+  - <code>sass:meta</code>: /documentation/modules/meta
+  - <code>sass:selector</code>: /documentation/modules/selector
+  - <code>sass:string</code>: /documentation/modules/string
+- Breaking Changes: /documentation/breaking-changes
+  :children:
+  - Strict Unary Operators: /documentation/breaking-changes/strict-unary
+  - Random With Units: /documentation/breaking-changes/random-with-units
+  - Invalid Combinators: /documentation/breaking-changes/bogus-combinators
+  - Media Queries Level 4: /documentation/breaking-changes/media-logic
+  - <code>/</code> as Division: /documentation/breaking-changes/slash-div
+  - Function Units: /documentation/breaking-changes/function-units
+  - <code>-moz-document</code>: /documentation/breaking-changes/moz-document
+  - Extending Compound Selectors: /documentation/breaking-changes/extend-compound
+  - CSS Variable Syntax: /documentation/breaking-changes/css-vars
+- Command Line: /documentation/cli
+  :children:
+  - Dart Sass: /documentation/cli/dart-sass
+  - Ruby Sass: /documentation/cli/ruby-sass
+  - Migrator: /documentation/cli/migrator
+- JavaScript API: /documentation/js-api

data/layout.yml

@@ -1,13 +1,13 @@
 resolutions:
   - target: small
-    width: 480
+    width:  480
     height: 640
   - target: medium
-    width: 640
+    width:  640
     height: 960
   - target: large
-    width: 960
+    width:  960
     height: 1280
   - target: x-large
-    width: 1280
+    width:  1280
     height: 1920

data/libsass.yml

@@ -1,7 +1,7 @@
 resources:
-  - name: 'Lightning fast Sass compiling with libsass, Node-sass and Grunt-sass'
-    url: 'http://benfrain.com/lightning-fast-sass-compiling-with-libsass-node-sass-and-grunt-sass/'
-    description: 'by Ben Frain, August 2013'
-  - name: 'Node, Express and libSass'
-    url: 'https://anotheruiguy.gitbooks.io/nodeexpreslibsass_from-scratch/content/index.html'
-    description: 'Node, Express and libSass: a project from scratch workshop'
+  - name: "Lightning fast Sass compiling with libsass, Node-sass and Grunt-sass"
+    url: "http://benfrain.com/lightning-fast-sass-compiling-with-libsass-node-sass-and-grunt-sass/"
+    description: "by Ben Frain, August 2013"
+  - name: "Node, Express and libSass"
+    url: "https://anotheruiguy.gitbooks.io/nodeexpreslibsass_from-scratch/content/index.html"
+    description: "Node, Express and libSass: a project from scratch workshop"

data/typography.yml

@@ -1,26 +1,26 @@
 sizes:
-  - name: small
+  - name:  small
     value: 12
-  - name: medium
+  - name:  medium
     value: 16
-  - name: large
+  - name:  large
     value: 24
-  - name: x-large
+  - name:  x-large
     value: 32
-  - name: xx-large
+  - name:  xx-large
     value: 48
-  - name: xxx-large
+  - name:  xxx-large
     value: 64
-  - name: xxxx-large
+  - name:  xxxx-large
     value: 96
 
 weights:
   - weight: light
-    value: 300
+    value:  300
   - weight: regular
-    value: 400
+    value:  400
   - weight: bold
-    value: 600
+    value:  600
 
 families:
   - style: text

old_source/assets/css/sass.css.scss

@@ -12,7 +12,6 @@
   'vendor/jquery-ui-custom/jquery-ui-theme',
   'vendor/typedoc/style',
   'vendor/typedoc/highlight',
-  'vendor/typedoc/icons',
 
   'functions',
   'breakpoints',

source/_layouts/blog.liquid

@@ -3,4 +3,6 @@ layout: base
 ---
 {% render 'attribution', date: page.date, author: author %}
 
-{{ content }}
+<div class="sl-l-container sl-l-container--small">
+  {{ content }}
+</div>

source/_layouts/has_both_sidebars.liquid

@@ -7,8 +7,8 @@ layout: base
     {% render 'navigation', contents: navigation %}
 
     <div class="sl-l-medium-holy-grail__main">
-      <div class="sl-l-medium-holy-grail">
-        <div class="sl-l-medium-holy-grail__body">
+      <div class="sl-l-large-holy-grail">
+        <div class="sl-l-large-holy-grail__body">
           {% if complementary_content %}
             <div class="sl-l-large-holy-grail__complementary{% if table_of_contents %} sl-l-large-holy-grail__complementary--contents{% endif %}">
               {{ complementary_content | markdown }}

source/assets/sass/sass.scss

@@ -11,7 +11,6 @@
 @use 'vendor/jquery-ui-custom/jquery-ui-theme';
 @use 'vendor/typedoc/style';
 @use 'vendor/typedoc/highlight';
-@use 'vendor/typedoc/icons';
 @use 'functions';
 @use 'breakpoints';
 @use 'visual-design/theme';

source/community.md

@@ -29,13 +29,13 @@ complementary_content: |
 Please read and follow our [community guidelines](/community-guidelines).
 
 Thinking of **contributing** to Sass itself? We rely on everyone to keep Sass as
-stable as it is. Feel free to [submit a patch via pull request](#Contribute) to
+stable as it is. Feel free to [submit a patch via pull request](#contribute) to
 the Sass project.
 
 Want to create your own Sass implementation? Check out our [implementation
 guidelines](/implementation).
 
-## Contribute {#Contribute}
+## Contribute
 
 Sass is an [open source project][github] and we encourage you to contribute. You
 can contribute with [bug reports and feature requests][issues], and if you

source/guide.liquid

@@ -204,7 +204,7 @@ partials are used with the `@use` rule.
 {% # retain older link %}
 <span id="topic-5"></span>
 
-<h2>Modules</h2>
+{{ '## Modules' | markdown }}
 
 {% render 'documentation/snippets/module-system-status' %}
 

source/helpers/engines.ts

@@ -21,7 +21,7 @@ export const markdownEngine = markdown({
   .use(markdownDefList)
   .use(markdownItAttrs)
   .use(markdownAnchor, {
-    level: [2, 3],
+    level: 2,
     permalink: renderPermalink,
   });
 

source/implementation.md

@@ -10,7 +10,7 @@ introduction: >
 <ul class="list-tiled">
 <li>
 
-## Resources
+<h2>Resources</h2>
 
 - [`sass-spec`](https://github.com/sass/sass-spec) is a suite of
   implementation-agnostic test cases for verifying that a Sass
@@ -32,7 +32,7 @@ introduction: >
 </li>
 <li>
 
-## Requirements
+<h2>Requirements</h2>
 
 We whole-heartedly love new implementations of Sass, but we do have a
 few restrictions that we ask those implementations to follow in order to
@@ -57,7 +57,7 @@ important that there be a unified vision for the language design.
 </li>
 <li>
 
-## Making Language Changes
+<h2>Making Language Changes</h2>
 
 Sass can still evolve as a language, of course. We have [a process][] for
 proposing and iterating on new language features that anyone can

source/libsass.md

@@ -51,7 +51,7 @@ Below are the LibSass wrappers that we're currently aware of. Sometimes there
 are multiple wrappers per language -- in those cases, we put the most
 recently-updated wrapper first.
 
-- ### Sass C {#sassc}
+- <h3 id="sassc">Sass C</h3>
 
   [SassC](https://github.com/sass/sassc) (get it?) is a wrapper written in C.
 
@@ -71,12 +71,12 @@ recently-updated wrapper first.
   ./bin/sassc [input file] > output.css
   ```
 
-- ### Crystal {#crystal}
+- <h3 id="crystal">Crystal</h3>
 
   [sass.cr](https://github.com/straight-shoota/sass.cr) is a LibSass wrapper for
   the [Crystal programming language](https://crystal-lang.org/).
 
-- ### Go {#go}
+- <h3 id="go">Go</h3>
 
   [go-libsass](https://github.com/wellington/go-libsass) has the most active
   GoLang wrapper. [gosass](https://github.com/moovweb/gosass) is another LibSass
@@ -87,24 +87,24 @@ recently-updated wrapper first.
   [wellington/sass](https://github.com/wellington/sass) is an in-progress pure
   Go Sass lexer, parser, and compiler.
 
-- ### Java {#java}
+- <h3 id="java">Java</h3>
 
   There is one Java wrapper --- [jsass](https://github.com/bit3/jsass). There is
   also a plugin for Maven --- [LibSass Maven
   plugin](https://gitlab.com/haynes/libsass-maven-plugin).
 
-- ### JavaScript {#javascript}
+- <h3 id="javascript">JavaScript</h3>
 
   The [sass.js](https://github.com/medialize/sass.js) project makes LibSass
   available as pure JavaScript. There's a way to [test it in the
   browser](https://sass.js.org/), too.
 
-- ### Lua {#lua}
+- <h3 id="lua">Lua</h3>
 
   The Lua wrapper is found at
   [lua-sass](https://github.com/craigbarnes/lua-sass).
 
-- ### .NET {#net}
+- <h3 id="net">.NET</h3>
 
   [LibSass Host](https://github.com/Taritsyn/LibSassHost) is updated regularly,
   and is probably the best bet. There's also
@@ -112,25 +112,25 @@ recently-updated wrapper first.
   [NSass](https://github.com/TBAPI-0KA/NSass), although they haven't been
   updated in a while.
 
-- ### Node {#node}
+- <h3 id="node">Node</h3>
 
   The [node-sass](https://github.com/sass/node-sass) project has proven to be
   popular, and we've taken it into the main Sass GitHub repo. Check out its
   package page [here](https://www.npmjs.com/package/node-sass), and [there's a
   dedicated twitter account](https://twitter.com/nodesass) for updates.
 
-- ### Perl {#perl}
+- <h3 id="perl">Perl</h3>
 
   The [CSS::Sass](https://github.com/sass/perl-libsass) project is updated
   regularly. There's the [Text-Sass-XS](https://github.com/ysasaki/Text-Sass-XS)
   project, too, although it hasn't been updated in a while.
 
-- ### PHP {#php}
+- <h3 id="php">PHP</h3>
 
   The [SassPHP](https://github.com/absalomedia/sassphp) project is an updated
   fork of an [older PHP version](https://github.com/jamierumbelow/sassphp).
 
-- ### Python {#python}
+- <h3 id="python">Python</h3>
 
   The [libsass-python](https://github.com/sass/libsass-python) project is
   updated regularly. There are more details on [its own
@@ -142,24 +142,24 @@ recently-updated wrapper first.
   [SassPython](https://github.com/marianoguerra/SassPython), haven't been
   updated in a while.
 
-- ### Ruby {#ruby}
+- <h3 id="ruby">Ruby</h3>
 
   LibSass has also been ported back into Ruby for the
   [sassc-ruby](https://github.com/sass/sassc-ruby) project.
 
-- ### R {#r}
+- <h3 id="r">R</h3>
 
   The [R](https://www.r-project.org/) [Sass
   package](https://github.com/rstudio/sass) wraps LibSass with additional
   caching and bundling methods. [Extended
   documentation](https://rstudio.github.io/sass/).
 
-- ### Rust {#rust}
+- <h3 id="rust">Rust</h3>
 
   The [`sass_rs`](https://github.com/compass-rs/sass-rs) crate is a LibSass
   wrapper and is updated regularly.
 
-- ### Scala {#scala}
+- <h3 id="scala">Scala</h3>
 
   The only Scala project, [Sass-Scala](https://github.com/kkung/Sass-Scala),
   hasn't been updated in a couple of years.

source/ruby-sass.md

@@ -7,7 +7,7 @@ introduction: >
   migrate to another implementation.
 ---
 
-- ## But Why?
+- <h2>But Why?</h2>
 
   When Natalie and Hampton first created Sass in 2006, Ruby was the language at
   the cutting edge of web development, the basis of their already-successful
@@ -28,7 +28,7 @@ introduction: >
   [Dart Sass]: /dart-sass
   [LibSass]: /libsass
 
-- ## Migrating Away
+- <h2>Migrating Away</h2>
 
   If you run Ruby Sass using the command-line `sass` executable, all you need to
   do is install Dart Sass's [command-line executable][install] instead. The

source/styleguide/color.liquid

@@ -2,7 +2,7 @@
 title: Color & Theming
 ---
 
-<h2>Brand Colors</h2>
+{{ '## Brand Colors' | markdown }}
 
 <ul class="sl-l-grid sl-l-grid--full sl-l-large-grid--divide-by-3 sl-l-large-grid--gutters">
   {% for swatch in colors %}

source/styleguide/components.liquid

@@ -2,7 +2,7 @@
 title: Components
 ---
 
-<h2>Closed</h2>
+{{ '## Closed' | markdown }}
 
 <dl class="sl-c-description-list sl-c-description-list--horizontal">
   <div>
@@ -16,7 +16,7 @@ title: Components
   <div><a href="#">▶︎</a></div>
 </dl>
 
-<h2>Open</h2>
+{{ '## Open' | markdown }}
 
 <dl class="sl-c-description-list sl-c-description-list--horizontal">
   <div>
@@ -34,7 +34,7 @@ title: Components
   <p>{% lorem 'paragraph' %}</p>
 </div>
 
-<h2>Alerts</h2>
+{{ '## Alerts' | markdown }}
 
 <div class="sl-c-alert">
   <div class="sl-l-container">
@@ -54,7 +54,7 @@ title: Components
   </div>
 </div>
 
-<h2>Buttons</h2>
+{{ '## Buttons' | markdown }}
 
 <a href="#" class="sl-c-button">Link</a>
 <button class="sl-c-button" type="button">Button</button>
@@ -62,24 +62,24 @@ title: Components
 <a href="#" class="sl-c-button sl-c-button--primary">Link</a>
 <button class="sl-c-button sl-c-button--primary" type="button">Button</button>
 
-<h2>Callouts</h2>
+{{ '## Callouts' | markdown }}
 
 <div class="sl-c-callout">
-  <h3>Callout</h3>
+  {{ '### Callout' | markdown }}
   <p>{% lorem 'paragraph' %}</p>
 </div>
 
 <div class="sl-c-callout sl-c-callout--warning">
-  <h3>Warning</h3>
+  {{ '### Warning' | markdown }}
   <p>{% lorem 'paragraph' %}</p>
 </div>
 
 <div class="sl-c-callout sl-c-callout--fun-fact">
-  <h3>Fun Fact</h3>
+  {{ '### Fun Fact' | markdown }}
   <p>{% lorem 'paragraph' %}</p>
 </div>
 
-<h2>Introduction</h2>
+{{ '## Introduction' | markdown }}
 
 <p class="sl-c-introduction">
   {% lorem 'paragraph' %}
@@ -89,13 +89,13 @@ title: Components
   <p>{% lorem 'paragraph' %}</p>
 </div>
 
-<h2>Link Headers</h2>
+{{ '## Link Headers' | markdown }}
 
-<h2 id="link-header-2">Link Header 2</h2>
-<h3 id="link-header-3">Link Header 3</h3>
-<h4 id="link-header-4">Link Header 4</h4>
+{{ '## Link Header 2' | markdown }}
+{{ '### Link Header 3' | markdown }}
+{{ '#### Link Header 4' | markdown }}
 
-<h2>Lists</h2>
+{{ '## Lists' | markdown }}
 
 <div class="sl-c-list-navigation-wrapper" style="height: unset; position: unset">
 {% markdown %}
@@ -113,11 +113,11 @@ title: Components
 {% endmarkdown %}
 </div>
 
-<h2>Pop Stripe</h2>
+{{ '## Pop Stripe' | markdown }}
 
 <div class="sl-c-pop-stripe"></div>
 
-<h2>Tables</h2>
+{{ '## Tables' | markdown }}
 
 <table class="sl-c-table">
   <tr>

source/styleguide/typography.liquid

@@ -2,7 +2,7 @@
 title: Typography
 ---
 
-<h2>Families</h2>
+{{ '## Families' | markdown }}
 
 {% for font_family in font_families %}
   <dl class="guide-description-list">

tool/typedoc-theme.js

@@ -10,19 +10,6 @@ function bind(fn, first) {
 }
 
 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
@@ -46,118 +33,30 @@ class SassSiteRenderContext extends DefaultThemeRenderContext {
     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',
+    if (!props.comment) return;
+    const compatibilityTags = props.comment.blockTags.filter(
+      (tag) => tag.tag === '@compatibility',
     );
-    props.comment?.removeTags('compatibility');
+    props.comment.removeTags('@compatibility');
 
     const parent = this.oldComment(props);
     if (!parent) return;
 
     parent.children.unshift(
       ...compatibilityTags.map((compat) => {
+        // Compatibility tags should have a single text block.
+        const text = compat.content[0].text;
+
         // The first line is arguments to impl_status, anything after that is the
         // contents of the block.
-        const lineBreak = compat.text.indexOf('\n');
+        const lineBreak = text.indexOf('\n');
         const firstLine =
-          lineBreak === -1 ? compat.text : compat.text.substring(0, lineBreak);
+          lineBreak === -1 ? text : text.substring(0, lineBreak);
         const rest =
-          lineBreak === -1 ? null : compat.text.substring(lineBreak + 1).trim();
+          lineBreak === -1 ? null : text.substring(lineBreak + 1).trim();
 
         return JSX.createElement(JSX.Raw, {
           html:
@@ -188,46 +87,36 @@ class SassSiteRenderContext extends DefaultThemeRenderContext {
         ),
     this,
   );
+
+  // 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.
+  oldUrlTo = this.urlTo;
+  urlTo = bind(function (context, reflection) {
+    const relative = context.oldUrlTo(reflection);
+
+    const absolute = new URL(
+      relative,
+      `relative:///documentation/js-api/${context.theme.markedPlugin.location}`,
+    );
+    absolute.pathname = absolute.pathname
+      .replace(/\.html$/, '')
+      .replace(/\/index$/, '');
+    return absolute.toString().replace(/^relative:\/\//, '');
+  }, 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() {
+  getRenderContext(page) {
     this.contextCache ??= new SassSiteRenderContext(
       this,
+      page,
       this.application.options,
     );
     return this.contextCache;
   }
 
-  render(page) {
+  render(page, template) {
     const context = this.getRenderContext(page);
 
     // The default header includes a search bar that we don't want, so we just
@@ -267,12 +156,12 @@ title: ${JSON.stringify(`${page.model.name} | JS API`)}
   </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 class="col-content">
+      ${JSX.renderElement(template(page))}
+    </div>
+    <div class="col-sidebar">
+      <div class="site-menu">
+        ${JSX.renderElement(context.sidebar(page))}
       </div>
     </div>
   </div>
@@ -294,13 +183,32 @@ title: ${JSON.stringify(`${page.model.name} | JS API`)}
 // 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.converter.addUnknownSymbolResolver((ref, refl, part, symbolId) => {
+    if (!symbolId) return;
+    const name = symbolId.qualifiedName;
+
+    switch (ref.moduleSource) {
+      case 'immutable':
+        return `https://immutable-js.com/docs/latest@main/${name}/`;
+      case 'source-map-js':
+        if (name === 'RawSourceMap') {
+          return 'https://github.com/mozilla/source-map/blob/58819f09018d56ef84dc41ba9c93f554e0645169/source-map.d.ts#L15-L23';
+        }
+        break;
+      case '@types/node':
+        if (name === 'Buffer') {
+          return 'https://nodejs.org/api/buffer.html';
+        }
+        break;
+
+      case 'typescript':
+        switch (name) {
+          case 'URL':
+            return 'https://developer.mozilla.org/en-US/docs/Web/API/URL';
+          case 'Promise':
+            return 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise';
+        }
+        break;
     }
   });