Merge branch 'main' into adapter-removed

Author: Hackwar

.drone.yml

@@ -6,7 +6,7 @@ clone:
 
 steps:
   - name: build
-    image: node:18-bullseye-slim
+    image: node:20-bookworm-slim
     commands:
       - npm install
       - npm run build
@@ -16,26 +16,25 @@ steps:
     depends_on:
       - build
     environment:
-      REMOTE_PRIVATE_KEY:
-        from_secret: REMOTE_PRIVATE_KEY
-      developer_host:
-        from_secret: developer_host
-      sftp_user:
-        from_secret: sftp_user
+      CLOUDFLARE_ACCOUNT_ID:
+        from_secret: CLOUDFLARE_ACCOUNT_ID
+      CLOUDFLARE_API_TOKEN:
+        from_secret: CLOUDFLARE_API_TOKEN
       GITHUB_TOKEN:
         from_secret: github_token
     commands:
-      - mkdir -p ~/.ssh
-      - eval $(ssh-agent -s)
-      - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
-      - echo "$REMOTE_PRIVATE_KEY" > ~/.ssh/id_rsa
-      - chmod 600 ~/.ssh/id_rsa
-      - ssh-add
-      - rclone config create server sftp host $developer_host user $sftp_user port 22
-      - if [ -z "$${DRONE_PULL_REQUEST}" ]; then export TARGET=public_html; else export TARGET=wildcard.manual.joomlacode.org/sites/pr-$${DRONE_PULL_REQUEST}; fi
-      - rclone -v sync build server:$TARGET
+      - echo "Prepare Workaround for trailing slashes bug https://github.com/facebook/docusaurus/issues/6282 on Cloudflare Pages"
+      - >
+        for f in build/assets/files/*; do
+          [ -f "$f" ] || continue;
+          filename=$(basename "$f");
+          echo "/assets/files/$filename/ /assets/files/$filename 301";
+        done > build/_redirects
+      - node_modules/.bin/wrangler pages deploy ./build --commit-dirty=true --project-name manual --branch="$${DRONE_SOURCE_BRANCH}" | tee /tmp/output.log
+      - export PREVIEW_UNIQUE_URL=`grep Deployment /tmp/output.log | awk '{ print $9 }'`
+      - export PREVIEW_URL=`grep "Deployment alias URL" /tmp/output.log | awk '{ print $5 }'`
       - chmod +x test.sh
-      - if [ ! -z "$${DRONE_PULL_REQUEST}" ]; then /bin/add_github_status.sh "Preview" "Generated preview for this pull request" "http://pr-$${DRONE_PULL_REQUEST}.manual.joomlacode.org" ; fi;
+      - if [ ! -z "$${DRONE_PULL_REQUEST}" ]; then /bin/add_github_status.sh "Preview" "Generated preview for this pull request" "$${PREVIEW_URL}" ; fi;
     when:
       branch:
         main
@@ -47,6 +46,6 @@ steps:
 
 ---
 kind: signature
-hmac: 3d1303abd175ffda3aec141c6ea71d541f50f3c3e0752a68330fde5560386a58
+hmac: fd23674d231f74d54696c996b77acceb14a19d2d5d800c7050bdaee2f9be5b4b
 
 ...

LICENSE

@@ -0,0 +1,31 @@
+JEDL
+====
+
+Below is a license granting you rights to use, modify and distribute documentation associated with the Joomla! project. It is designed to foster wide electronic distribution of Joomla! documentation while ensuring that any material added to the documentation by you or others can be taken up and made part of the authoritative documentation distributed by the Joomla! project.
+The license that appears below is not the only way to get permission to use Joomla! documentation. If you want to publish Joomla! documentation in a manner not permitted by this license (i.e. in a printed book), please contact the Joomla! project.
+Although the license is called the "Joomla! Electronic Documentation License", you are encouraged to use it for works not associated with Joomla! and for things other than documentation.
+The license itself is copyright 2007 Open Source Matters, Inc., and you have permission to make verbatim copies of it.
+
+
+Joomla! Electronic Documentation License v 1.0
+==============================================
+
+## Definitions
+
+To "Propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except displaying or modifying a private copy.
+The "Work" is any copyrightable material licensed under the terms of this license or any material based on such material. The "Author" means all the people or entities who have the legal right to grant permission to Propagate the Work or parts of the Work. Each licensee is addressed as "you".
+"Electronic Media" means any device, medium or technology used to store, record, display, transmit or modify electronic information, including websites, compact discs, digital video discs, hard disks, magnetic media, and computer networks. "Electronic Media" does not include, for example, books printed on paper.
+"Grantback License" means a non-exclusive, perpetual, worldwide, royalty-free license to Propagate the Work in any medium and by any means.
+"Copyleft License" means a license to Propagate the Work under the terms of this license or any future version of the Joomla Electronic Documentation License published by Open Source Matters, Incorporated.
+The "Source Form" of a work means the preferred form of the Work for making modifications to it. For text works, this could be plain ASCII text format.
+
+## Conditional Permissions
+
+If you grant a Grantback License to the Author and a Copyleft License to anybody who comes into possession of the Work, you may Propagate the Work via Electronic Media for any purpose, including commercial purposes.
+You must make available at no charge, to anybody to whom you distribute the Work, a version of the Work in Source Form. Such availability must be via either (1) the same means and method with which you distribute the Work or (2) simple download over the internet. You may not condition providing the Source Form of the Work on anything other than acceptance of this license.
+You must provide a copy of this license, notice that it applies to the Work, and information needed to acquire the Source Form to anybody to whom you distribute the Work.
+You must preserve the Author's copyright notices in the Work and display them as prominently as you display your own.
+## Reservations of Rights
+
+Nothing in this license grants you or anybody else any right to Propagate the Work in any medium or through any means other than Electronic Media.
+Nothing in this license grants you or anybody else any right to do anything that requires permission under trademark law. Specifically, nothing in this license grants you permission to represent that the Work is "official" or in any way endorsed or sanctioned by the Authors.

README.md

@@ -4,191 +4,9 @@ This repository should hold all Joomla! documentation needed to develop extensio
 
 The Documentation can be found at [https://manual.joomla.org](https://manual.joomla.org)
 
-## Contributing to the Joomla Manual
+## Contributing
 
-This manual 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.
+This manual is self documenting, you can find the documentation at
+[manual.joomla.org/about](https://manual.joomla.org/about/).
 
-Updates to the documentation is managed via this repository, so you should initially fork it 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 Locally
-
-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 do:
-
-```
-$ 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)
-
-### Preview for pull request
-
-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. 
-
-Don't use subdirectory names which match somewhat the parent directory name. For example, avoid `./install-update/install/`, as this can cause docusaurus to report broken links.
-
-### Docusaurus Additions
-
-You won't see the effect of these when you preview the Markdown text, but you will see them by previewing the Pull Request. 
-
-[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
-
-#### Header Levels - just one H1
-
-To align with a11y requirements for accessibility, please don't have more than one header level 1:
-
-```
-# Just One H1
-```
-
-#### API Docs Links
-
-If you link to the Joomla API docs then the URL of the API depends on the version of the manual documentation. For example, for Joomla 4.4 documentation the User API is at [https://api.joomla.org/cms-4/classes/Joomla-CMS-User-User.html](https://api.joomla.org/cms-4/classes/Joomla-CMS-User-User.html), but for Joomla 5.x documentation it is [https://api.joomla.org/cms-5/classes/Joomla-CMS-User-User.html](https://api.joomla.org/cms-5/classes/Joomla-CMS-User-User.html).
-
-This is similar for Framework classes, eg [https://api.joomla.org/framework-3/classes/Joomla-Registry-Registry.html](https://api.joomla.org/framework-3/classes/Joomla-Registry-Registry.html), which is also dependent upon the documentation version.
-
-As this creates a maintainability issue a plugin has been developed which automatically selects the appropriate API docs version, and you should use this plugin by specifying API docs links like the following examples:
-
-```
-cms-api://classes/Joomla-CMS-User-User.html
-framework-api://classes/Joomla-Registry-Registry.html
-```
-
-The plugin will replace `cms-api://` or `framework-api://` with the correct URL section.
+The markdown files for the this documentation are in the `about` folder.

about/contributing.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 3
+---
+
+Contributing
+============
+
+How to contribute to the Joomla! documentation. First it's important to understand how to write documentation,
+which is handeled in the [Writing documentation](./writing.md) page.
+
+## Install Docusaurus Locally
+
+To install Docusaurus on your own machine you should initialise a local git repository and clone the manual from the
+forked copy in your GitHub repository into this git instance.
+
+Then change directory to your local git repository and do:
+
+```bash
+npm install
+```
+
+Once Docusaurus is installed:
+
+```bash
+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.
+
+```bash
+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 `https://branchname.manual-bku.pages.dev/`, where you replace branchname with the branch of your pull request.
+This link will be added to the "checks" section in the pull request as "preview".