Build the right-side table of contents from javascript

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: false
+blank_issues_enabled: true
 contact_links:
   - name: SUPPORT, ISSUES, and TROUBLESHOOTING
     url: https://github.com/google/docsy/discussions

.github/workflows/test.yaml

@@ -25,4 +25,7 @@ jobs:
           cache: npm
           cache-dependency-path: package.json
       - run: npm install --omit=optional
-      - run: npm run test:all
+      - if: runner.os != 'Windows'
+        run: npm run test:all
+      - if: runner.os == 'Windows'
+        run: npm run ci:prepare && npm run cd:docs build && npm run ci:post

.prettierignore

@@ -1,6 +0,0 @@
-.editorconfig
-.gitattributes
-.gitignore
-.nvmrc
-.prettierignore
-.s3deploy.yml

.vscode/cspell.json

@@ -2,5 +2,15 @@
 {
   "version": "0.2",
   "caseSensitive": true,
-  "words": ["Docsy", "hugo", "shortcode", "shortcodes", "warnf"]
+  "words": [
+    "Docsy",
+    "errorf",
+    "hugo",
+    "shortcode",
+    "shortcodes",
+    "tabpane",
+    "upvote",
+    "warnf",
+    "relref"
+  ]
 }

CHANGELOG.md

@@ -18,23 +18,138 @@ Useful links:
 [releases]: https://github.com/google/docsy/releases
 [tags]: https://github.com/google/docsy/tags
 
-## 0.9.2 or 0.10.0
+## 0.12.1 or 0.13.0
 
-> ### UNRELEASED: this planned version is still under development
+> **UNRELEASED: this planned version is still under development**
 
 For the full list of changes, see the [0.x.y] release notes.
 
 **Breaking changes**:
 
-- Removed shortcode `card-code` that was [deprecated in 0.7.0](#070); use
-  shortcode `card` with named parameter `code=true` instead.
+- ...
 
 **New**:
 
 **Other changes**:
 
 [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
 
+## 0.12.0
+
+For the full list of changes, see the [0.12.0] release notes.
+
+**Breaking changes**:
+
+- Renames the default Docsy heading render hook and heading self-link partials.
+  This is a breaking change only if your project uses this feature. For details,
+  see [Heading self links][] ([#2223]).
+- Relocates and adapts layouts in response to Hugo's [new template system][].
+  For details, see [Adapt to new template system in Hugo v0.146.0 #2243][#2243].
+- **IMPORTANT**: if your project overrides any of the layout files mentioned in
+  [#2243], then apply the same name changes in your project files. In
+  particular, note that:
+  - Taxonomy-related layout files: names have been _swapped_, and `terms.html`
+    is now singular ([#2257]):
+    - Renames `_default/taxonomy.html` to `term.html` (singular)
+    - Renames `_default/terms.html` to `taxonomy.html`
+  - Renames `layouts/**/content.html` by adding a `_td-` filename prefix
+    ([#2259]).
+
+[#2257]: https://github.com/google/docsy/pull/2257
+[#2259]: https://github.com/google/docsy/pull/2259
+[new template system]: https://gohugo.io/templates/new-templatesystem-overview/
+
+**Potential breaking changes**:
+
+- Removes shortcode `figure`, hugo's built-in shortcode `figure` can/will be
+  used instead.
+
+**New**:
+
+- **[Breadcrumb navigation]** support has been enhanced and adjusted:
+  - You can now disable breadcrumbs for an entire project, or individual pages
+    or sections by setting `ui.breadcrumb_disable` to true. For details, see
+    [Breadcrumb navigation][].
+  - **Blog** pages now also have breadcrumbs by default ([#1788]).
+  - Index-page single-element breadcrumb lists are hidden by default ([#2160]).
+- Support for a [_td-content-after-header.html] page-content render hook, which
+  can be [content type][] specific ([#2192]). For details, see the [User
+  Guide][before-page-content].
+
+**Other changes**:
+
+- **Blog** section index page content and title used to be ignored, they are now
+  displayed ([#1787]). To recover the old behavior use the following style
+  override: `.td-section.td-blog .td-content { display: none; }`.
+- Adds a `comment` shortcode, as a drop-in replacement for the one removed from
+  Hugo.
+
+[0.12.0]: https://github.com/google/docsy/releases/v0.12.0
+[#1787]: https://github.com/google/docsy/issues/1787
+[#1788]: https://github.com/google/docsy/issues/1788
+[#2160]: https://github.com/google/docsy/pull/2160
+[#2192]: https://github.com/google/docsy/pull/2192
+[#2223]: https://github.com/google/docsy/pull/2223
+[#2243]: https://github.com/google/docsy/pull/2243
+[before-page-content]:
+  https://www.docsy.dev/docs/adding-content/lookandfeel/#before-page-content
+[Breadcrumb navigation]:
+  https://www.docsy.dev/docs/adding-content/navigation/#breadcrumb-navigation
+[content type]: https://gohugo.io/quick-reference/glossary/#content-type
+[Heading self links]:
+  https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links
+[_td-content-after-header.html]:
+  https://github.com/google/docsy/blob/main/layouts/_td-content-after-header.html
+
+## 0.11.0
+
+For the full list of changes, see the [0.11.0] release notes.
+
+**New**:
+
+- Support for Right-To-Left (RLT) languages is reintroduced via [Bootstrap's
+  support for RTL][bs-rtl]. For details, see [Right-to-left languages][rtl].
+- The URL to your project's contribution guidelines is configurable. For
+  details, see [Adding a community page].
+- When a section's sidebar entries are truncated because there are more than
+  [params.ui.sidebar_menu_truncate] section entries, a warning is issued.
+
+[0.11.0]: https://github.com/google/docsy/releases/v0.11.0
+[bs-rtl]: https://getbootstrap.com/docs/5.3/getting-started/rtl/
+[Adding a community page]:
+  https://www.docsy.dev/docs/adding-content/content/#adding-a-community-page
+[params.ui.sidebar_menu_truncate]:
+  https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options
+[rtl]: https://www.docsy.dev/docs/language/#right-to-left-languages
+
+## 0.10.0
+
+For an introduction to this release, see the [0.10.0 release report]. For the
+full list of changes, see the [0.10.0] release notes.
+
+**New**: color themes and dark-mode support! For details, see [Color themes and
+dark-mode support][dark-mode].
+
+**Breaking changes**:
+
+- Removes shortcode `card-code` that was [deprecated in 0.7.0](#070); use
+  shortcode `card` with named parameter `code=true` instead.
+- The following SCSS variables are inlined in favor of dark-mode compatible
+  styling: `$border-color`, `$td-sidebar-tree-root-color`,
+  `$td-sidebar-bg-color`, `$td-sidebar-border-color` ([#1952])
+
+**Style changes** (potentially breaking):
+
+- The style of various shortcode and elements have been adjusted so that they
+  are compatible with light/dark mode. For details see, **Important style
+  changes** in [Color themes and dark-mode support][dark-mode].
+
+[#1952]: https://github.com/google/docsy/pull/1952
+[0.10.0]: https://github.com/google/docsy/releases/v0.10.0
+[0.10.0 release report]: https://www.docsy.dev/blog/2024/0.10.0/
+[dark-mode]:
+  https://www.docsy.dev/blog/2024/0.10.0/#color-themes-and-dark-mode-support
+
 ## 0.9.1
 
 Patch release. For details, see [0.9.1].
@@ -64,7 +179,8 @@ this release are listed next.
   form `--KIND`. The new suffix is `__KIND`. For details, see [Disabling links].
 
 - **Heading self-link** support has been reimplemented and projects must now
-  explicitly enable the feature. For details, see [Heading self links].
+  explicitly enable the feature. For details, see [Heading self
+  links][0.9.0:hsl].
 
 **Footer changes**: refactoring, for easier customization, and simplification.
 For details concerning all footer changes, see [#1818].
@@ -92,7 +208,7 @@ For details concerning all footer changes, see [#1818].
 [Footer layout]: https://www.docsy.dev/blog/2024/0.9.0/#footer-layout
 [Footer copyright]: https://www.docsy.dev/blog/2024/0.9.0/#footer-copyright
 [Footer streamlined]: https://www.docsy.dev/blog/2024/0.9.0/#footer-streamlined
-[Heading self links]: https://www.docsy.dev/blog/2024/0.9.0/#heading-self-links
+[0.9.0:hsl]: https://www.docsy.dev/blog/2024/0.9.0/#heading-self-links
 [look and feel]: https://www.docsy.dev/blog/2024/0.9.0/#look-and-feel
 [mermaid]:
   https://www.docsy.dev/docs/adding-content/diagrams-and-formulae/#diagrams-with-mermaid
@@ -109,10 +225,11 @@ For the full list of changes, see the [0.8.0] release notes.
 
 **Breaking changes**:
 
-- Docsy is packaged as a **single Hugo module** ([#1120]).
-  - For details, see [Use Docsy as a Hugo Module].
-- **Important**: non-Hugo-module projects should read the [Docsy NPM install
-  side-effect] note.
+- Docsy is packaged as a **single Hugo module** ([#1120]). For details, see [Use
+  Docsy as a Hugo Module].
+- **Important**: non-Hugo-module projects should be aware of the [Docsy NPM
+  install side-effect]. Also, for guidance on Hugo-reported "failed to load
+  modules" error, see [Docsy as an NPM package].
 - **Page feedback**, or [User feedback]:
   - In support of projects configuring analytics outside of Docsy, feedback
     functionality is enabled regardless of whether
@@ -131,6 +248,8 @@ For the full list of changes, see the [0.8.0] release notes.
 [#1726]: https://github.com/google/docsy/pull/1726
 [#1727]: https://github.com/google/docsy/pull/1727
 [0.8.0]: https://github.com/google/docsy/releases/v0.8.0
+[Docsy as an NPM package]:
+  https://docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
 [Docsy NPM install side-effect]:
   https://docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect
 [Use Docsy as a Hugo Module]:
@@ -206,7 +325,8 @@ For the full list of changes, see the [0.7.0] release notes.
 - **Shortcodes**:
   - Now using Hugo's native support for processing HTML & markdown, not file
     extension testing. ([#906])
-  - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939])
+  - Dropped support for pre-Hugo-0.54.x behavior of [shortcodes with markdown],
+    `{{%/*...*/%}}`. ([#939])
   - `blocks/section`: **default** and accepted values of the `type` argument
     have changed! For details, see [blocks/section] ([#1472]).
   - **Card shortcodes** ([#1376])]:
@@ -219,6 +339,8 @@ For the full list of changes, see the [0.7.0] release notes.
 
 [chroma-docsy]:
   https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-chroma
+[shortcodes with markdown]:
+  https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown
 
 - **Detection of draw.io diagrams** is now **disabled** by default [#1185]
 
@@ -419,9 +541,10 @@ For the full list of changes, see the [0.2.0] release notes.
 
 <!-- ENTRY TEMPLATE ------------------------------------------------------
 
+```
 ## 0.X.Y
 
-> ### UNRELEASED: this planned version is still under development
+> **UNRELEASED: this planned version is still under development**
 
 For the full list of changes, see the [0.x.y] release notes.
 
@@ -434,5 +557,6 @@ For the full list of changes, see the [0.x.y] release notes.
 **Other changes**:
 
 [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
+```
 
 ---------------------------------------------------------------------------->

CONTRIBUTING.md

@@ -51,10 +51,10 @@ repo.
     the end of the file. (Note that change details are autogenerated by GitHub
     in a later step.)
 3.  **Update Docsy version** to v0.X.Y for:
-    - `version` key in [package.json](package.json)
-    - `version` key in [userguide/hugo.yaml][]
-4.  Run `npm install` to have vendor assets and [go.mod](go.mod) updated for
-    dependencies.
+    - `version` key in [package.json]
+    - `version` key in [userguide/hugo.yaml]
+4.  Run `npm run ci:prepare` to ensure that vendor assets and [go.mod]
+    dependencies are up-to-date.
 5.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
     preparation".
 6.  **Test the PR** branch from selected sites, and push any required
@@ -117,19 +117,22 @@ Assuming that Docsy release v0.X.Y has been successfully deployed and use by at
 least one downstream project, then perform the following actions before any
 further changes are merged into the default branch:
 
-1. Set `version` in [package.json](package.json) to the next planned (or the
-   next dot) release with a dev suffix, such as `v0.X.Z-dev.0-unreleased`.
+1. Set `version` in [package.json] to the next planned (or the next dot) release
+   with a dev suffix, such as `v0.X.Z-dev-unreleased`.
 2. In the [CHANGELOG]:
    - **Create a new entry** for the next release by copying the ENTRY TEMPLATE
      at the end of the file.
    - **Pin the 0.X.Y release URL**, which ends with `latest?FIXME=...`, to the
      v0.X.Y release at `https://github.com/google/docsy/releases/v0.x.y`.
 3. **Submit a PR with your changes**, using a title like "Set NPM package
-   version to next unreleased dev vers".
+   version to next unreleased dev version".
 4. **Get PR approved and merged**.
 
-[CHANGELOG]: CHANGELOG.md
+[CHANGELOG]: https://github.com/google/docsy/blob/main/CHANGELOG.md
 [contribution guidelines]: https://www.docsy.dev/docs/contribution-guidelines/
 [docsy-example]: https://github.com/google/docsy-example
 [Draft a new release]: https://github.com/google/docsy/releases/new
-[userguide/hugo.yaml]: userguide/hugo.yaml
+[go.mod]: https://github.com/google/docsy/blob/main/go.mod
+[package.json]: https://github.com/google/docsy/blob/main/package.json
+[userguide/hugo.yaml]:
+  https://github.com/google/docsy/blob/main/userguide/hugo.yaml

README.md

@@ -1,12 +1,7 @@
 # Docsy
 
-[![Project status: active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
-[![Project releases](https://img.shields.io/github/release/google/docsy)](https://github.com/google/docsy/releases)
-[![Project build Status](https://badges.netlify.com/api/docsydocs.svg?branch=main)](https://app.netlify.com/sites/docsydocs/deploys)
-[![Project contributors](https://img.shields.io/github/contributors/google/docsy)](https://github.com/google/docsy/graphs/contributors)
-[![Project license](https://img.shields.io/github/license/google/docsy)](https://github.com/google/docsy/blob/main/LICENSE)
-
-## 🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use official Docsy [releases].
+> **🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use
+> official Docsy [releases].**
 
 Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets,
 providing simple navigation, site structure, and more.
@@ -95,8 +90,8 @@ requests, see [CONTRIBUTING.md]. Thank you to all past, present, and future
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the
-[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for details
+This project is licensed under the Apache License 2.0 - see
+[LICENSE](https://github.com/google/docsy/blob/main/LICENSE) for details
 
 [code of conduct]:
   https://github.com/google/.github/blob/master/CODE_OF_CONDUCT.md

assets/scss/_boxes.scss

@@ -116,3 +116,21 @@
 @each $color, $value in $grays {
   @include box-variant(".td-box", $color, $value);
 }
+
+// Single dark-mode compatibility override for white boxes:
+@include color-mode(dark) {
+  .td-box--white {
+    color: var(--bs-body-color);
+    background-color: var(--bs-body-bg);
+    p > a, span > a {
+      color: var(--bs-link-color);
+      &:focus,
+      &:hover {
+        color: rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1));
+      }
+    }
+    .td-arrow-down::before {
+      border-color: var(--bs-body-bg) transparent transparent transparent;
+    }
+  }
+}