Update 0.14.0 release docs, rework and improve project-styles section

Author: chalin

.markdownlint-cli2.yaml

@@ -12,7 +12,7 @@ globs:
   - 'docsy.dev/content/en/docs/best-practices/**/*.md'
   - 'docsy.dev/content/en/docs/get-started/other-options.md'
   - 'docsy.dev/content/en/docs/language.md'
-  - 'docsy.dev/content/en/site/**/*.md'
+  - 'docsy.dev/content/en/project/**/*.md'
 
 config:
   extends: .markdownlint.yaml

docsy.dev/.prettierignore

@@ -7,6 +7,6 @@
 !/content/en/docs/best-practices/**/*.*
 !/content/en/docs/get-started/other-options.md
 !/content/en/docs/language.md
-!/content/en/site/**/*.*
+!/content/en/project/**/*.*
 
 /layouts

docsy.dev/content/en/blog/2026/0.14.0.md

@@ -1,14 +1,14 @@
 ---
 title: Release 0.14.0 report and upgrade guide
 linkTitle: Release 0.14.0
-date: 2026-01-16
+date: 2026-01-25
 author: >-
   [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
   for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
 message: Hello, world!
 body_class: release-highlights published-draft-post
 tags: [release]
-cSpell:ignore: Chalin docsy markdownify FOUC lookandfeel mhchem katex notoc
+cSpell:ignore: Chalin pageinfo docsy gohugoio subrepo lookandfeel
 ---
 
 {{% card header="Highlights" %}}
@@ -30,62 +30,137 @@ Docsy [0.14.0] comes with the following notable features and improvements:
 
 - {{% _param FA globe "" %}} [Internationalization](#internationalization)
   improvements for multiple locales
-- {{% _param FA book "" %}}
-  [Documentation enhancements](#documentation-enhancements) including Hugo
+- {{% _param FA book "" %}} Documentation enhancements including Hugo
   Markdown-style alert support
-- {{% _param FA code "" %}} [Hugo upgrade](#hugo-upgrade) to 0.154.5 with
-  important breaking changes
+- {{% _param FA code "" %}} [Hugo upgrade](#hugo) to 0.154.5 with important
+  breaking changes
 
 ## Ready to upgrade?<a id="breaking-changes"></a> {#ready-to-upgrade}
 
 - Review {{% _param BADGE BREAKING warning %}} changes:
-  - {{% _param BREAKING %}} [Hugo 0.153+ upgrade](#hugo-upgrade) introduces
-    breaking changes
+  - {{% _param BREAKING %}} How you [customize Swagger](#swagger-scss) UI's look
+    and feel changes.
+  - {{% _param BREAKING %}} [Hugo 0.153+ upgrade](#hugo) introduces breaking
+    changes
+- Review changes to internal files:
+  - [Improved separation of project and internal SCSS files](#improved-scss-soc)
 - Optionally skim:
   - {{% _param NEW %}} New features
   - [Other notable changes](#other-notable-changes)
 - {{% _param FA rocket primary %}} When you're ready, jump to
   [Upgrade to 0.14.0](#upgrade).
 
-## {{% _param FA globe "" %}} Internationalization improvements {#internationalization}
+## {{% _param NEW %}} Markdown alert syntax {#alerts}
 
-This release includes significant improvements to internationalization support:
-
-- **Bengali localization**: Added feedback section and table of contents
-  translations, fixed newline issues
-- **Serbian translations**: Updated both Cyrillic and Latin variants
-- **Chinese translations**: Updated Simplified and Traditional Chinese locales
-- **German localization**: Completed German translation support
-
-These updates improve the experience for users of Docsy sites in these
-languages.
-
-## {{% _param FA book "" %}} Documentation enhancements {#documentation-enhancements}
-
-### {{% _param NEW %}} Hugo Markdown-style alert support {#alerts}
-
-Docsy 0.14.0 adds support and documentation for Hugo's native Markdown-style
-alert syntax. This provides an alternative to the traditional shortcode-based
-alerts, offering a more Markdown-native approach to creating alerts in your
-content.
-
-For details about the supported syntax, see
-[Hugo Markdown-style alert support](/docs/content/adding-content/#alerts).
-
-### Documentation reorganization
+Docsy 0.14.0 adds support for Hugo's Markdown alert syntax, like this:
 
-The site documentation section has been renamed to "project" section, with pages
-moved to the About section for better organization. This improves the structure
-and discoverability of project-related documentation.
-
-### Additional documentation improvements
+```markdown
+> [!NOTE] :star: Markdown alert syntax
+>
+> This syntax is more author, tooling, and AI friendly.
+```
 
-- Added **AGENTS.md** guide for AI agents working with the Docsy codebase
-- Added site build info and build documentation
-- Added version badge to documentation pages
-- Version tracking added to docs landing page
+Which renders as:
 
-## {{% _param BREAKING %}} Hugo upgrade {#hugo-upgrade}
+> [!NOTE] :star: Markdown alert syntax
+>
+> This syntax is more author, tooling, and AI friendly.
+
+While we continue to support the [alert shortcode][], we recommend using the
+Markdown alert syntax whenever possible. For details about the supported syntax,
+and how to customize the appearance of alerts, see [Alerts][].
+
+[alert shortcode]: /docs/content/shortcodes/#alert
+[Alerts]: /docs/content/adding-content/#alerts
+
+## Improved separation of project and internal SCSS files {#improved-scss-soc}
+
+Docsy 0.14.0 moves all internal SCSS files from `assets/scss/` into the
+`assets/scss/td/` subdirectory. This change distinguishes project customization
+files from internal theme files and prevents projects from inadvertently
+overriding internal SCSS files. For details on how to customize Docsy's look and
+feel for your project, see [Project styles][] that covers:
+
+- [Project style files][]: the files supported for project SCSS customization
+- [Advanced style customization][]
+
+### Action required {#action-required-post-scss-file-move}
+
+If your project has any of the files listed below in `assets/scss/`, you're
+overriding Docsy's internal SCSS files.
+
+<details class="mb-3">
+<summary>
+<span class="ms-2 h5 text-info">
+<span class="fas fa-file-alt"></span>
+List of internal
+<code>assets/scss/</code> files moved into the <code>td/</code> subdirectory
+</span>
+</summary>
+
+```text
+assets/scss/
+├── _alerts.scss
+├── _blog.scss
+├── _boxes.scss
+├── _breadcrumb.scss
+├── _code.scss
+├── _colors.scss
+├── _content.scss
+├── _drawio.scss
+├── _main-container.scss
+├── _nav.scss
+├── _navbar-mobile-scroll.scss
+├── _pageinfo.scss
+├── _search.scss
+├── _sidebar-toc.scss
+├── _sidebar-tree.scss
+├── _swagger.scss
+├── _table.scss
+├── _taxonomy.scss
+├── _variables_forward.scss
+├── _variables.scss
+├── blocks/_blocks.scss
+├── blocks/_cover.scss
+├── section-index.scss
+├── shortcodes.scss
+├── shortcodes/cards-pane.scss
+├── shortcodes/tabbed-pane.scss
+├── support/_bootstrap_vers_test.scss
+├── support/_mixins.scss
+├── support/_rtl.scss
+└── support/_utilities.scss
+```
+
+</details>
+
+To continue using your customizations from `_abc.scss` add the following import
+to your `_styles_project.scss` file:
+
+```scss
+@import 'abc';
+```
+
+Alternatively, you can copy the styles directly into your `_styles_project.scss`
+file.
+
+For details about style customizations, see [Project style files][] and
+[Advanced style customization][].
+
+## {{% _param BREAKING %}} Swagger UI style customization {#swagger-scss}
+
+Prior to 0.14.0, the Docsy User Guide incorrectly recommended overriding
+`_swagger.scss` to customize [Swagger UI][] styles. Docsy's internal SCSS files
+are not intended to be overridden. The User Guide has been corrected, but since
+this was documented, moving the file constitutes a breaking change.
+
+If your project has Swagger UI style customizations, follow the steps in
+[Action required](#action-required-post-scss-file-move) to continue using your
+customizations.
+
+[Swagger UI]: /docs/content/shortcodes/#swaggerui
+
+## {{% _param BREAKING %}} Hugo 0.153+ upgrade {#hugo}
 
 Docsy 0.14.0 requires **Hugo 0.154.5**, upgraded from 0.152.2 in Docsy 0.13.0.
 This upgrade includes several breaking changes introduced in Hugo 0.153+ that
@@ -136,9 +211,30 @@ the upgrade process.
 
 ## Other notable changes
 
-- **CI/CD improvements**: Netlify configuration moved to docsy.dev subrepo, CI
-  cleanup and reorganization
-- **Package updates**: Various npm packages updated alongside the Hugo upgrade
+- ...
+
+### {{% _param FA globe "" %}} Internationalization improvements {#internationalization}
+
+This release includes significant improvements to internationalization support:
+
+- **i18n file format migration**: All translation files have been converted from
+  TOML to YAML format for better maintainability and consistency
+- **Bengali localization**: Added feedback section and table of contents
+  translations, fixed newline issues, added alert labels
+- **Serbian translations**: Updated both Cyrillic and Latin variants
+- **Chinese translations**: Updated Simplified and Traditional Chinese locales,
+  added alert labels
+- **German localization**: Completed German translation support
+- **Japanese translations**: Converted to YAML format, added alert labels and
+  all-rights-reserved translations
+- **Hebrew translations**: New locale added with alert and table of contents
+  labels
+- **Ukrainian translations**: Converted to YAML format
+- **Alert label translations**: Added across multiple locales for consistent
+  alert messaging
+
+These updates improve the experience for users of Docsy sites in these languages
+and make the translation files easier to maintain.
 
 ## {{% _param FA rocket primary %}} Upgrade to 0.14.0 {#upgrade}
 
@@ -166,6 +262,9 @@ instead:
 After upgrading, review the [breaking changes](#breaking-changes) and test your
 site thoroughly. Pay special attention to:
 
+- **SCSS file reorganization**: See
+  [Improved separation of project and internal SCSS files](#improved-scss-soc)
+  and [Swagger UI style customization](#swagger-scss)
 - **Language aliases**: Verify that default language redirects work correctly
 - **Page aliases**: Check that aliases point to the correct language versions
 - **macOS installations**: If you're on macOS, ensure Hugo is installed
@@ -217,6 +316,10 @@ Other references:
 
 [0.13.0]: /project/about/changelog/#v0.13.0
 [0.14.0]: https://github.com/google/docsy/releases/v0.14.0?no-link-check=1
+[Advanced style customization]:
+  /docs/content/lookandfeel/#advanced-style-customization
 [CL@0.14.0]: /project/about/changelog/#v0.14.0
+[Project styles]: /docs/content/lookandfeel/#project-styles
+[Project style files]: /docs/content/lookandfeel/#project-style-files
 [upgrade-0.13]: /blog/2025/0.13.0/
 [Upgrade to Docsy 0.13.0]: /blog/2025/0.13.0/