Global refactor of themes section #2129
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,2 @@ | ||
| .idea/ | ||
| .claude/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| # PrestaShop Developer Docs — Claude 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`, …). This file lives on the `9.x` branch — all content paths are prefixed with `/9/`. 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 | ||
|
|
||
| - 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 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Themes Section — Claude Context | ||
|
|
||
| This file is loaded in addition to the root `CLAUDE.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/`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -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 | | ||||||
| | [Hooks]({{< relref "/9/themes/concepts/hooks" >}}) | Extension points for modules in the front office | | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
To maintain consistency, this should be renamed to display as it does in the menu (like the other entries). |
||||||
| | [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" >}}). | ||||||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have to remove this link, this is a non sens