Reorganize SCSS, fix scroll padding, normalize blocks-shortcode heading IDs and keep old IDs as alias (google#2505)

Author: chalin

.vscode/cspell.json

@@ -13,6 +13,8 @@
     "Gantt",
     "getenv",
     "GLFM",
+    "gohugo",
+    "gohugoio",
     "Goldydocs",
     "htmltest",
     "hugo",

AGENTS.md

@@ -12,4 +12,11 @@ project CI/CD, release process, etc.
 [project]: docsy.dev/content/en/project/_index.md
 [git-info.md]: docsy.dev/content/en/project/build/git-repo.md
 
+## User guide
+
+Enforce the [style guide][] when reviewing user guide additions or
+modifications.
+
+[style guide]: docsy.dev/content/en/project/style-guide.md
+
 <!-- cSpell:ignore docsy -->

assets/scss/td/main.scss assets/scss/td/_main.scssassets/scss/td/main.scss renamed to assets/scss/td/_main.scss

@@ -36,6 +36,7 @@
 @import 'pageinfo';
 @import 'taxonomy';
 @import 'drawio';
+@import 'scroll';
 @import 'shortcodes';
 @import 'swagger';
 @import 'support/rtl';
@@ -44,30 +45,4 @@
   @import url($td-web-font-path);
 }
 
-// Adjust anchors vs the fixed menu.
-@include media-breakpoint-up(md) {
-  .td-offset-anchor:target {
-    display: block;
-    position: relative;
-    top: -$td-navbar-min-height;
-    visibility: hidden;
-  }
-
-  h2[id]::before,
-  h3[id]::before,
-  h4[id]::before,
-  h5[id]::before,
-  h6[id]::before,
-  .td-offset-anchor::before {
-    $td-anchor-offset-delta: 1.5rem;
-    display: block;
-    content: ' ';
-    margin-top: calc(
-      -1 * #{$td-navbar-min-height} - #{$td-anchor-offset-delta}
-    );
-    height: calc(#{$td-navbar-min-height} + #{$td-anchor-offset-delta});
-    visibility: hidden;
-  }
-}
-
 @import '../styles_project';

assets/scss/td/_scroll.scss

@@ -0,0 +1,18 @@
+// Browser scroll padding
+
+html,
+body {
+  --td-anchor-offset-delta: 1.5rem;
+  --td-scroll-padding-top: calc(
+    #{$td-navbar-min-height} + var(--td-anchor-offset-delta)
+  );
+
+  // Small viewports where the navbar is not fixed,
+  // we still want a bit of padding:
+  scroll-padding-top: var(--td-anchor-offset-delta);
+
+  // Wide viewports where the navbar is fixed.
+  @include media-breakpoint-up(md) {
+    scroll-padding-top: var(--td-scroll-padding-top);
+  }
+}

assets/scss/td/section-index.scss assets/scss/td/_section-index.scssassets/scss/td/section-index.scss renamed to assets/scss/td/_section-index.scss

@@ -155,7 +155,7 @@ changes ([PR #221](https://github.com/google/docsy-example/pull/221)) were
 mainly confined to the landing page of each natural language:
 
 - Utility-class renames, such as `.ml-*` and `.mr-*` to `.ms-*` and `.me-*`
-- [blocks/section](/docs/content/shortcodes/#blockssection) changes
+- [blocks/section](/docs/content/shortcodes/#blocks-section) changes
   ([PR #1472](https://github.com/google/docsy/pull/1472)):
   - Language landing pages had to be renamed from `.html` to `.md` in support of
     using blocks shortcodes to render markdown content

assets/scss/td/shortcodes.scss assets/scss/td/_shortcodes.scssassets/scss/td/shortcodes.scss renamed to assets/scss/td/_shortcodes.scss

@@ -204,7 +204,7 @@ specifically:
 [#1841]: https://github.com/google/docsy/issues/1841
 [#1852]: https://github.com/google/docsy/issues/1852
 [#2]: https://github.com/google/docsy/issues/2
-[blocks/feature]: /docs/content/shortcodes/#blocksfeature
+[blocks/feature]: /docs/content/shortcodes/#blocks-feature
 [CL@0.9.0]: /project/about/changelog/#v0.9.0
 [functions]: https://gohugo.io/functions/
 [hook]: https://gohugo.io/templates/render-hooks/

docsy.dev/content/en/blog/2023/0.7.x.md

@@ -139,7 +139,7 @@ structure as follows:
   ```
 
 The following commands can help you move your custom layout files and folders
-<a name="move-layout-files"></a>:
+<a id="move-layout-files"></a>:
 
 1. Move your custom layout files and folders:
 

docsy.dev/content/en/blog/2024/0.9.0.md

@@ -2,7 +2,7 @@
 title: Release 0.13.0 report and upgrade guide
 linkTitle: Release 0.13.0
 date: 2025-11-24
-lastmod: 2026-01-30
+lastmod: 2026-02-02
 author: >-
   [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
   for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
@@ -44,7 +44,7 @@ Docsy [0.13.0] comes with the following notable features and fixes:
 - {{% _param FA universal-access "" %}} [Accessibility](#accessibility)
   enhancements for better color contrast and dark mode support
 
-## Ready to upgrade?<a id="breaking-changes"></a> {#ready-to-upgrade}
+## Ready to upgrade? <a id="breaking-changes"></a> {#ready-to-upgrade}
 
 - Review {{% _param BADGE BREAKING warning %}} changes:
   - {{% _param BREAKING %}} [Alert shortcode](#alert-shortcode) body content
@@ -282,6 +282,7 @@ Docsy 0.12.0][]: follow them, using version **0.13.0** where the guide refers to
 
 - **Docsy**: [0.12.0] → [0.13.0]<br> Includes **Bootstrap**: 5.3.6 → 5.3.8
 - **Hugo**: 0.147.5 → 0.152.2&nbsp;[^vers-note]
+  > [!NB] See [Hugo 0.152.0 **breaking changes**][hugo-0.152.0].
 - **Node**: LTS 22 → LTS 24&nbsp;[^vers-note]
 
 [^vers-note]:
@@ -342,8 +343,9 @@ About this release:
 Other references:
 
 - [0.12.0 upgrade guide][]
-- For Hugo upgrade considerations when moving from 0.147.5 to 0.152.2, see the
-  [Hugo release notes](https://github.com/gohugoio/hugo/releases).
+- For Hugo upgrade considerations when moving from 0.147.5 to 0.152.2, see:
+  - [Hugo 0.152.0 breaking changes][hugo-0.152.0], our companion post
+  - The official [Hugo release notes](https://github.com/gohugoio/hugo/releases)
 
 [#349]: https://github.com/google/docsy/issues/349
 [#941]: https://github.com/google/docsy/pull/941
@@ -358,5 +360,6 @@ Other references:
 [CL@0.13.0]: /project/about/changelog/#v0.13.0
 [Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/
 [0.12.0 upgrade guide]: /blog/2025/0.12.0/
+[hugo-0.152.0]: /blog/2026/hugo-0.152.0+/#0.152.0
 
 > [!NB] **Last updated** {{% param lastmod %}}