Global refactor of themes section

.aider.conf.yml

@@ -0,0 +1,3 @@
+# Automatically read the docs architecture guidelines
+read:
+  - CONTEXT.md

.antigravityrules

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs
+
+For all content editing, page creation, or structural decisions in this project, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository.
+
+Do not answer or generate content until you have parsed that file.

.cursorrules

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs
+
+For all content editing, page creation, or structural decisions in this project, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository.
+
+Do not answer or generate content until you have parsed that file.

.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs
+
+For all content editing, page creation, or structural decisions in this project, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository.
+
+Do not answer or generate content until you have parsed that file.

.gitignore

@@ -1 +1,2 @@
 .idea/
+.claude/

.opencoderules

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs
+
+For all content editing, page creation, or structural decisions in this project, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository.
+
+Do not answer or generate content until you have parsed that file.

.windsurfrules

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs
+
+For all content editing, page creation, or structural decisions in this project, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository.
+
+Do not answer or generate content until you have parsed that file.

CLAUDE.md

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs
+
+For all content editing, page creation, or structural decisions in this project, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository.
+
+Do not answer or generate content until you have parsed that file.

CONTEXT.md

@@ -0,0 +1,79 @@
+# PrestaShop Developer Docs — AI System Context
+
+## Project
+
+Hugo static site. Source is Markdown with YAML front matter. Built with the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn/). Deployed at https://devdocs.prestashop-project.org/.
+
+Each major PrestaShop version has its own branch (`8.x`, `9.x`, …). The `9.x` branch uses `/9/` as the content path prefix. If you are working on another branch, update the version prefix accordingly.
+
+## Hugo Conventions
+
+### Front matter (required on every page)
+
+```yaml
+---
+title: Page Title         # Required. Displayed as heading and in nav.
+menuTitle: Short Title    # Optional. Shorter title for the sidebar.
+weight: 10                # Required. Controls ordering (lower = higher).
+chapter: true             # Optional. Section landing pages only.
+showOnHomepage: true      # Optional. Shows on the docs home page.
+useMermaid: true          # Optional. Only when page uses Mermaid diagrams.
+aliases:                  # Optional. Hugo redirect aliases (see Redirects below).
+  - /9/old/path
+---
+```
+
+### Shortcodes
+
+```
+{{% notice note %}}        → Supplementary information
+{{% notice info %}}        → Important contextual information
+{{% notice tip %}}         → Best practice or recommendation
+{{% notice warning %}}     → Breaking change, deprecation, common pitfall
+{{% children /%}}          → Auto-list child pages (section landing pages)
+{{< relref "/9/..." >}}    → Internal cross-reference — always use relref, never raw paths
+{{< minver v="9.1" >}}     → Minimum version badge
+```
+
+### Images
+
+Stored in `img/` relative to the section. From a depth-1 page (e.g. `themes/concepts/page.md`) the path is `../../img/filename.png`. From depth-2 (e.g. `themes/concepts/templates/page.md`) it is `../../../img/filename.png`.
+
+### Internal links
+
+Always use `{{< relref "/9/section/page" >}}`. Never use relative paths.
+
+## Redirects
+
+When a page is moved or renamed, add an `aliases` key to the **new page's** front matter. Hugo generates a redirect HTML file at the old path automatically.
+
+```yaml
+aliases:
+  - /9/section/old/path/to/page
+```
+
+Multiple aliases are supported as a list. Use the full path from root including `/9/`.
+
+**Do not remove aliases once added** — external sites and search engines may link to old URLs.
+
+## Writing Style & Typography
+
+- Present tense, active voice, second person ("you").
+- "must" for requirements, "should" for recommendations, "can" for options.
+- No emojis. No marketing language. No merchant-facing guidance.
+- Lead with the most important information (inverted pyramid).
+- One concept per page when possible.
+- Audience: theme developers and module developers. Not merchants.
+- No em dashes (`—`). Use `:` to introduce an explanation or list, `,` for a mid-sentence aside, and `.` to start a new sentence. Exception: table cells used as empty-value placeholders.
+
+## No Duplicate Content
+
+Each concept must live in exactly one place. If two pages need to cover the same information, the second page links to the first — it does not repeat the content.
+
+- Do not copy explanations, code examples, or configuration tables across pages
+- Do not summarize a page's content on another page — link to it instead
+- If you find duplicated content during an edit, remove it from the less authoritative page and add a link
+
+## Themes Section
+
+When working inside `themes/`, additional context applies. See `themes/CONTEXT.md` for the themes section map, technology stack rules (Bootstrap 5.3, BEM, Smarty 4, no jQuery, `data-ps-*` attributes), and what not to document.

basics/installation/_index.md

@@ -293,7 +293,6 @@ This problem may arise in case-insensitive file systems like MacOS due to a misc
 
 [getting-started-guide]: https://docs.prestashop-project.org/v.8-documentation/v/english/getting-started
 [system-requirements]: {{< relref "/9/basics/installation/system-requirements" >}}
-[clone-the-repository]: {{< relref "/9/themes/getting-started/setting-up-your-local-environment" >}}
 [compile-assets]: {{< relref "/9/development/compile-assets" >}}
 [webpack]: https://webpack.js.org/
 [composer]: https://getcomposer.org/download/

development/architecture/introduction.md

@@ -295,8 +295,8 @@ Remember the overview at the top of the article? Have a look at this more detail
 [MVC]: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
 [smarty]: https://www.smarty.net/
 [bootstrap]: https://getbootstrap.com/
-[child-theme]: {{< ref "/9/themes/reference/template-inheritance/parent-child-feature" >}}
-[theme-module-override]: {{< ref "/9/themes/reference/overriding-modules" >}}
+[child-theme]: {{< ref "/9/themes/create-a-theme/child-theme" >}}
+[theme-module-override]: {{< ref "/9/themes/concepts/overrides" >}}
 [twig]: https://twig.symfony.com/
 [github]: https://github.com/PrestaShop/prestashop-ui-kit/
 [autoupgrade]: https://github.com/PrestaShop/autoupgrade/

development/internationalization/rtl.md

@@ -32,4 +32,4 @@ If you changed something in your Back Office theme and you want your change to b
 
 {{< figure src="../img/rtl-edit-language.png" title="Toggling RTL for a language" >}}
 
-[rtl-support]: {{< ref "/9/themes/reference/rtl" >}}
+[rtl-support]: {{< ref "/9/themes/concepts/rtl" >}}

modules/core-updates/8.0.md

@@ -59,7 +59,7 @@ The `use_parent_assets` setting in `theme.yml`, when set to `true`, makes the ch
 
 To maintain the behavior of 1.7 and load the child theme's assets, `use_parent_assets` must be set to `false`.
 
-[More details in the theme.yml reference page]({{<relref "/9/themes/getting-started/theme-yml#parent--child-settings">}}).
+[More details in the theme.yml reference page]({{<relref "/9/themes/concepts/theme-structure#parentchild-settings">}}).
 
 #### Classic theme
 

modules/creation/displaying-content-in-front-office.md

@@ -416,7 +416,7 @@ name, or even your own name or initials, such as:
 
 ## List of Smarty variables
 
-You can find [a complete list of variables available in Smarty Templates on this page]({{< relref "/9/themes/reference/templates/variables" >}}).
+You can find [a complete list of variables available in Smarty Templates on this page]({{< relref "/9/themes/reference/template-variables" >}}).
 
 There are many other contextual hooks. If you need to display all of the
 current page's Smarty variables, add the following call:

themes/CLAUDE.md

@@ -0,0 +1,5 @@
+# AI Context for PrestaShop Developer Docs — Themes Section
+
+For all content editing, page creation, or structural decisions inside `themes/`, you MUST first read and strictly abide by the rules defined in the `CONTEXT.md` file located at the root of this repository, then read `themes/CONTEXT.md` for themes-specific rules.
+
+Do not answer or generate content until you have parsed both files.

themes/CONTEXT.md

@@ -0,0 +1,47 @@
+# Themes Section — AI System Context
+
+This file is loaded in addition to the root `CONTEXT.md` when working inside `themes/`.
+
+## Section map
+
+| Directory | Purpose |
+|-----------|---------|
+| `getting-started/` | Fast path: requirements, quick start, environment setup |
+| `concepts/` | Generic PrestaShop theme system mechanics (any theme) |
+| `hummingbird/` | Reference theme implementation (self-contained) |
+| `create-a-theme/` | Step-by-step how-to guides |
+| `guidelines/` | Universal rules: coding standards, browser compat, accessibility |
+| `reference/` | Pure lookup tables: template variables, JS events, Smarty helpers |
+| `distribution/` | Validation and export |
+
+### concepts/ vs hummingbird/
+
+- `concepts/` = mechanics that apply to **any** PrestaShop theme
+- `hummingbird/` = Hummingbird-specific implementation details
+- Cross-reference between the two with "For Hummingbird specifics, see..." / "For how the API works, see..."
+
+## Documentation guidelines
+
+### Technology stack
+
+- **Hummingbird** is the reference theme. Always use it as the example implementation.
+- **Bootstrap 5.3**, not Bootstrap 4. Never document BS4 patterns as current.
+- **BEM** naming convention for CSS classes. Do not mention RSCSS.
+- **Smarty 4** template engine. Use `{extends}` / `{block}` inheritance, not `{include}` patterns.
+- **No jQuery** in theme code. jQuery is loaded by `core.js` for module backward compatibility only. New theme code must use vanilla JavaScript.
+- **`data-ps-*` attributes** for JavaScript DOM hooks, not `.js-` prefixed classes.
+- **Web Platform Baseline** as the browser compatibility reference, not fixed version numbers.
+- **Accessibility (EAA / WCAG 2.2 AA)** is a hard requirement, not optional.
+
+### What not to document
+
+- Classic theme directory structure or code examples
+- `_dev/` folder (Classic-specific build artifact)
+- Bourbon, RSCSS, or any deprecated CSS methodology
+- jQuery usage patterns for new code
+- Fixed browser version lists (e.g. "Chrome 90+")
+- PHP coding standards: those belong in core contribution docs
+- PrestaShop 1.6 or 1.7 patterns unless explaining a migration path
+- Merchant-facing guidance: audience is theme and module developers only
+
+`reference/` pages contain no narrative: pure lookup tables only. All explanatory content belongs in `concepts/` or `hummingbird/`.

themes/_index.md

@@ -11,12 +11,22 @@ icon: 'images/icons/themes.svg'
 
 # Themes
 
-The default PrestaShop installation offers the neutral "Classic theme", enabling merchants to quickly start their activity, whatever their business line.
+{{% notice warning %}}
+The **Classic theme is deprecated** for new development starting from PrestaShop 9.1. It remains available for backward compatibility but will not receive new features. For Classic-specific documentation, refer to the [v8 theme docs]({{< relref "/8/themes" >}}).
+{{% /notice %}}
 
-Several marketplaces are available to get PrestaShop themes. As a graphic designer/front developer, you can put your themes up for sale on this marketplaces.
+PrestaShop themes control the entire front-office experience: layout, templates, styles, and client-side behavior.
 
-{{% notice note %}}
-A new theme, Hummingbird, is being developed by the maintainer team. While under develoment, [you can start to discover it here]({{<relref "/9/themes/hummingbird">}}).
-{{% /notice %}}
+Starting from PrestaShop 9.1, **[Hummingbird]({{< relref "/9/themes/hummingbird" >}})** is the default theme. It is built on Bootstrap 5.3, follows BEM conventions, and provides an accessibility-first, jQuery-free architecture.
+
+## Documentation structure
 
-{{% children /%}}
+| Section | What you'll find |
+|---------|-----------------|
+| **[Getting started]({{< relref "/9/themes/getting-started" >}})** | Requirements, quick start, environment setup |
+| **[Concepts]({{< relref "/9/themes/concepts" >}})** | How the PrestaShop theme system works, structure, templates, assets, hooks, overrides |
+| **[Hummingbird]({{< relref "/9/themes/hummingbird" >}})** | The reference theme, CSS architecture, JavaScript conventions, accessibility, workflow |
+| **[Create a theme]({{< relref "/9/themes/create-a-theme" >}})** | Step-by-step guides to build your own theme |
+| **[Guidelines]({{< relref "/9/themes/guidelines" >}})** | Coding standards, browser compatibility, accessibility requirements |
+| **[Reference]({{< relref "/9/themes/reference" >}})** | Lookup tables, template variables, JavaScript events, Smarty helpers |
+| **[Distribution]({{< relref "/9/themes/distribution" >}})** | Validation, testing, and exporting your theme |

themes/concepts/_index.md

@@ -0,0 +1,23 @@
+---
+title: Theme concepts
+menuTitle: Concepts
+weight: 10
+chapter: true
+showOnHomepage: true
+---
+
+# Theme concepts
+
+This section explains how the PrestaShop theme system works. These concepts apply to **any** PrestaShop theme. They are not specific to Hummingbird or any other theme implementation.
+
+| Page | Description |
+|------|-------------|
+| [Theme structure]({{< relref "/9/themes/concepts/theme-structure" >}}) | Directory layout, `theme.yml` reference, core assets |
+| [Templates]({{< relref "/9/themes/concepts/templates" >}}) | Layouts, inheritance, listing pages, head, notifications |
+| [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) | CSS/JS registration API, per-page assets, module integration |
+| [Theme hooks]({{< relref "/9/themes/concepts/hooks" >}}) | Extension points for modules in the front office |
+| [Overrides]({{< relref "/9/themes/concepts/overrides" >}}) | Module template/asset overrides and JS selector overrides |
+| [Translation]({{< relref "/9/themes/concepts/translation" >}}) | Internationalization for theme wordings |
+| [RTL support]({{< relref "/9/themes/concepts/rtl" >}}) | Right-to-left language stylesheet handling |
+
+For Hummingbird-specific architecture and conventions, see the [Hummingbird section]({{< relref "/9/themes/hummingbird" >}}).