You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+4-188
Original file line number
Diff line number
Diff line change
@@ -4,193 +4,9 @@ This repository should hold all Joomla! documentation needed to develop extensio
4
4
5
5
The Documentation can be found at [https://manual.joomla.org](https://manual.joomla.org)
6
6
7
-
## Contributing to the Joomla Manual
7
+
## Contributing
8
8
9
-
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.
9
+
This manual is self documenting, you can find the documentation at
Updates to the documentation is managed via this repository, so you should initially fork it into your own GitHub account.
12
-
Then you can make changes to the documentation files and submit a pull request to the Joomla manual.
13
-
Ensure that you continue to sync your fork branches with the Joomla manual `main` branch.
14
-
15
-
The documentation uses the [Markdown](https://www.markdownguide.org/) syntax, with additional features which Docusaurus provides.
16
-
17
-
To make documentation changes you'll probably find it easiest to use one of two options:
18
-
1. Install Docusaurus on your own machine, and make changes there
19
-
2. Use [github dev](https://github.com/github/dev) to make the changes on the GitHub server.
20
-
21
-
### Install Docusaurus Locally
22
-
23
-
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.
24
-
25
-
Then change directory to your local git repository and do:
26
-
27
-
```
28
-
$ npm install
29
-
```
30
-
31
-
Once Docusaurus is installed:
32
-
33
-
```
34
-
$ npm run start
35
-
```
36
-
37
-
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
38
-
39
-
```
40
-
$ npm run build
41
-
```
42
-
43
-
This command generates static content into the `build` directory and can be served using any static contents hosting service.
44
-
45
-
### Use github dev
46
-
47
-
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:
48
-
- create a new git branch for your changes
49
-
- create new files and folders, modify and delete existing files, upload files
50
-
- preview files (right-click on the file tab) - this will show interpreted markdown, but will not interpret Docusaurus additions
51
-
- commit and push changes
52
-
- return to GitHub repository (by clicking on GitHub in bottom left, or by replacing github.dev by github.com in the URL)
53
-
54
-
### Preview for pull request
55
-
56
-
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.
57
-
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.
58
-
59
-
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.
60
-
This link will be added to the "checks" section in the pull request as "preview".
61
-
62
-
### Versions
63
-
64
-
The Joomla Manual contains documentation for multiple versions of the Joomla software.
65
-
66
-
The mapping between the versions of the manual in GitHub and the live manual is:
67
-
68
-
| GitHub manual (development) | Live Docusaurus manual |
| /docs | "upcoming" release (shown as /docs/next in the URL) |
71
-
| /versioned_docs/version-m.n | version m.n (under "Current releases") |
72
-
73
-
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:
74
-
- the version m.n of the latest full Joomla release ("latest" release)
75
-
- the version m.n+1 of the next Joomla release ("upcoming" release)
76
-
- the last version (m-1.last) of the Joomla previous major version
77
-
78
-
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.
79
-
80
-
To minimise changes it's recommended that you initially just make changes within the /docs area, and then raise the pull request.
81
-
This allows team members to review the documentation, and for you to fix any issues without having to replicate changes to multiple versions.
82
-
Then when the review process is complete the changes can be replicated to the other versions prior to merging.
83
-
84
-
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`.
85
-
86
-
### Common Build Problems
87
-
88
-
If you use angle brackets or curly brackets in text then always enclose these in backticks, like `<h1>` or `{['a':1, 'b':2]}`.
89
-
90
-
Don't use colons (:) in titles.
91
-
92
-
Don't use `<br>` to force a new line (eg in table text); use `<br/>` instead.
93
-
94
-
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.
95
-
96
-
### Docusaurus Additions
97
-
98
-
You won't see the effect of these when you preview the Markdown text, but you will see them by previewing the Pull Request.
99
-
100
-
[Front Matter](https://docusaurus.io/docs/markdown-features#front-matter) should be used for titles and position in the left-hand sidebar:
101
-
102
-
```
103
-
---
104
-
title: Best Practices
105
-
sidebar-position: 2
106
-
---
107
-
```
108
-
109
-
[Code blocks](https://docusaurus.io/docs/markdown-features/code-blocks) are enclosed in 3 backticks, and can have a [title](https://docusaurus.io/docs/markdown-features/code-blocks#code-title)
110
-
111
-
```php title="hello.php"
112
-
public static function hello()
113
-
{
114
-
echo "Hello!";
115
-
}
116
-
```
117
-
118
-
Line numbering and highlighting of individual lines are also supported.
119
-
120
-
To aid readability of the markdown please leave a blank line before and after code blocks.
We don't use blank lines around content, and we add 2 spaces before the text messages.
124
-
125
-
```
126
-
:::note[Developer Note]
127
-
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
128
-
:::
129
-
130
-
:::note[Joomla Issue]
131
-
For issues that affect the documentation - please link to the issue on the Joomla Issue Tracker
132
-
:::
133
-
134
-
:::tip
135
-
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
136
-
:::
137
-
138
-
:::info
139
-
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
140
-
:::
141
-
142
-
:::warning
143
-
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
144
-
:::
145
-
146
-
:::danger
147
-
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
148
-
:::
149
-
```
150
-
151
-
Please use the following placeholder for unfinished sections of a document.
152
-
153
-
```
154
-
:::note[TODO]
155
-
This section is missing, please use the **Edit this Page** link at the bottom of this page to add this section.
156
-
:::
157
-
```
158
-
159
-
If the page is not completed yet and bigger parts are missing use
160
-
161
-
```
162
-
:::caution[TODO]
163
-
This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
164
-
:::
165
-
```
166
-
167
-
### Diagrams
168
-
169
-
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.
170
-
171
-
Images, code zip files, etc should be held in a folder `_assets` at the point in the documentation where they're used.
172
-
173
-
### Other Recommendations
174
-
175
-
#### Header Levels - just one H1
176
-
177
-
To align with a11y requirements for accessibility, please don't have more than one header level 1:
178
-
179
-
```
180
-
# Just One H1
181
-
```
182
-
183
-
#### API Docs Links
184
-
185
-
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).
186
-
187
-
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.
188
-
189
-
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:
Copy file name to clipboardExpand all lines: about/documentation.md
+65-21
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,26 @@
1
1
This documentation
2
2
==================
3
3
4
-
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.
4
+
This [Joomla development manual](https://manual.joomla.org/docs/) is built using [Docusaurus 3](https://docusaurus.io/),
5
+
a modern static website generator. If you want to contribute to it then this page will help you get started.
5
6
6
-
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.
7
+
Updates to the documentation is managed via the [Joomla manual github repository](https://github.com/joomla/Manual),
8
+
so you should initially fork this repository into your own github account. Then you can make changes to the documentation
9
+
files and submit a pull request to the Joomla manual. Ensure that you continue to sync your fork branches
10
+
with the Joomla manual `main` branch.
7
11
8
12
The documentation uses the [Markdown](https://www.markdownguide.org/) syntax, with additional features which Docusaurus provides.
9
13
10
14
To make documentation changes you'll probably find it easiest to use one of two options:
11
15
1. Install Docusaurus on your own machine, and make changes there
12
-
2. Use [github dev](https://github.com/github/dev) to make the changes on the github server.
16
+
2. Use [github dev](https://github.com/github/dev) to make the changes on the GitHub server.
13
17
14
-
## Install Docusaurus
18
+
## Install Docusaurus Locally
15
19
16
-
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.
20
+
To install Docusaurus on your own machine you should initialise a local git repository and clone the manual from the
21
+
forked copy in your githut repository into this git instance.
17
22
18
-
Then change directory to your local git repository and issue:
23
+
Then change directory to your local git repository and do:
19
24
20
25
```
21
26
$ npm install
@@ -27,51 +32,64 @@ Once Docusaurus is installed:
27
32
$ npm run start
28
33
```
29
34
30
-
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
35
+
This command starts a local development server and opens up a browser window.
36
+
Most changes are reflected live without having to restart the server.
31
37
32
38
```
33
39
$ npm run build
34
40
```
35
41
36
42
This command generates static content into the `build` directory and can be served using any static contents hosting service.
37
43
38
-
## Use github dev
44
+
## Use GitHub dev
45
+
46
+
To use github dev go to your repository and press the "." (dot) key, as described within the
47
+
[github.dev guide](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor). You can then:
39
48
40
-
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:
41
49
- create a new git branch for your changes
42
50
- create new files and folders, modify and delete existing files, upload files
43
51
- preview files (right-click on the file tab) - this will show interpreted markdown, but will not interpret Docusaurus additions
44
52
- commit and push changes
45
-
- return to github repository (by clicking on GitHub in bottom left, or by replacing github.dev by github.com in the URL)
53
+
- return to GitHub repository (by clicking on GitHub in bottom left, or by replacing github.dev by github.com in the URL)
46
54
47
55
## Pull Requests
48
56
49
-
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.
57
+
Once you raise a pull request on the [Joomla manual](https://github.com/joomla/Manual) a test build is run to identify
58
+
any problems with your documentation. If you find a check has failed then click on the Details of the check which failed,
59
+
and you can check the console logs to find the problem.
50
60
51
-
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.
61
+
When the build succeeds you will be able to see the result of your documentation changes by navigating to a
62
+
URL like `http://pr-240.manual.joomlacode.org/docs/`, where you replace 240 with the number of your pull request.
52
63
This link will be added to the "checks" section in the pull request as "preview".
53
64
54
65
## Versions
55
66
56
67
The Joomla Manual contains documentation for multiple versions of the Joomla software.
57
68
58
-
The mapping between the versions of the manual in github and the live manual is:
69
+
The mapping between the versions of the manual in GitHub and the live manual is:
59
70
60
-
|github manual (development) | Live Docusaurus manual |
| /docs | "upcoming" release (shown as /docs/next in the URL) |
63
74
| /versioned_docs/version-m.n | version m.n (under "Current releases") |
64
75
65
-
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:
76
+
If your documentation changes relate to multiple versions of Joomla then you should duplicate these changes into
77
+
multiple versions of Joomla manual. These versions which are updated are currently agreed to be:
78
+
66
79
- the version m.n of the latest full Joomla release ("latest" release)
67
80
- the version m.n+1 of the next Joomla release ("upcoming" release)
68
81
- the last version (m-1.last) of the Joomla previous major version
69
82
70
-
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.
83
+
Other versions may be present within /versioned_docs but are not updated with the changes, even if the documentation is
84
+
true for those Joomla versions.
71
85
72
-
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.
86
+
To minimise changes it's recommended that you initially just make changes within the /docs area, and then raise
87
+
the pull request. This allows team members to review the documentation, and for you to fix any issues without
88
+
having to replicate changes to multiple versions. Then when the review process is complete the changes can be
89
+
replicated to the other versions prior to merging.
73
90
74
-
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`.
91
+
Once the pull request is merged you can delete the branch on your own repository, and sync your `main` branch with the
92
+
updated Joomla manual `main`.
75
93
76
94
## Common Build Problems
77
95
@@ -84,6 +102,7 @@ Don't use `<br>` to force a new line (eg in table text); use `<br/>` instead.
84
102
## Docusaurus Additions
85
103
86
104
[Front Matter](https://docusaurus.io/docs/next/markdown-features#front-matter) should be used for titles and position in the left-hand sidebar:
105
+
87
106
```
88
107
---
89
108
title: Best Practices
@@ -92,6 +111,7 @@ sidebar-position: 2
92
111
```
93
112
94
113
[Code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) are enclosed in 3 backticks, and can have a title:
114
+
95
115
```php title="hello.php"
96
116
public static function hello()
97
117
{
@@ -149,7 +169,9 @@ If the page is not completed yet and bigger parts are missing use
149
169
150
170
## Diagrams
151
171
152
-
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.
172
+
Where possible, use [Mermaid](https://mermaid.live) for creating diagrams for inclusion in the documentation.
173
+
Where Mermaid doesn't provide what you need, then please include the saved diagram from your drawing tool
174
+
in addition to the image file.
153
175
154
176
Images, code zip files, etc should be held in a folder `_assets` at the point in the documentation where they're used.
155
177
@@ -159,4 +181,26 @@ To align with a11y requirements for accessibility, please don't have more than o
159
181
160
182
```
161
183
# Just One H1
162
-
```
184
+
```
185
+
186
+
#### API Docs Links
187
+
188
+
If you link to the Joomla API docs then the URL of the API depends on the version of the manual documentation.
189
+
For example, for Joomla 4.4 documentation the User API is at
0 commit comments