Otoroshi advanced features guide

.github/copilot-instructions.md

@@ -105,12 +105,19 @@ aliases:
 - Always specify **current versions** of software/tools
 - Include **environment variables** with exact names and examples
 - Provide **command-line examples** with proper syntax
-- Use **callouts for important information**:
+- Prefer **GitHub-style callouts for important information**. They render in both GitHub and the documentation site:
   ```markdown
-  > [!NOTE] Context about new features
-  > [!TIP] Helpful suggestions
-  > [!WARNING] Important considerations
+  > [!NOTE]
+  > Context about new features.
+
+  > [!TIP]
+  > Helpful suggestions.
+
+  > [!WARNING]
+  > Important considerations.
   ```
+- Use the Hugo `{{< callout >}}` shortcode only when GitHub-style syntax can't provide the required rendering or behaviour
+- Limit callouts to one or two per page
 
 ### Guide-Specific Rules
 
@@ -223,7 +230,7 @@ clever keycloak version update yourKeycloakNameOrId
 - [ ] Examples use realistic project names and values
 - [ ] No first-person pronouns (I, we, us, our)
 - [ ] Short, clear sentences under 25 words
-- [ ] Proper callouts for important information
+- [ ] GitHub-style callouts used for important information where needed
 
 ### Before Publishing Changelog
 - [ ] Clear benefit/impact stated upfront
@@ -273,10 +280,30 @@ The site is configured for Clever Cloud hosting with the `static` runtime and th
 - `CC_WEBROOT="public"`
 - `CC_STATIC_AUTOBUILD_OUTDIR="public/developers"`
 - `SERVER_ERROR_PAGE_404="developers/404.html"`
-- Optional: `CC_HUGO_VERSION="0.152"` to specify Hugo version (example value)
+- Optional: `CC_HUGO_VERSION="0.161"` to specify Hugo version (example value)
 
 ## Quality Assurance Requirements
 
+### Commit Message Convention
+Use `section(page): commit message` for content updates. The section and page must identify the documentation area being changed:
+
+```text
+addons(postgresql): document pg_partman support
+applications(nodejs): clarify pnpm configuration
+changelog(metabase): announce 0.63.14 security update
+```
+
+Use standard Conventional Commits for documentation structure, Hugo configuration or templates, deployment, CI, tooling, and dependency changes:
+
+```text
+feat(hugo): add a shortcode for version tables
+fix(ci): run Vale on shared content
+refactor(layouts): simplify changelog rendering
+chore(deps): update the Hextra theme
+```
+
+Split content and structural changes into separate commits when possible.
+
 ### Build Verification
 Always test changes with the `hugo` command before committing to ensure the build is functional. Fix any build errors immediately as they prevent deployment. Verify that all links, references, image paths, and shortcode syntax work correctly in the generated output.
 

.github/styles/config/vocabularies/Doc/accept.txt

@@ -32,6 +32,7 @@ DNS
 Dockerfile
 downtimes
 eg
+Entra
 EOL
 ESLint
 failover
@@ -45,6 +46,7 @@ Glassfish
 Gradle
 gradle
 Grafana
+hardcoded
 healthcheck
 Heptapod
 Hextra
@@ -61,9 +63,11 @@ LLM
 LLMs
 Lume
 LTS
+Materia
 Matomo
 maven
 Metabase
+middleware
 monolog
 monorepo
 monorepository
@@ -75,6 +79,7 @@ nmap
 npm
 Nuxt
 OAuth
+Okta
 Otoroshi
 packageManager
 Payara

.github/workflows/deploy.yml

@@ -35,7 +35,7 @@ jobs:
           CLEVER_SECRET: ${{ secrets.CLEVER_SECRET }}
           CLEVER_TOKEN: ${{ secrets.CLEVER_TOKEN }}
           ORGA_ID: ${{ secrets.ORGA_ID }}
-          GH_CC_HUGO_VERSION: 0.152
+          GH_CC_HUGO_VERSION: 0.163
           GH_CC_STATIC_AUTOBUILD_OUTDIR: public/developers
           GH_CC_WEBROOT: public
           GH_SERVER_ERROR_PAGE_404: developers/404.html

CLAUDE.md

@@ -78,6 +78,30 @@ For changelog entries, also include:
 - **Structure**: Use 2-4 well-developed paragraphs per section, minimize bullet lists
 - **Paragraphs**: Aim for 3-6 lines for optimal readability
 
+### Callouts
+- Prefer GitHub-style callouts because they render in both GitHub and the documentation site:
+  ```markdown
+  > [!NOTE]
+  > This information helps readers understand the current behaviour.
+
+  > [!WARNING]
+  > Back up your application database before upgrading.
+  ```
+- Use the Hugo `{{< callout >}}` shortcode only when GitHub-style syntax can't provide the required rendering or behaviour
+- Limit callouts to one or two per page
+
+### Commit Messages
+- For content updates, use `section(page): commit message`, for example:
+  - `addons(postgresql): document pg_partman support`
+  - `applications(nodejs): clarify pnpm configuration`
+  - `changelog(metabase): announce 0.63.14 security update`
+- For documentation structure, Hugo, deployment, CI, tooling, or dependency changes, use standard Conventional Commits, for example:
+  - `feat(hugo): add a shortcode for version tables`
+  - `fix(ci): run Vale on shared content`
+  - `refactor(layouts): simplify changelog rendering`
+  - `chore(deps): update the Hextra theme`
+- Split content and structural changes into separate commits when possible
+
 ### Code and Technical Examples
 - Always provide complete, runnable code examples
 - Use exact environment variable names: `CC_WEBROOT`, `CC_NODE_BUILD_TOOL`, etc.
@@ -90,7 +114,7 @@ The site is configured for Clever Cloud hosting with the `static` runtime and th
 - `CC_WEBROOT="public"`
 - `CC_STATIC_AUTOBUILD_OUTDIR="public/developers"`
 - `SERVER_ERROR_PAGE_404="developers/404.html"`
-- Optional: `CC_HUGO_VERSION="0.152"` to specify Hugo version (example value)
+- Optional: `CC_HUGO_VERSION="0.161"` to specify Hugo version (example value)
 
 ## Data Management
 Runtime versions and software compatibility information is maintained in `/data/runtime_versions.yml` and should be kept current with platform capabilities. The site generates various output formats including standard HTML and a special LLMS output format at `/llms.txt` for AI consumption.
@@ -103,7 +127,7 @@ Runtime versions and software compatibility information is maintained in `/data/
 - `{{% steps %}}` - Create step-by-step instructions for guides
 - `{{< tabs items="npm,yarn,pnpm" >}}` - Create tabbed content sections
 - `{{< cards >}}` - Display card layouts for related resources
-- `{{< callout >}}` - Create note, tip, warning callouts
+- `{{< callout >}}` - Create a callout only when GitHub-style syntax isn't sufficient
 - `{{< hextra/hero-subtitle >}}` - Add engaging subtitles in guides
 
 ### Hugo Content Types

CONTRIBUTING.md

@@ -40,13 +40,24 @@ Sources for quality content are currently being updated.
 - Using phrases like _simply_, _It's that simple_, _It's easy_, or _quickly_ in a procedure.
 - Over-politeness with the use of _please_: go straight to the point.
 
-#### 💡 Shortcodes
+#### 💡 Shortcodes and callouts
 
 This doc uses Hugo with [Hextra theme](https://imfing.github.io/hextra/), which provides a variety of [shortcodes](https://imfing.github.io/hextra/docs/guide/shortcodes/) to enhance it and improve its readability.
 For example :
 
 - [Steps](https://imfing.github.io/hextra/docs/guide/shortcodes/steps/) are well suited for the `/guides/` section, or for any tutorial.
-- [Callouts](https://imfing.github.io/hextra/docs/guide/shortcodes/callout/) draw attention to an important information in the page. However, don't overuse them, as too many callouts can miss their point and make the page crowded. Limit callouts to one or two per page.
+
+Use GitHub-style callouts whenever possible. They remain readable on GitHub and don't depend on Hugo-specific rendering:
+
+```markdown
+> [!NOTE]
+> This information helps readers understand the current behaviour.
+
+> [!WARNING]
+> Back up your application database before upgrading.
+```
+
+Use the [Hextra callout shortcode](https://imfing.github.io/hextra/docs/guide/shortcodes/callout/) only when a GitHub-style callout can't provide the required rendering or behaviour. Don't overuse callouts: limit them to one or two per page.
 
 ### 💅 Style guide
 
@@ -68,6 +79,27 @@ Priority goes to PRs that reference a problem addressed in an issue fitting the
 - **Keep it small:** The quality of the review is inversely proportional to the size of the PR. Smaller PRs simplify the reviewing process and increase the chances of getting constructive feedback.
 - **Accept the feedback:** If reviewers ask you to make changes, do it. If you disagree, explain why. If you aren't sure, ask for clarification. Don't nitpick on the feedback, and don't take it personally.
 
+#### Commit messages
+
+For content updates, use `section(page): commit message`. The section and page identify the documentation area you changed:
+
+```text
+addons(postgresql): document pg_partman support
+applications(nodejs): clarify pnpm configuration
+changelog(metabase): announce 0.63.14 security update
+```
+
+For changes to the documentation structure, Hugo configuration or templates, deployment, CI, tooling, or dependencies, use the standard Conventional Commits format `type(scope): commit message`:
+
+```text
+feat(hugo): add a shortcode for version tables
+fix(ci): run Vale on shared content
+refactor(layouts): simplify changelog rendering
+chore(deps): update the Hextra theme
+```
+
+Keep content and structural changes in separate commits when possible so each commit can follow the appropriate convention.
+
 ### 🥸 When reviewing a PR
 
 - **Latency:** Long PR review latency can be disappointing for the authors, and make merge conflicts arise in their branch. Long latency kills productivity and morale, so make sure to review PRs in a timely manner.

README.md

@@ -57,7 +57,7 @@ SERVER_ERROR_PAGE_404="developers/404.html"
 ```
 
 > [!TIP]
-> You can set the Hugo version with `CC_HUGO_VERSION` with a value like `0.152`
+> You can set the Hugo version with `CC_HUGO_VERSION` with a value like `0.161`
 
 ## Contributing