Added rec changes

Manik-Khajuria-5 · Manik-Khajuria-5 · commit 8d25194a1fdc · 2025-12-03T16:53:39.000+05:30
diff --git a/docs/_inc/_create-classic-ui-instance.md b/docs/_inc/_create-classic-ui-instance.md
@@ -15,4 +15,4 @@ To stop the Plone instance in foreground mode, type {kbd}`ctrl-c`.
 
 ## Related content
 
-- {doc}`Classic UI </classic-ui/index>`
+- {ref}`classic-ui-index-label`
diff --git a/docs/_inc/_install-python-plone61.md b/docs/_inc/_install-python-plone61.md
@@ -10,4 +10,4 @@ Plone 6.1 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}.
 
 ## Related content
 
-- {doc}`Plone installation requirements </install/index>`
+- {ref}`Plone installation requirements <get-started-label>`
diff --git a/docs/_static/images-test/examples.png b/docs/_static/images-test/examples.png
diff --git a/docs/_static/images-test/image-srcset.png b/docs/_static/images-test/image-srcset.png
diff --git a/docs/_static/images-test/images-test.png b/docs/_static/images-test/images-test.png
diff --git a/docs/_static/images-test/picture-tags.png b/docs/_static/images-test/picture-tags.png
diff --git a/docs/admin-guide/add-site.md b/docs/admin-guide/add-site.md
@@ -72,8 +72,8 @@ Regardless of the frontend you select, you will be redirected to the backend's u
 If you select the Volto frontend, you can switch to it by changing the port number in the URL, usually `3000`, and visiting it at http://localhost:3000, for example.
 ```
 
-## Related Content
+## Related content
 
-- {doc}`/install/create-project-cookieplone` — Create a new Plone project using Cookiecutter.
-- {doc}`/admin-guide/install-buildout` — Install Plone using Buildout.
-- {doc}`/admin-guide/install-pip` — Install Plone using pip.
+- {ref}`install-cookieplone-label`
+- {ref}`install-buildout-label`
+- {ref}`install-pip-label`
diff --git a/docs/admin-guide/backup-restore-plone-buildout.md b/docs/admin-guide/backup-restore-plone-buildout.md
@@ -96,6 +96,6 @@ Some Plone sites require incremental backups every few minutes.
 
 ## Related content
 
-- {doc}`/admin-guide/export-import` — Export and import content
-- {doc}`/admin-guide/install-buildout` — Install Plone using Buildout
-- {doc}`/admin-guide/install-pip` — Install Plone using pip
+- {ref}`exportimport`
+- {ref}`install-buildout-label`
+- {ref}`install-pip-label`
diff --git a/docs/admin-guide/export-import.md b/docs/admin-guide/export-import.md
@@ -114,5 +114,5 @@ Consider a File content item with UID `3e0dd7c4b2714eafa1d6fc6a1493f953` and a P
 
 ## Related content
 
-- {doc}`/admin-guide/backup-restore-plone-buildout` — Back up and restore Plone sites
-- {doc}`/admin-guide/add-site` — Add a Plone site to an existing instance
+- {ref}`back-up-and-restore-a-plone-buildout-label`
+- {ref}`add-a-plone-site-label`
diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md
@@ -129,7 +129,7 @@ bin/instance stop
 
 ## Related content
 
-- {doc}`/admin-guide/add-site` — Add a Plone site after installation
-- {doc}`/admin-guide/install-pip` — Alternative installation method using pip
-- {doc}`/admin-guide/backup-restore-plone-buildout` — Back up and restore your Plone site
-- {doc}`/conceptual-guides/compare-buildout-pip` — Compare Buildout and pip installation methods
+- {ref}`add-a-plone-site-label`
+- {ref}`install-pip-label`
+- {ref}`back-up-and-restore-a-plone-buildout-label`
+- {ref}`compare-buildout-pip-label`
diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md
@@ -100,6 +100,6 @@ bin/runwsgi -v instance/etc/zope.ini
 
 ## Related content
 
-- {doc}`/admin-guide/add-site` — Add a Plone site after installation
-- {doc}`/admin-guide/install-buildout` — Alternative installation method using Buildout
-- {doc}`/conceptual-guides/compare-buildout-pip` — Compare Buildout and pip installation methods
+- {ref}`add-a-plone-site-label`
+- {ref}`install-buildout-label`
+- {ref}`compare-buildout-pip-label`
diff --git a/docs/backend/behaviors.md b/docs/backend/behaviors.md
@@ -381,6 +381,6 @@ This dynamically provided interface enables the component architecture to react
 
 ## Related content
 
-- {doc}`/backend/content-types/index` — Add behaviors to content types
-- {doc}`/backend/schemas` — Define schemas for behaviors
-- {doc}`/backend/fields` — Field types used in behavior schemas
+- {ref}`backend-content-types-index-label`
+- {ref}`backend-schemas-label`
+- {ref}`backend-fields-label`
diff --git a/docs/backend/content-types/creating-content-types.md b/docs/backend/content-types/creating-content-types.md
@@ -121,8 +121,8 @@ Also have a look at Plone {doc}`/backend/behaviors`, which provide default featu
 
 ## Related content
 
-- {doc}`/backend/schemas` — Define schemas for your content types
-- {doc}`/backend/fields` — Field types for content type schemas
-- {doc}`/backend/widgets` — Customize form widgets
-- {doc}`/backend/behaviors` — Add reusable behaviors to content types
-- {doc}`/backend/content-types/fti` — Configure Factory Type Information
+- {ref}`backend-schemas-label`
+- {ref}`backend-fields-label`
+- {ref}`backend-widgets-label`
+- {ref}`backend-behaviors-label`
+- {ref}`backend-content-types-fti-label`
diff --git a/docs/backend/content-types/index.md b/docs/backend/content-types/index.md
@@ -7,6 +7,8 @@ myst:
     "keywords": "Content types, Dexterity, Plone"
 ---
 
+(backend-content-types-index-label)=
+
 # Content Types
 
 This part of the documentation describes how to develop content types in Plone.
diff --git a/docs/backend/fields.md b/docs/backend/fields.md
@@ -123,6 +123,8 @@ img_obj = api.content.create(
 
 
 
+(backend-fields-relation-fields-label)=
+
 ### Fields in `z3c.relationfield.schema`
 
 See [`z3c.relationfield`](https://pypi.org/project/z3c.relationfield/) for more details.
@@ -366,7 +368,7 @@ In supermodel XML, the directives are `security:read-permission` and
 
 ## Related content
 
-- {doc}`/backend/schemas` — How fields compose schemas
-- {doc}`/backend/content-types/index` — Use fields in content type schemas
-- {doc}`/backend/vocabularies` — Define vocabularies for Choice fields
-- {doc}`/backend/relations` — Relation fields for linking content
+- {ref}`backend-schemas-label`
+- {ref}`backend-content-types-index-label`
+- {ref}`backend-vocabularies-label`
+- {ref}`relations-label`
diff --git a/docs/backend/relations.md b/docs/backend/relations.md
@@ -61,7 +61,7 @@ minions = RelationList(
 )
 ```
 
-We can see that the [code for the behavior `IRelatedItems`](https://github.com/plone/plone.app.relationfield/blob/master/plone/app/relationfield/behavior.py) does exactly the same thing.
+We can see that the [code for the behavior `IRelatedItems`](https://github.com/plone/plone.app.relationfield/blob/master/src/plone/app/relationfield/behavior.py) does exactly the same thing.
 
 
 (relations-controlling-relation-targets-label)=
@@ -646,7 +646,7 @@ But it can also be the name of a relation that is created by code, for example,
 
 ## Related content
 
-- {doc}`/backend/schemas` — Define schemas for content types and forms
-- {doc}`/backend/fields` — Field types including `RelationChoice` and `RelationList`
-- {doc}`/backend/content-types/index` — Create custom content types with relations
-- {doc}`/backend/vocabularies` — Control which items can be related using vocabularies
+- {ref}`backend-schemas-label`
+- {ref}`backend-fields-relation-fields-label`
+- {ref}`backend-content-types-index-label`
+- {ref}`backend-vocabularies-label`
diff --git a/docs/backend/schemas.md b/docs/backend/schemas.md
@@ -39,6 +39,8 @@ Zope schemas are used for tasks such as:
 -   specifying required attributes on an object
 -   defining custom validators on input data
 
+(schemas-fields-label)=
+
 The basic unit of data model declaration is the {doc}`field </backend/fields>`, which specifies what kind of data each Python attribute can hold.
 
 
@@ -731,9 +733,7 @@ def fields(self):
 
 ## Related content
 
-- {doc}`/backend/fields` — Field types used in schemas
-- {doc}`/backend/content-types/index` — Use schemas to define content types
-- {doc}`/classic-ui/forms` — Use schemas to create forms
-- {doc}`/backend/vocabularies` — Define vocabularies for Choice fields
-
-
+- {ref}`backend-fields-label`
+- {ref}`backend-content-types-index-label`
+- {ref}`classic-ui-forms-label`
+- {ref}`backend-vocabularies-label`
diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-python3.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-python3.md
@@ -382,6 +382,6 @@ Here is a list of helpful references on the topic of porting Python 2 to Python
 -   https://eev.ee/blog/2016/07/31/python-faq-how-do-i-port-to-python-3/
 -   https://diveintopython3.net/
 -   https://docs.djangoproject.com/en/1.11/topics/python3/
--   https://docs.ansible.com/ansible/latest/dev_guide/developing_python_3.html
+-   https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html
 -   https://docs.python.org/2/library/doctest.html#debugging
 ```
diff --git a/docs/backend/vocabularies.md b/docs/backend/vocabularies.md
@@ -22,6 +22,6 @@ See issue [Backend > Vocabularies needs content](https://github.com/plone/docume
 
 ## Related content
 
-- {doc}`/backend/fields` — Use vocabularies with Choice fields
-- {doc}`/backend/schemas` — Define schemas with Choice fields
-- {doc}`/backend/content-types/index` — Use vocabularies in content type schemas
+- {ref}`backend-fields-label`
+- {ref}`backend-schemas-label`
+- {ref}`backend-content-types-index-label`
diff --git a/docs/backend/widgets.md b/docs/backend/widgets.md
@@ -624,7 +624,7 @@ You can set the template used by the widget with the `<z3c:widgetTemplate>` ZCML
 ### Widget frame override
 
 You can override widget templates as instructed for `z3c.form`.
-`plone.app.z3cform` renders [a frame around each widget](https://github.com/plone/plone.app.z3cform/blob/master/plone/app/z3cform/templates/widget.pt), which usually consists of:
+`plone.app.z3cform` renders [a frame around each widget](https://github.com/plone/plone.app.z3cform/blob/master/src/plone/app/z3cform/templates/widget.pt), which usually consists of:
 
 -   Label
 -   Required marker
@@ -633,7 +633,7 @@ You can override widget templates as instructed for `z3c.form`.
 You might want to customize this widget frame for your own form.
 Below is an example of how to do it.
 
-Copy [`widget.pt`](https://github.com/plone/plone.app.z3cform/blob/master/plone/app/z3cform/templates/widget.pt) to your own package, rename it as `demo-widget.pt`, and edit it.
+Copy [`widget.pt`](https://github.com/plone/plone.app.z3cform/blob/master/src/plone/app/z3cform/templates/widget.pt) to your own package, rename it as `demo-widget.pt`, and edit it.
 
 Then add the following code to `configure.zcml`.
 Remember to fix the path of the template according to your own paths.
@@ -786,7 +786,7 @@ The code renders both widgets, {guilabel}`min` and {guilabel}`max`, in a single
 
 ## Related content
 
-- {doc}`/backend/fields` — Field types that use widgets
-- {doc}`/backend/schemas` — Define schemas with widget directives
-- {doc}`/classic-ui/forms` — Use widgets in forms
-- {doc}`/backend/content-types/index` — Customize widgets for content types
+- {ref}`backend-fields-label`
+- {ref}`backend-schemas-label`
+- {ref}`classic-ui-forms-label`
+- {ref}`backend-content-types-index-label`
diff --git a/docs/classic-ui/forms.md b/docs/classic-ui/forms.md
@@ -174,7 +174,7 @@ In the template, you can use the following variables:
 Dexterity content types come with default add and edit forms.
 You can build custom add and edit forms to adjust their behavior.
 
-The implementation of the default edit and add forms is in [`plone.dexterity.browser.edit.py`](https://github.com/plone/plone.dexterity/blob/master/plone/dexterity/browser/edit.py) and [`plone.dexterity.browser.add.py`](https://github.com/plone/plone.dexterity/blob/master/plone/dexterity/browser/add.py).
+The implementation of the default edit and add forms is in [`plone.dexterity.browser.edit.py`](https://github.com/plone/plone.dexterity/blob/master/src/plone/dexterity/browser/edit.py) and [`plone.dexterity.browser.add.py`](https://github.com/plone/plone.dexterity/blob/master/src/plone/dexterity/browser/add.py).
 
 ```{todo}
 Describe Add/Edit forms here and how to customize them.
diff --git a/docs/classic-ui/images.md b/docs/classic-ui/images.md
@@ -248,7 +248,7 @@ To scale an image, you can use the `mode` parameter to control the scaling outpu
 You must use either `width` or `height`, or both.
 
 Three different scaling options are supported.
-They correspond to the CSS [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) values.
+They correspond to the CSS [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background-size) values.
 
 The possible options for `mode` are listed below, where the default option is `scale`.
 
@@ -272,6 +272,92 @@ The possible options for `mode` are listed below, where the default option is `s
 
     Deprecated option names: `scale-crop-to-fill`, `up`.
 
+### Images test rendering
+
+Plone's Classic UI includes special demonstration views that render ready-made examples of image handling and responsive image components using your site's active theme.
+These views help developers verify image scaling, `srcset` generation, and explore available image optimization patterns.
+These views work on image content types, including images and documents with images.
+
+Append the view name `/@@images-test` to an image URL, optionally followed by an anchor, such as `#srcset`, for specific sections.
+You must be authenticated as a site admin to view this demo.
+
+For example, on the Classic UI demo site, the URL would be https://classic.demo.plone.org/en/demo/an-image.jpg/@@images-test#srcset.
+
+````{card}
+```{image} /_static/images-test/images-test.png
+:alt: Images test view
+:target: /_static/images-test/images-test.png
+```
++++
+_Images test view_
+````
+
+The view displays the following examples, all rendered with the current settings in `/@@imaging-controlpanel`.
+
+Standard image scales
+:   Shows the Classic UI Plone scales with different modes:
+    -   Mini
+    -   Mini mode=cover
+    -   Mini mode=contain
+
+    ````{card}
+    ```{image} /_static/images-test/examples.png
+    :alt: Example standard image scales
+    :target: /_static/images-test/examples.png
+    ```
+    +++
+    _Example standard image scales_
+    ````
+
+Picture tags
+:   Demonstrates the use of `<picture>` elements with configured picture variants.
+    If the site runs on Plone 5.2 or earlier, a regular `<img>` tag is rendered instead.
+
+    Picture Tag Large
+    :   uses the configured `large` picture variant
+
+    Picture Tag Medium
+    :   uses the `medium` variant with multiple `<source>` elements and media queries for art direction
+
+    Picture Tag Small
+    :   uses the `small` variant
+
+    Picture Tag Small with title/alt
+    :   same as the previous, but with `title` and `alt` attributes explicitly set
+
+````{card}
+```{image} /_static/images-test/picture-tags.png
+:alt: Picture tags
+:target: /_static/images-test/picture-tags.png
+```
++++
+_Picture tags_
+````
+
+`img` with `srcset` attributes
+:   Shows how to use Plone’s `@@images` view to generate a full responsive `<img>` tag with a complete `srcset`.
+    The browser automatically selects the most appropriate scale based on the available space and device pixel ratio.
+    The example includes the required `sizes` attribute and demonstrates the resulting HTML output.
+    
+    ```{seealso}
+    {ref}`classic-ui-images-responsive-image-support`
+    ```
+
+````{card}
+```{image} /_static/images-test/image-srcset.png
+:alt: img with srcset attributes
+:target: /_static/images-test/image-srcset.png
+```
++++
+_img with srcset attributes_
+````
+
+```{seealso}
+{ref}`classic-ui-images-responsive-image-support`
+```
+
+This view is especially valuable for theme developers who need to verify that responsive images, picture variants, and `srcset` functionality are correctly styled and behave as expected across devices and Plone versions.
+
 
 (classic-ui-images-permissions-label)=
 
@@ -286,7 +372,7 @@ To access image scales, which are normally not accessible to the current user, o
 ## Responsive image support
 
 Plone supports the generation of [`picture`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/picture) tags with `srcset`s for image optimization.
-Additionally, you can define [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) for [art direction](classic-ui-images-responsive-image-support-art-direction) and further optimization.
+Additionally, you can define [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries/Using) for [art direction](classic-ui-images-responsive-image-support-art-direction) and further optimization.
 
 The configuration allows you to define different `picture` variants, such as `Large`, `Medium`, or `Small`.
 Users can choose from them in editors, such as TinyMCE, and developers can use them in templates.
diff --git a/docs/classic-ui/theming/css-custom-properties.md b/docs/classic-ui/theming/css-custom-properties.md
@@ -11,7 +11,7 @@ myst:
 
 # CSS custom properties
 
-This chapter describes the [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) used in Bootstrap and customized by Classic UI themes.
+This chapter describes the [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) used in Bootstrap and customized by Classic UI themes.
 Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that represent specific values to be reused throughout a document.
 
 
diff --git a/docs/classic-ui/viewlets.md b/docs/classic-ui/viewlets.md
@@ -190,7 +190,7 @@ These methods should honor the [`zope.contentprovider.interfaces.IContentProvide
 
 ```{seealso}
 -   [`zope.contentprovider.interfaces`](https://github.com/zopefoundation/zope.contentprovider/blob/3.7.2/src/zope/contentprovider/interfaces.py)
--   [`plone.app.layout.viewlets.common`](https://github.com/plone/plone.app.layout/blob/master/plone/app/layout/viewlets/common.py)
+-   [`plone.app.layout.viewlets.common`](https://github.com/plone/plone.app.layout/blob/master/src/plone/app/layout/viewlets/common.py)
 ```
 
 
@@ -822,7 +822,7 @@ Hide the concerning viewlets in one manager using `/@@manage-viewlets` and {file
 ```
 
 Viewlet managers are based on [`zope.viewlet.manager.ViewletManager`](https://github.com/zopefoundation/zope.viewlet/blob/master/src/zope/viewlet/manager.py)
-and [`plone.app.viewletmanager.manager.OrderedViewletManager`](https://github.com/plone/plone.app.viewletmanager/blob/master/plone/app/viewletmanager/manager.py).
+and [`plone.app.viewletmanager.manager.OrderedViewletManager`](https://github.com/plone/plone.app.viewletmanager/blob/master/src/plone/app/viewletmanager/manager.py).
 
 ```{seealso}
 -   [`zope.viewlet`](https://github.com/zopefoundation/zope.viewlet/blob/master/src/zope/viewlet/viewlet.py)
diff --git a/docs/classic-ui/views.md b/docs/classic-ui/views.md
@@ -38,7 +38,7 @@ This enhances readability and makes components more reusable.
 You can override the Python logic, the template file, or both.
 
 When you work with Plone, the most common view type is `BrowserView` from the package [`Products.Five`](https://github.com/zopefoundation/Zope/blob/master/src/Products/Five/doc/manual.txt).
-Other view types include `DefaultView` from [`plone.dexterity`](https://github.com/plone/plone.dexterity/blob/master/plone/dexterity/browser/view.py) and `CollectionView` from [`plone.app.contenttypes`](https://github.com/plone/plone.app.contenttypes/blob/master/plone/app/contenttypes/browser/collection.py).
+Other view types include `DefaultView` from [`plone.dexterity`](https://github.com/plone/plone.dexterity/blob/master/src/plone/dexterity/browser/view.py) and `CollectionView` from [`plone.app.contenttypes`](https://github.com/plone/plone.app.contenttypes/blob/master/src/plone/app/contenttypes/browser/collection.py).
 
 Each `BrowserView` class is a Python callable.
 The `BrowserView.__call__()` method acts as an entry point to executing the view code.
@@ -255,7 +255,7 @@ Add the name of the new view `my-view` to the following list:
 ### Template slots
 
 In the generated template above, we have a `fill-slot` attribute.
-This will fill the slot with the name `content-core`, which is defined in Plone's [`main_template`](https://github.com/plone/Products.CMFPlone/blob/master/Products/CMFPlone/browser/templates/main_template.pt).
+This will fill the slot with the name `content-core`, which is defined in Plone's [`main_template`](https://github.com/plone/Products.CMFPlone/blob/master/src/Products/CMFPlone/browser/templates/main_template.pt).
 The following list shows the available options for `<metal fill-slot="">` in your template.
 
 ```{note}
diff --git a/docs/conceptual-guides/compare-buildout-pip.md b/docs/conceptual-guides/compare-buildout-pip.md
@@ -7,6 +7,8 @@ myst:
     "keywords": "Plone 6, Conceptual guides, Classic UI, Buildout, pip, install"
 ---
 
+(compare-buildout-pip-label)=
+
 # Compare Buildout and pip
 
 This guide explains the differences between two tools, {term}`Buildout` and {term}`pip`, to install Plone and its Classic UI user interface, helping to inform your choice when developing your new project in Plone.
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md
diff --git a/docs/glossary.md b/docs/glossary.md
diff --git a/docs/i18n-l10n/index.md b/docs/i18n-l10n/index.md
diff --git a/docs/i18n-l10n/translating-text-strings.md b/docs/i18n-l10n/translating-text-strings.md
diff --git a/docs/i18n-l10n/use-an-external-translation-service.md b/docs/i18n-l10n/use-an-external-translation-service.md

Original file line number	Diff line number	Diff line change
@@ -15,4 +15,4 @@ To stop the Plone instance in foreground mode, type {kbd}`ctrl-c`.
`15`	`15`
`16`	`16`	`## Related content`
`17`	`17`
`18`		-- {doc}`Classic UI </classic-ui/index>`
	`18`	+- {ref}`classic-ui-index-label`
Original file line number	Diff line number	Diff line change
`@@ -10,4 +10,4 @@ Plone 6.1 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}.`
`10`	`10`
`11`	`11`	`## Related content`
`12`	`12`
`13`		-- {doc}`Plone installation requirements </install/index>`
	`13`	+- {ref}`Plone installation requirements <get-started-label>`