Release 5.2

README.md

@@ -65,10 +65,10 @@ The Joomla Manual contains documentation for multiple versions of the Joomla sof
 
 The mapping between the versions of the manual in github and the live manual is:
 
-| github manual (development)      | Live Docusaurus manual |
-| -------------------------------- | ---------------------- |
-| /docs                            | "upcoming" release  (shown as /docs/next in the URL)     |
-| /versioned_docs/version-m.n      | version m.n (under "Current releases")        |
+| github manual (development)      | Live Docusaurus manual                               |
+| -------------------------------- |------------------------------------------------------|
+| /docs                            | "upcoming" release  (shown as /docs/next in the URL) |
+| /versioned_docs/version-m.n      | version m.n (under "Current releases")               |
 
 If your documentation changes relate to multiple versions of Joomla then you should duplicate these changes into multiple versions of Joomla manual. These versions which are updated are currently agreed to be: 
 - the version m.n of the latest full Joomla release ("latest" release)

docusaurus.config.js

@@ -84,23 +84,29 @@ const config = {
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/joomla/manual/tree/main/',
-          lastVersion: '5.1',
+          lastVersion: '5.2',
           versions: {
             'current': {
-              label: '5.2 (upcoming)',
+              label: '5.3 (Upcoming)',
               banner: 'unreleased'
             },
+            '5.2': {
+              label: '5.2 (Current)',
+            },
             '5.1': {
-              label: '5.1',
+              label: '5.1 (Archived)',
+              banner: 'unmaintained'
             },
             '5.0': {
-              label: '5.0',
+              label: '5.0 (Archived)',
+              banner: 'unmaintained'
             },
             '4.4': {
-              label: '4.4',
-            }
+              label: '4.4 (Security)',
+              banner: 'none'
+            },
           },
-          /*onlyIncludeVersions: ['current', '4.3'], */
+          /* onlyIncludeVersions: ['current', '5.2', '4.4'], */
           remarkPlugins: [
               // Configure the plugin for parsing the API links
               [apiLinkPlugin,{
@@ -180,27 +186,6 @@ const config = {
               },
             ],
             dropdownItemsAfter: [
-              {
-                type: 'html',
-                value: '<hr class="dropdown-separator">',
-              },
-              {
-                type: 'html',
-                className: 'dropdown-archived-versions',
-                value: '<b>Archived versions</b>',
-              },
-              {
-                label: '3.x',
-                href: 'https://docs.joomla.org/Category:Joomla!_3.0',
-              },
-              {
-                label: '2.5',
-                href: 'https://docs.joomla.org/Category:Joomla!_2.5',
-              },
-              {
-                type: 'html',
-                value: '<hr class="dropdown-separator">',
-              },
               {
                 to: '/versions',
                 label: 'All versions',

versioned_docs/version-5.2/about/documentation.md

@@ -0,0 +1,162 @@
+This documentation
+==================
+
+This [Joomla development manual](https://manual.joomla.org/docs/) is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator. If you want to contribute to it then this page will help you get started.
+
+Updates to the documentation is managed via the [Joomla manual github repository](https://github.com/joomla/Manual), so you should initially fork this repository into your own github account. Then you can make changes to the documentation files and submit a pull request to the Joomla manual. Ensure that you continue to sync your fork branches with the Joomla manual `main` branch. 
+
+The documentation uses the [Markdown](https://www.markdownguide.org/) syntax, with additional features which Docusaurus provides.
+
+To make documentation changes you'll probably find it easiest to use one of two options:
+1. Install Docusaurus on your own machine, and make changes there
+2. Use [github dev](https://github.com/github/dev) to make the changes on the github server. 
+
+## Install Docusaurus
+
+To install Docusaurus on your own machine you should initialise a local git repository and clone the manual from the forked copy in your githut repository into this git instance. 
+
+Then change directory to your local git repository and issue:
+
+```
+$ npm install
+```
+
+Once Docusaurus is installed:
+
+```
+$ npm run start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+```
+$ npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Use github dev
+
+To use github dev go to your repository and press the "." (dot) key, as described within the [github.dev guide](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor). You can then:
+- create a new git branch for your changes
+- create new files and folders, modify and delete existing files, upload files
+- preview files (right-click on the file tab) - this will show interpreted markdown, but will not interpret Docusaurus additions
+- commit and push changes
+- return to github repository (by clicking on GitHub in bottom left, or by replacing github.dev by github.com in the URL)
+
+## Pull Requests
+
+Once you raise a pull request on the [Joomla manual](https://github.com/joomla/Manual) a test build is run to identify any problems with your documentation. If you find a check has failed then click on the Details of the check which failed, and you can check the console logs to find the problem.
+
+When the build succeeds you will be able to see the result of your documentation changes by navigating to a URL like `http://pr-240.manual.joomlacode.org/docs/`, where you replace 240 with the number of your pull request.
+This link will be added to the "checks" section in the pull request as "preview". 
+
+## Versions
+
+The Joomla Manual contains documentation for multiple versions of the Joomla software. 
+
+The mapping between the versions of the manual in github and the live manual is:
+
+| github manual (development)      | Live Docusaurus manual |
+| -------------------------------- | ---------------------- |
+| /docs                            | "upcoming" release  (shown as /docs/next in the URL)     |
+| /versioned_docs/version-m.n      | version m.n (under "Current releases")        |
+
+If your documentation changes relate to multiple versions of Joomla then you should duplicate these changes into multiple versions of Joomla manual. These versions which are updated are currently agreed to be: 
+- the version m.n of the latest full Joomla release ("latest" release)
+- the version m.n+1 of the next Joomla release ("upcoming" release)
+- the last version (m-1.last) of the Joomla previous major version 
+
+Other versions may be present within /versioned_docs but are not updated with the changes, even if the documentation is true for those Joomla versions. 
+
+To minimise changes it's recommended that you initially just make changes within the /docs area, and then raise the pull request. This allows team members to review the documentation, and for you to fix any issues without having to replicate changes to multiple versions. Then when the review process is complete the changes can be replicated to the other versions prior to merging. 
+
+Once the pull request is merged you can delete the branch on your own repository, and sync your `main` branch with the updated Joomla manual `main`.
+
+## Common Build Problems
+
+If you use angle brackets or curly brackets in text then always enclose these in backticks, like `<h1>` or `{['a':1, 'b':2]}`.
+
+Don't use colons (:) in titles.
+
+Don't use `<br>` to force a new line (eg in table text); use `<br/>` instead. 
+
+## Docusaurus Additions
+
+[Front Matter](https://docusaurus.io/docs/next/markdown-features#front-matter) should be used for titles and position in the left-hand sidebar:
+```
+---
+title: Best Practices
+sidebar-position: 2
+---
+```
+
+[Code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) are enclosed in 3 backticks, and can have a title:
+```php title="hello.php"
+public static function hello() 
+{
+    echo "Hello!"; 
+}
+```
+Line numbering and highlighting of individual lines are also supported.
+
+To aid readability of the markdown please leave a blank line before and after code blocks.
+
+[Admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 
+We don't use blank lines around content, and we add 2 spaces before the text messages.
+
+```
+:::note[Developer Note]
+  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+:::
+
+:::note[Joomla Issue]
+  For issues that affect the documentation - please link to the issue on the Joomla Issue Tracker
+:::
+
+:::tip
+  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+:::
+
+:::info
+  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+:::
+
+:::warning
+  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+:::
+
+:::danger
+  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+:::
+```
+
+Please use the following placeholder for unfinished sections of a document.
+
+```
+:::note[TODO]
+  This section is missing, please use the **Edit this Page** link at the bottom of this page to add this section.
+:::
+```
+
+If the page is not completed yet and bigger parts are missing use
+
+```
+:::caution[TODO]
+  This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
+:::
+```
+
+## Diagrams
+
+Where possible, use [Mermaid](https://mermaid.live) for creating diagrams for inclusion in the documentation. Where Mermaid doesn't provide what you need, then please include the saved diagram from your drawing tool in addition to the image file.
+
+Images, code zip files, etc should be held in a folder `_assets` at the point in the documentation where they're used.
+
+## Other Recommendations
+
+To align with a11y requirements for accessibility, please don't have more than one header level 1:
+
+```
+# Just One H1
+```

versioned_docs/version-5.2/about/index.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 12
+---
+About
+=====
+:::caution TODO
+
+This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
+
+:::

versioned_docs/version-5.2/about/versioning.md

@@ -0,0 +1,16 @@
+Versioning the documentation
+============================
+
+The documentation should reflect the current releases of Joomla!. For each minor version we will have a tagged version in the documentation and update the version dropdown in this documentation.
+
+## Command to run
+When we release a new minor Joomla! version, the documentation will be frozen and the version will be tagged. Use
+
+```bash npm2yarn
+npm run docusaurus docs:version 4.3.0
+```
+
+to tag a version. The current state of the documentation will be copied to the ```versioned_docs``` folder and the ```versions.js``` is updated.
+
+## Update the Versions dropdown
+In the ```docusaurus.config.js``` the key ```onlyIncludeVersions``` has to be updated to the latest stable version. Also the ```lastVersion``` has to be updated properly and the ```versions``` labels should be set.

versioned_docs/version-5.2/accessibility/atag.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 3
+---
+ATAG Conformance
+===========
+In this section we will explain the Authoring Tool Accessibility Guidelines, which level of conformance we are aiming for, and how to learn more about ATAG.
+
+:::caution TODO
+
+This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
+
+:::

versioned_docs/version-5.2/accessibility/best-practices/empty-template.md

@@ -0,0 +1,61 @@
+Page Template
+===========
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::tip
+This is an empty template, intended to be used as a starting point for adding new best practices pages. Try to keep it consistent with other pages and fill out all relevant sections; sections marked "optional" can be removed if not relevant.
+:::
+
+## Overview
+
+Definition / explanation of what this page is all about.
+
+### Best Practices
+* Add best practices here. 
+* etc
+
+### Common Mistakes
+* Add common errors here.
+
+## Who is affected?
+People using screen readers need ....
+
+People with cognitive disabilities need ... etc.
+
+Who is impacted most by the accessibility of this element?
+
+## Testing for accessibility
+<Tabs>
+<TabItem value="screenreader" label="With a screenreader">
+
+How does someone test that this is accessible with a screenreader?
+1. Use the screen reader to navigate to ...
+2. Make sure ...
+3. Make sure ...
+4. If ... then it passes. ✅
+5. If ... then it fails. ❌
+
+</TabItem>
+<TabItem value="inspector" label="With web inspector">
+
+How does someone test that this is accessible with web inspector?
+1. Right Click > Inspect ... on the page.
+2. Make sure ...
+3. Make sure ...
+4. If ... then it passes. ✅
+5. If ... then it fails. ❌
+6. If ... then it passes. ✅
+7. If ... then it fails. ❌
+
+</TabItem>
+</Tabs>
+
+## Relevant WCAG Success Criteria
+* Link to the WCAG Success Criteria here. For example:
+* [WCAG criteria 1.3.1 - Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)
+
+## Relevant ATAG Guidelines (optional)
+* Link to the ATAG Guideline(s) here. For example:
+* [Guideline A.3.2: (For the authoring tool user interface) Provide authors with enough time.](https://www.w3.org/TR/ATAG20/#gl_a32)
+

versioned_docs/version-5.2/accessibility/best-practices/index.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 4
+---
+Best Practices for Accessible Design
+===========
+In this section we will explain different aspects to designing with accessibility in mind.
+
+Suggested sub-pages:
+1. Colours
+2. Fonts
+3. Images
+4. Focus Order
+5. (add more)
+
+:::caution TODO
+
+This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
+
+:::