Add docs for the freemarker templates

[Nuvindu]

Purpose

Fixes: wso2/product-integrator#1971

Summary by CodeRabbit

• Documentation
  • Updated the FreeMarker transform guide with clearer security/usage guidance for file-based template rendering, explicitly restricting templates to trusted, operator-managed content and disallowing user-supplied input.
  • Strengthened best-practice recommendations for HTML escaping during rendering.
  • Adjusted prior wording about reviewability of production templates.
• Documentation Navigation
  • Added the FreeMarker guide to the Develop → Transform section.
• Other
  • Enabled Prism syntax highlighting for ftl.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updates FreeMarker documentation with template trust-boundary and HTML-escaping guidance, adds the page to the Transform sidebar, and enables FTL syntax highlighting.

Changes

FreeMarker documentation

Layer / File(s)	Summary
Rendering security and best practices en/docs/develop/transform/freemarker.md	Clarifies that file-based templates are trusted, operator-managed content and must not use user-supplied input; adds HTML-escaping guidance using ${value?html} or .ftlh.
Documentation navigation and syntax highlighting en/sidebars.ts, en/docusaurus.config.ts	Adds the FreeMarker page to the Transform sidebar and enables ftl syntax highlighting.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: rosensilva, anupama-pathirage, kavinduzoysa, nipunaranasinghe

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description includes only the Purpose section with a link to the related issue and screenshots, but lacks most required sections such as Goals, Approach, User stories, Release note, and others.	Complete the pull request description by filling in the Goals, Approach, User stories, Release note, Documentation, and other required template sections to provide comprehensive context for reviewers.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds the requested Freemarker documentation for WSO2 Integrator and includes supportive docs/config updates.
Out of Scope Changes check	✅ Passed	The sidebar and Prism language additions directly support the new docs and do not introduce unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly and directly describes the main change: adding documentation for FreeMarker templates, which is the primary objective of the pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Broken links, images & orphan pages

✅ Passing — no broken links or images found.

Links/images come from one crawl of the production build (baseUrl-aware). Orphans are docs not referenced by sidebars.ts.

Summary

• Broken links & images — total 0 · 🆕 introduced 0 · 📄 already on main 0
• Orphan pages — total 8 · 🆕 introduced 0 · 📄 already on main 8

Broken links & images

Introduced by this PR

No new broken link(s)/image(s) introduced by this PR. ✅

Already on main — 0 total

None.

Orphan pages

Introduced by this PR

No new orphan page(s) introduced by this PR. ✅

Already on main — 8 total

Already present on the base branch (not caused by this PR):

Show 8

• docs/deploy-operate/observe/datadog-integration
• docs/deploy-operate/observe/elastic-stack-elk
• docs/deploy-operate/observe/metrics-prometheus-grafana
• docs/deploy-operate/observe/opensearch-integration
• docs/deploy-operate/observe/recipe-elk-stack
• docs/deploy-operate/observe/recipe-kubernetes-production
• docs/deploy-operate/observe/recipe-local-development
• docs/deploy-operate/observe/recipe-opensearch-setup

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@en/docs/develop/transform/freemarker.md`:
- Around line 14-16: Update the “Rendering from a file” guidance around
freemarker:renderFromFile to describe disk templates as trusted,
operator-managed server-side code; remove the suggestion that non-developers can
freely edit them and explicitly state that user-supplied template source is
prohibited.
- Around line 25-32: Add ftl to the themeConfig.prism.additionalLanguages list
in docusaurus.config.ts, preserving the existing registered languages. This
enables syntax highlighting for the FreeMarker fences used throughout
freemarker.md.
- Around line 196-204: Add a best-practice entry near the existing formatting
and nullable-field guidance explaining that interpolated untrusted values must
be HTML-escaped with the ?html built-in, or that templates should use an HTML
output format via .ftlh or output_format="HTML". Clarify that render and
renderFromFile otherwise use FreeMarker’s undefined output format and do not
escape values automatically.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d1c0080b-1813-4ec1-b57e-27176ec3e9b1

📥 Commits

Reviewing files that changed from the base of the PR and between 0e8e2a6 and 24e9d9d.

⛔ Files ignored due to path filters (6)

• en/static/img/develop/transform/freemarker/freemarker-file-read-json.png is excluded by !**/*.png
• en/static/img/develop/transform/freemarker/freemarker-json-variable.png is excluded by !**/*.png
• en/static/img/develop/transform/freemarker/freemarker-print-inline-result.png is excluded by !**/*.png
• en/static/img/develop/transform/freemarker/freemarker-print-result.png is excluded by !**/*.png
• en/static/img/develop/transform/freemarker/freemarker-render-from-file.png is excluded by !**/*.png
• en/static/img/develop/transform/freemarker/freemarker-render-inline.png is excluded by !**/*.png

📒 Files selected for processing (2)

• en/docs/develop/transform/freemarker.md
• en/sidebars.ts