|
| 1 | +--- |
| 2 | +title: Upgrade Docsy to 0.14.0 |
| 3 | +cSpell:ignore: docsy hugo |
| 4 | +--- |
| 5 | + |
| 6 | +**Note:** v0.14.0 is not yet released. This upgrade uses the latest Docsy from |
| 7 | +`main`. |
| 8 | + |
| 9 | +From this prompt: |
| 10 | + |
| 11 | +> Read through Docsy 0.14.0 Upgrade blog post at |
| 12 | +> https://main--docsydocs.netlify.app/blog/2026/0.14.0/ (or |
| 13 | +> https://raw.githubusercontent.com/google/docsy/refs/heads/main/docsy.dev/content/en/blog/2026/0.14.0.md |
| 14 | +> if you prefer the raw source). |
| 15 | +> |
| 16 | +> Produce a report, based on the Docsy 0.14.0 Upgrade blog that details which |
| 17 | +> updates are required in this, the docsy-example, repo; which optional changes |
| 18 | +> and cleanup opportunities there are (to reduce technical debt), and which |
| 19 | +> enhancements we can apply. |
| 20 | +
|
| 21 | +I got the instructions below. |
| 22 | + |
| 23 | +## Upgrade report |
| 24 | + |
| 25 | +Now let me examine the docsy-example repository to understand what files and |
| 26 | +configurations it has that might be affected by this upgrade.Based on my |
| 27 | +analysis of the Docsy 0.14.0 Upgrade blog post and the current state of the |
| 28 | +`google/docsy-example` repository, here is a comprehensive upgrade report: |
| 29 | + |
| 30 | +--- |
| 31 | + |
| 32 | +# Docsy 0.14.0 Upgrade Report for `google/docsy-example` |
| 33 | + |
| 34 | +## Executive Summary |
| 35 | + |
| 36 | +The docsy-example repository is currently on **Docsy v0.13.1 (pre-release |
| 37 | +build)** and requires upgrading to the **latest Docsy from `main`** (v0.14.0 is |
| 38 | +not yet released). The repository already meets the **Hugo 0.155.0** minimum |
| 39 | +requirement. The upgrade impact is **relatively low** since the example site |
| 40 | +uses standard Docsy project files and doesn't override internal theme files. |
| 41 | + |
| 42 | +--- |
| 43 | + |
| 44 | +## 1. Required Updates ⚠️ |
| 45 | + |
| 46 | +### 1.1 Update Docsy Module Version |
| 47 | + |
| 48 | +```bash |
| 49 | +go get github.com/google/docsy@main |
| 50 | +# or: hugo mod get -u github.com/google/docsy@main |
| 51 | + |
| 52 | +hugo mod tidy && hugo mod graph |
| 53 | +``` |
| 54 | + |
| 55 | +### 1.2 Navbar Theme Behavior Change |
| 56 | + |
| 57 | +**Impact:** The navbar now follows the site's light/dark theme by default |
| 58 | +instead of always being dark. |
| 59 | + |
| 60 | +**Files potentially affected:** The homepage and about pages use `blocks/cover` |
| 61 | +which interacts with the navbar. |
| 62 | + |
| 63 | +**Action required:** If you want to restore the previous **always-dark navbar** |
| 64 | +behavior, add `navbar_theme: dark` under `params.ui` in `hugo.yaml`. |
| 65 | + |
| 66 | +**Current status:** No `navbar_theme` is set. The navbar follows the site |
| 67 | +light/dark theme by default. **No change made**—we do not need to enforce dark |
| 68 | +mode for the nav. |
| 69 | + |
| 70 | +### 1.3 `blocks/cover` Markdown Processing |
| 71 | + |
| 72 | +**Breaking change:** The shortcode now uses `.Inner` content directly, relying |
| 73 | +on Hugo's native Markdown processing. |
| 74 | + |
| 75 | +**Affected files:** |
| 76 | + |
| 77 | +- [`content/fa/about/index.html`](https://github.com/google/docsy-example/blob/834cb7a89aa10d50dfd8bf5df6349cfe002bc1f9/content/fa/about/index.html) - |
| 78 | + Uses `{{< blocks/cover >}}` in an `.html` file |
| 79 | + |
| 80 | +**Action:** If Markdown content inside `blocks/cover` doesn't render correctly |
| 81 | +in HTML files, change from: |
| 82 | + |
| 83 | +```html |
| 84 | +{{< blocks/cover title="..." >}} |
| 85 | +``` |
| 86 | + |
| 87 | +to the Markdown call syntax: |
| 88 | + |
| 89 | +```html |
| 90 | +{{% blocks/cover title="..." %}} |
| 91 | +``` |
| 92 | + |
| 93 | +**Note:** The English about page |
| 94 | +([`content/en/about/index.md`](https://github.com/google/docsy-example/blob/834cb7a89aa10d50dfd8bf5df6349cfe002bc1f9/content/en/about/index.md)) |
| 95 | +already correctly uses `{{% blocks/cover %}}`. |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +## 2. Optional Changes & Cleanup Opportunities 🧹 |
| 100 | + |
| 101 | +These reduce technical debt and adopt improved patterns: |
| 102 | + |
| 103 | +### 2.1 Switch to Markdown Alert Syntax |
| 104 | + |
| 105 | +**Current state:** The repo uses **both** Markdown alerts and the `alert` |
| 106 | +shortcode in |
| 107 | +[`content/en/docs/getting-started/example-page.md`](https://github.com/google/docsy-example/blob/834cb7a89aa10d50dfd8bf5df6349cfe002bc1f9/content/en/docs/getting-started/example-page.md#L210-L288): |
| 108 | + |
| 109 | +```markdown |
| 110 | +<!-- Current: Markdown alerts (already using new syntax!) --> |
| 111 | + |
| 112 | +> [!NB] This is an alert. |
| 113 | +
|
| 114 | +> [!TIP] |
| 115 | +> |
| 116 | +> This is a successful alert. |
| 117 | +
|
| 118 | +<!-- Current: Alert shortcodes (consider migrating) --> |
| 119 | + |
| 120 | +{{% alert %}} This is an alert. {{% /alert %}} |
| 121 | +{{% alert title="Alert title" color="secondary" %}} ... {{% /alert %}} |
| 122 | +``` |
| 123 | + |
| 124 | +**Recommendation:** Since this is an example site, **keep both syntaxes** to |
| 125 | +demonstrate both options to users. Add a comment explaining the Markdown syntax |
| 126 | +is recommended for new content. |
| 127 | + |
| 128 | +### 2.2 Navbar Height Customization |
| 129 | + |
| 130 | +**New in 0.14.0:** You can now adjust navbar height via the |
| 131 | +`$td-navbar-min-height` SCSS variable. |
| 132 | + |
| 133 | +**File:** |
| 134 | +[`assets/scss/_variables_project.scss`](https://github.com/google/docsy-example/blob/cac635841b0955e46a3d82c814b308c17a6dc87c/assets/scss/_variables_project.scss) |
| 135 | + |
| 136 | +**Current state:** The file is essentially empty (just comments). |
| 137 | + |
| 138 | +**Opportunity:** If navbar height customization is desired, add: |
| 139 | + |
| 140 | +```scss |
| 141 | +$td-navbar-min-height: 4rem; // Adjust as needed |
| 142 | +``` |
| 143 | + |
| 144 | +### 2.3 New `td-below-navbar` Helper Class |
| 145 | + |
| 146 | +**Enhancement:** You can now position `blocks/cover` below the navbar instead of |
| 147 | +behind it. |
| 148 | + |
| 149 | +**Opportunity:** For pages like the About page, you could use: |
| 150 | + |
| 151 | +```markdown |
| 152 | +{{% blocks/cover title="About Goldydocs" height="auto td-below-navbar" %}} |
| 153 | +``` |
| 154 | + |
| 155 | +This positions the cover content below the fixed navbar on desktop. |
| 156 | + |
| 157 | +### 2.4 Internal SCSS File Reorganization |
| 158 | + |
| 159 | +**Good news:** The docsy-example repo does **not** override any internal SCSS |
| 160 | +files. The only SCSS files present are: |
| 161 | + |
| 162 | +- `assets/scss/_styles_project.scss` - Uses supported imports |
| 163 | +- `assets/scss/_variables_project.scss` - Minimal/empty |
| 164 | + |
| 165 | +The `_styles_project.scss` imports are from `td/` prefix which is the |
| 166 | +**correct** pattern: |
| 167 | + |
| 168 | +```scss |
| 169 | +@import 'td/color-adjustments-dark'; |
| 170 | +@import 'td/code-dark'; |
| 171 | +@import 'td/gcs-search-dark'; |
| 172 | +``` |
| 173 | + |
| 174 | +**No action required** - the repo already follows best practices. |
| 175 | + |
| 176 | +--- |
| 177 | + |
| 178 | +## 3. Enhancements to Consider ✨ |
| 179 | + |
| 180 | +### 3.1 Experimental Netlify Build Info Shortcode |
| 181 | + |
| 182 | +**New in 0.14.0:** The `td/site-build-info/netlify` shortcode displays Netlify |
| 183 | +build information. |
| 184 | + |
| 185 | +**Opportunity:** Since docsy-example uses Netlify (see |
| 186 | +[`netlify.toml`](https://github.com/google/docsy-example/blob/cac635841b0955e46a3d82c814b308c17a6dc87c/netlify.toml)), |
| 187 | +consider adding this to a footer or about page: |
| 188 | + |
| 189 | +```markdown |
| 190 | +{{< td/site-build-info/netlify >}} |
| 191 | +``` |
| 192 | + |
| 193 | +### 3.2 Experimental Extra Styles |
| 194 | + |
| 195 | +**New in 0.14.0:** |
| 196 | + |
| 197 | +- Navbar link decoration for active/hover states |
| 198 | +- Nested-list margin fix |
| 199 | + |
| 200 | +These are experimental and can be enabled per Docsy documentation. |
| 201 | + |
| 202 | +### 3.3 New CSS Variables for Navbar Customization |
| 203 | + |
| 204 | +**New experimental CSS variables:** |
| 205 | + |
| 206 | +- `--td-navbar-bg-color` |
| 207 | +- `--td-navbar-backdrop-filter` |
| 208 | +- `--td-navbar-border-bottom` |
| 209 | +- `--bs-bg-opacity` |
| 210 | +- `--bs-link-underline-opacity` |
| 211 | + |
| 212 | +**Opportunity:** Document these in the example site to help users understand |
| 213 | +customization options. |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +## 4. Items NOT Applicable to docsy-example ✅ |
| 218 | + |
| 219 | +The following breaking changes do **NOT** affect this repo: |
| 220 | + |
| 221 | +| Breaking Change | Status | |
| 222 | +| --------------------------------------------------------------------------------------- | --------------------- | |
| 223 | +| `td-offset-anchor` class usage | ❌ Not found in repo | |
| 224 | +| `navbar-bg-on-scroll` / `navbar-bg-onscroll--fade` classes | ❌ Not found in repo | |
| 225 | +| Swagger UI style customizations (`_swagger.scss`) | ❌ Not present | |
| 226 | +| Override of `blocks/lead.html`, `blocks/section.html`, or `layouts/community/list.html` | ❌ No overrides found | |
| 227 | +| Override of `navbar.html` partial | ❌ Not overridden | |
| 228 | +| Project-level i18n files | ❌ Not present | |
| 229 | + |
| 230 | +--- |
| 231 | + |
| 232 | +## 5. Post-Upgrade Sanity Checks ✓ |
| 233 | + |
| 234 | +After upgrading, verify: |
| 235 | + |
| 236 | +- [ ] **Build output**: Site builds without errors, warnings, or deprecation |
| 237 | + notices |
| 238 | +- [ ] **Navbar appearance**: Theme matches expectations (light in light mode, |
| 239 | + dark in dark mode) |
| 240 | +- [ ] **Cover pages**: Homepage and About page render correctly with navbar |
| 241 | + overlay |
| 242 | +- [ ] **Fragment links**: In-page anchor links scroll to correct position below |
| 243 | + navbar |
| 244 | +- [ ] **Alert rendering**: Both Markdown alerts and `alert` shortcodes display |
| 245 | + properly |
| 246 | +- [ ] **`<details>` elements**: Spacing is correct in content pages |
| 247 | +- [ ] **TOC sidebar**: h1 entries are visually distinct |
| 248 | + |
| 249 | +--- |
| 250 | + |
| 251 | +## 6. Summary of Actions |
| 252 | + |
| 253 | +| Priority | Action | File(s) | |
| 254 | +| ------------ | -------------------------------------------------------- | --------------------------------- | |
| 255 | +| 🔴 Required | Update Docsy module to latest from `main` | `go.mod`, `go.sum` | |
| 256 | +| ⚪ No action | Navbar follows site theme; dark mode not enforced | — | |
| 257 | +| 🟡 Review | Test `blocks/cover` in HTML files for Markdown rendering | `content/fa/about/index.html` | |
| 258 | +| 🟢 Optional | Consider `td-below-navbar` for cover positioning | Content files with `blocks/cover` | |
| 259 | +| 🟢 Optional | Add Netlify build info shortcode | Any appropriate page | |
| 260 | +| ⚪ No action | SCSS files already follow correct patterns | `assets/scss/` | |
| 261 | + |
| 262 | +--- |
| 263 | + |
| 264 | +## References |
| 265 | + |
| 266 | +- [Docsy 0.14.0 Release Blog Post](https://main--docsydocs.netlify.app/blog/2026/0.14.0/) |
| 267 | +- [Hugo 0.152.0-0.155.x Upgrade Guide](https://main--docsydocs.netlify.app/blog/2026/hugo-0.152.0+/) |
| 268 | +- [Docsy 0.14.0 Changelog](https://www.docsy.dev/project/about/changelog/#v0.14.0) |
0 commit comments