Skip to content

Commit 3dc8731

Browse files
HLeithnerHLeithner
committed
Split about use documentation and add browser component
1 parent 301f52c commit 3dc8731

File tree

14 files changed

+536
-194
lines changed

14 files changed

+536
-194
lines changed

‎about/contributing.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
Contributing
6+
============
7+
8+
How to contribute to the Joomla! documentation. First it's important to understand how to write documentation,
9+
which is handeled in the [Writing documentation](./writing.md) page.
10+
11+
## Install Docusaurus Locally
12+
13+
To install Docusaurus on your own machine you should initialise a local git repository and clone the manual from the
14+
forked copy in your GitHub repository into this git instance.
15+
16+
Then change directory to your local git repository and do:
17+
18+
```bash
19+
npm install
20+
```
21+
22+
Once Docusaurus is installed:
23+
24+
```bash
25+
npm run start
26+
```
27+
28+
This command starts a local development server and opens up a browser window.
29+
Most changes are reflected live without having to restart the server.
30+
31+
```bash
32+
npm run build
33+
```
34+
35+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
36+
37+
## Use GitHub dev
38+
39+
To use GitHub dev go to your repository and press the "." (dot) key, as described within the
40+
[github.dev guide](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor). You can then:
41+
42+
- create a new git branch for your changes
43+
- create new files and folders, modify and delete existing files, upload files
44+
- preview files (right-click on the file tab) - this will show interpreted markdown, but will not interpret Docusaurus additions
45+
- commit and push changes
46+
- return to GitHub repository (by clicking on GitHub in bottom left, or by replacing github.dev by github.com in the URL)
47+
48+
## Pull Requests
49+
50+
Once you raise a pull request on the [Joomla manual](https://github.com/joomla/Manual) a test build is run to identify
51+
any problems with your documentation. If you find a check has failed then click on the Details of the check which failed,
52+
and you can check the console logs to find the problem.
53+
54+
When the build succeeds you will be able to see the result of your documentation changes by navigating to a
55+
URL like `https://branchname.manual-bku.pages.dev/`, where you replace branchname with the branch of your pull request.
56+
This link will be added to the "checks" section in the pull request as "preview".

‎about/features/admonition.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
import BrowserWindow from '@site/src/components/BrowserWindow';
2+
3+
# Admonition
4+
5+
[Admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions)
6+
We don't use blank lines around content, and we add 2 spaces before the text messages.
7+
8+
```
9+
:::note[Developer Note]
10+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
11+
:::
12+
13+
:::note[Joomla Issue]
14+
For issues that affect the documentation - please link to the issue on the Joomla Issue Tracker
15+
:::
16+
17+
:::tip
18+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
19+
:::
20+
21+
:::info
22+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
23+
:::
24+
25+
:::warning
26+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
27+
:::
28+
29+
:::danger
30+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
31+
:::
32+
```
33+
34+
```mdx-code-block
35+
<BrowserWindow url="https://manual.joomla.org">
36+
37+
:::note[Developer Note]
38+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
39+
:::
40+
41+
:::note[Joomla Issue]
42+
For issues that affect the documentation - please link to the issue on the Joomla Issue Tracker
43+
:::
44+
45+
:::tip
46+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
47+
:::
48+
49+
:::info
50+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
51+
:::
52+
53+
:::warning
54+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
55+
:::
56+
57+
:::danger
58+
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
59+
:::
60+
61+
</BrowserWindow>
62+
```

‎about/features/asset.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Asset
2+
3+
Images, code zip files, etc should be held in a folder `_assets` at the point in the documentation where they're used.

‎about/features/browser.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
import BrowserWindow from '@site/src/components/BrowserWindow';
2+
import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow';
3+
4+
# Browser
5+
6+
## BrowserWindow
7+
8+
The `BrowserWindow` component is used to display a browser window with a URL.
9+
Default url is https://www.joomla.org, a manual feature should be shown use the https://manual.joomla.org url.
10+
11+
```md
12+
---
13+
title: Example metadata
14+
---
15+
16+
import BrowserWindow from '@site/src/components/BrowserWindow';
17+
18+
​```mdx-code-block
19+
<BrowserWindow url="https://manual.joomla.org">
20+
Example Text, this could be markdown.
21+
</BrowserWindow>
22+
​```
23+
```
24+
25+
Example:
26+
27+
```mdx-code-block
28+
<BrowserWindow url="https://manual.joomla.org">
29+
Example Text, this could be markdown.
30+
</BrowserWindow>
31+
```
32+
33+
34+
## IframeWindow
35+
36+
The `IframeWindow` component is used to display a browser window with an iframe.
37+
38+
```md
39+
---
40+
title: Example metadata
41+
---
42+
43+
import BrowserWindow from '@site/src/components/BrowserWindow/IframeWindow';
44+
45+
​```mdx-code-block
46+
<IframeWindow url="https://manual.joomla.org">
47+
​```
48+
```
49+
50+
Example:
51+
52+
```mdx-code-block
53+
<IframeWindow url="https://manual.joomla.org">
54+
</IframeWindow>
55+
```

‎about/features/code.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Code Blocks
2+
3+
[Code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) are enclosed in 3 backticks, and can have a title:
4+
5+
```php title="hello.php"
6+
public static function hello()
7+
{
8+
echo "Hello!";
9+
}
10+
```
11+
12+
Line numbering and highlighting of individual lines are also supported.
13+
14+
To aid readability of the markdown please leave a blank line before and after code blocks.

‎about/features/diagram.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Diagram
2+
3+
Where possible, use [Mermaid](https://mermaid.live) for creating diagrams for inclusion in the documentation.
4+
Where Mermaid doesn't provide what you need, then please include the saved diagram from your drawing tool
5+
in addition to the image file.

‎about/features/index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
Features
6+
========
7+
8+
The [Joomla development manual](https://manual.joomla.org/docs/) uses a couple of Docusaurus features to make it easier to read.
9+
10+
There are 2 types of syntax to be aware of:
11+
12+
1. **Markdown** - this is the standard syntax for writing documentation, and is used for most of the content.
13+
2. **MDX** - this is a combination of Markdown and JSX, and is used for the more complex components.
14+
15+
## Markdown
16+
17+
This is common Markdown syntax, with some extra features added by Docusaurus.
18+
19+
## MDX Components
20+
21+
In docusaurus we have a number of components that are used to display content. In addition to the standard docusaurus
22+
components we provide addional components in the Joomla! documentation.
23+
24+
Components needs to be imported at the top of the file after the metadata object, and then can be used within the markdown content.
25+
26+
Example:
27+
28+
```md
29+
---
30+
title: Example metadata
31+
---
32+
33+
import BrowserWindow from '@site/src/components/BrowserWindow';
34+
35+
​```mdx-code-block
36+
<BrowserWindow>
37+
A text with a browser window.
38+
</BrowserWindow>
39+
​```
40+
```

‎about/features/metadata.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Metadata
2+
3+
[Front Matter](https://docusaurus.io/docs/next/markdown-features#front-matter) should be used for titles and position in the left-hand sidebar:
4+
5+
```
6+
---
7+
title: Best Practices
8+
sidebar-position: 2
9+
---
10+
```

0 commit comments

Comments
 (0)