Skip to content

Commit 45a9f62

Browse files
georgringergeorgringer
committed
[TASK] Initial version
0 parents  commit 45a9f62

28 files changed

+2483
-0
lines changed

‎Classes/Controller/DocModuleController.php

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<?php
2+
declare(strict_types=1);
3+
4+
namespace GeorgRinger\Doc\Controller;
5+
6+
use Psr\Http\Message\ResponseInterface;
7+
use Psr\Http\Message\ServerRequestInterface;
8+
use TYPO3\CMS\Core\Http\HtmlResponse;
9+
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
10+
use TYPO3\CMS\Core\Utility\GeneralUtility;
11+
use TYPO3\CMS\Core\Utility\PathUtility;
12+
use TYPO3\CMS\Fluid\View\StandaloneView;
13+
14+
15+
class DocModuleController
16+
{
17+
18+
19+
/**
20+
* @param ServerRequestInterface $request the current request
21+
* @return ResponseInterface the response with the content
22+
*/
23+
public function mainAction(ServerRequestInterface $request): ResponseInterface
24+
{
25+
$view = $this->getStandaloneView();
26+
return new HtmlResponse($view->render());
27+
}
28+
29+
private function getStandaloneView(): StandaloneView
30+
{
31+
$settings = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Configuration\ExtensionConfiguration::class)->get('doc');
32+
$docRootPath = $settings['documentationRootPath'] ?? '';
33+
if (!$docRootPath) {
34+
throw new \UnexpectedValueException('Documentation root path not set', 1609235458);
35+
}
36+
37+
$publicResourcesPath = '../../' . PathUtility::getRelativePathTo(ExtensionManagementUtility::extPath('doc')) . 'Resources/Public/docsify/';
38+
39+
40+
$templatePathAndFilename = GeneralUtility::getFileAbsFileName('EXT:doc/Resources/Private/Templates/Module.html');
41+
$view = GeneralUtility::makeInstance(StandaloneView::class);
42+
$view->setTemplatePathAndFilename($templatePathAndFilename);
43+
$view->assignMultiple([
44+
'path' => $publicResourcesPath,
45+
'docRoothPath' => $docRootPath,
46+
'darkMode' => $settings['darkMode'] ?? false
47+
]);
48+
return $view;
49+
}
50+
}

‎LICENSE.txt

+345
Large diffs are not rendered by default.

‎Readme.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# TYPO3 Extension `doc`
2+
3+
This extensions provides a new module below *Help* called *Project Documentation* to deliver your documentation to your clients and also for yourself.
4+
5+
It is based on Markdown which makes it easy to write it all down during or after creating custom extensions, content elements, release notes or anything which needs to be documented and should not be forgotten.
6+
7+
The JS library [docsify](https://docsify.js.org/) transforms **markdown files** into beautiful HTML content.
8+
9+
![Demo](Resources/Public/Images/Demo.png)
10+
11+
## Setup the extension
12+
13+
Download the extension. Use one of the following options:
14+
15+
1. *Composer*: `composer req georgringer/doc`
16+
2. *TER*: Download extension from [TER](https://extensions.typo3.org/extension/doc/)
17+
3. *TYPO3 Backend*: Download extension in *Extension Manager*
18+
19+
### Configuration
20+
21+
Switch to **Install Tool/Settings** and customize the global configuration.
22+
As seen in the screenshot below, the following configuration options are available:
23+
24+
* `Documentation Root Path`: Define the path to the Markdown files
25+
* `Dark mode`: Enable the dark mode
26+
27+
![Extension Configuration](Resources/Public/ExampleDocs/_img/ExtensionConfiguration.png)
28+
29+
## Write the documentation
30+
31+
> Without any documentation, this extension is not useful at all :)
32+
33+
Checkout the sample documentation inside `EXT:doc/Resources/Public/ExampleDocs`
34+
and also the **Markdown Cheatsheet** as there are some nice features available.

‎Resources/Private/Language/locallang_mod.xlf

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<xliff version="1.0" xmlns:t3="http://typo3.org/schemas/xliff">
3+
<file t3:id="1609228987" source-language="en" datatype="plaintext" original="EXT:doc/Resources/Private/Language/locallang_mod.xlf" product-name="doc">
4+
<header/>
5+
<body>
6+
<trans-unit id="mlang_labels_tablabel" resname="mlang_labels_tablabel">
7+
<source>Documentation</source>
8+
</trans-unit>
9+
<trans-unit id="mlang_labels_tabdescr" resname="mlang_labels_tabdescr">
10+
<source>This module shows you the project documentation</source>
11+
</trans-unit>
12+
<trans-unit id="mlang_tabs_tab" resname="mlang_tabs_tab">
13+
<source>Project documentation</source>
14+
</trans-unit>
15+
</body>
16+
</file>
17+
</xliff>

‎Resources/Private/Templates/Module.html

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>Documentation</title>
6+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
7+
<meta name="description" content="Description">
8+
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
9+
<link rel="stylesheet" href="{path}vue.css">
10+
<f:if condition="{darkMode}">
11+
<link rel="stylesheet" href="{path}dark.css">
12+
</f:if>
13+
<link rel="stylesheet" href="{path}typo3.css">
14+
</head>
15+
<body>
16+
<div id="app"></div>
17+
<script>
18+
var docRootPath = '{docRoothPath}';
19+
window.$docsify = {
20+
name: 'Documentation',
21+
themeColor: '#1e46b9',
22+
basePath: docRootPath,
23+
homepage: 'Home.md',
24+
loadSidebar: true,
25+
loadNavbar: false,
26+
subMaxLevel: 0,
27+
autoHeader: false
28+
}
29+
</script>
30+
<script src="{path}docsify_4.11.6.js"></script>
31+
<script src="{path}prism-php.min.js"></script>
32+
</body>
33+
</html>

‎Resources/Public/ExampleDocs/ContentElements/Gallery.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Gallery
2+
3+
> Sed scelerisque risus id metus condimentum, at volutpat nibh tincidunt.
4+
> Quisque in tincidunt nunc, sed fringilla tellus.
5+
> Nunc risus urna, vehicula id suscipit id, mattis non eros.
6+
7+
## Description
8+
9+
Fusce ex eros, sollicitudin vitae diam in, aliquet tincidunt magna.
10+
Curabitur interdum urna sed feugiat dapibus. Vestibulum a magna a lectus feugiat
11+
facilisis nec et urna. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
12+
Maecenas eu mauris eu velit semper lobortis. Nam in auctor lectus. Nullam ut efficitur eros,
13+
vitae volutpat tellus. Nulla nec luctus enim.
14+
15+
Suspendisse fermentum massa at magna faucibus, ut maximus velit porttitor.
16+
Nulla commodo id mauris eget interdum. Integer hendrerit luctus neque,
17+
at accumsan nisl ultrices id. Mauris egestas dapibus pellentesque.
18+
Suspendisse placerat leo ligula, eu posuere tortor elementum et.
19+
Sed ultrices, sem nec tristique rutrum, lorem enim bibendum elit,
20+
sit amet egestas risus risus a nibh. Suspendisse aliquet id lacus eu commodo.
21+
Fusce faucibus iaculis purus sed auctor.
22+
23+
## Rendering
24+
25+
```html
26+
<div class="card">
27+
<img
28+
src="https://mdbootstrap.com/img/new/standard/nature/184.jpg"
29+
class="card-img-top"
30+
alt="..."
31+
/>
32+
<div class="card-body">
33+
<h5 class="card-title">Card title</h5>
34+
<p class="card-text">
35+
Some quick example text to build on the card title and make up the bulk of the
36+
card's content.
37+
</p>
38+
<a href="#!" class="btn btn-primary">Button</a>
39+
</div>
40+
</div>
41+
```

‎Resources/Public/ExampleDocs/ContentElements/Teaser.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Teaser
2+
3+
> Etiam bibendum sem malesuada, viverra turpis eu, iaculis nibh. Quisque sed rhoncus tellus,
4+
> vitae posuere magna. Sed vehicula eget felis at feugiat.
5+
6+
## Description
7+
8+
Mauris condimentum quam nec ipsum ullamcorper, tincidunt gravida metus mattis.
9+
Donec tempus enim posuere consectetur lacinia. Cras convallis viverra nisl.
10+
Maecenas consequat, risus ut feugiat elementum, sem orci vehicula elit, ac lacinia quam magna vitae urna.
11+
Nullam eget odio porttitor, sagittis ligula vitae, sagittis metus.
12+
13+
Nam sit amet dolor fringilla lorem tincidunt aliquam.
14+
Quisque varius vulputate augue, tristique tempus metus sollicitudin quis.
15+
Phasellus ullamcorper felis scelerisque, laoreet felis eget, viverra dolor.
16+
Quisque blandit congue sem, a convallis augue aliquet ac.
17+
Maecenas tempor ligula id dui imperdiet malesuada. Ut id volutpat purus.
18+
19+
## Rendering
20+
21+
```html
22+
<ul class="list-group">
23+
<li class="list-group-item active" aria-current="true">Cras justo odio</li>
24+
<li class="list-group-item">Dapibus ac facilisis in</li>
25+
<li class="list-group-item">Morbi leo risus</li>
26+
<li class="list-group-item">Porta ac consectetur ac</li>
27+
<li class="list-group-item">Vestibulum at eros</li>
28+
</ul>
29+
```

‎Resources/Public/ExampleDocs/Home.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Project documentation
2+
3+
This module documents all **content elements**, **plugins** and any other important information you need to use this website.
4+
5+
> By using **Markdown** it is easy to create and maintain the documentation
6+
> while developing the features using the same IDE and code base (e.g. GIT).
7+
>
8+
> Documentation is not only important for editors to know how something should be done but also
9+
> for the creator.
10+
11+
## Further questions?
12+
13+
If you got additional questions, please contact:
14+
15+
1. Project manager Jane Doe
16+
2. Use the [ticket system](https://tickets.com) and add the following details
17+
* How to reproduce
18+
* Which browser and Operating System
19+
* On which page (include the page id)
20+
3. Don't use slack ;)

‎Resources/Public/ExampleDocs/Plugins/News.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# News extension
2+
3+
> The news extension can be found e.g. on [github.com/georgringer/news](https://github.com/georgringer/news).
4+
5+
## Configuration
6+
7+
Aliquam et odio eleifend, rhoncus mi vitae, semper lorem.
8+
Nam pulvinar, turpis finibus convallis sollicitudin,
9+
ligula metus auctor ipsum, ac pretium arcu neque vitae ligula.
10+
11+
## Available templates
12+
13+
Sed ullamcorper urna sit amet nulla accumsan, quis consectetur tortor lobortis.
14+
Nulla non quam nec mauris facilisis congue.
15+
16+
- One
17+
- Two
18+
- Three
19+
20+
## SEO
21+
22+
!> Don't forget the bots!
23+
24+
Vestibulum eros ipsum, consequat sed arcu gravida, mollis tempor sapien.
25+
Donec libero tellus, finibus tempor facilisis eu, convallis non metus.
26+
Nullam a volutpat magna, eu lacinia ligula. Sed nec erat id diam ornare sagittis eget euismod purus.
27+
Vivamus in justo id lorem mollis commodo a et diam. Suspendisse elit turpis, venenatis in mi facilisis,
28+
hendrerit euismod erat. Aenean sed commodo ipsum, eget vestibulum metus.

‎Resources/Public/ExampleDocs/Setup/Extension.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Using this extension
2+
3+
Using this extension is fairly easy.
4+
5+
## Write the documentation
6+
7+
?> Without any documentation, this extension is not useful at all :)
8+
9+
Checkout the sample documentation inside `EXT:doc/Resources/Public/ExampleDocs`
10+
and also the [Markdown Cheatsheet](Setup/Markdown.md) as there are some nice features available.
11+
12+
The following 3 special files are important:
13+
14+
- `Home.md`: This file is uses as homepage.
15+
- `_sidebar.md`: Sidebar on the left. Put all the important links here
16+
- `_navbar.md`: Navigation on the top right
17+
18+
19+
## Setup the extension
20+
21+
Download the extension. Use one of the following options:
22+
23+
1. *Composer*: `composer req georgringer/doc`
24+
2. *TER*: Download extension from [TER](https://extensions.typo3.org/extension/doc/)
25+
3. *TYPO3 Backend*: Download extension in *Extension Manager*
26+
27+
### Configuration
28+
29+
Switch to **Install Tool/Settings** and customize the global configuration.
30+
As seen in the screenshot below, the following configuration options are available:
31+
32+
* `Documentation Root Path`: Define the path to the Markdown files
33+
* `Dark mode`: Enable the dark mode
34+
35+
![Extension Configuration](../_img/ExtensionConfiguration.png ':size=50%')

‎Resources/Public/ExampleDocs/Setup/Markdown.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Markdown CheatSheet
2+
3+
Writing Markdown is fairly simple. Checkout this [guide](https://www.markdownguide.org/basic-syntax/)
4+
for the basic syntax including stuff like:
5+
6+
- headings
7+
- paragraphs
8+
- lists
9+
- code
10+
- links
11+
- images
12+
13+
## Docsify helpers
14+
15+
This extension uses [docsifiy](https://docsify.js.org/#/helpers) for converting Markdown to HTML on the fly
16+
and there are some nice helpers included which extend the Markdown ruleset.
17+
18+
### Important content
19+
20+
!> Never save passwords on GitHub
21+
22+
```markdown
23+
!> Never save passwords on GitHub
24+
```
25+
26+
--------
27+
28+
?> Clearing the **cache** can help!
29+
30+
```markdown
31+
?> Clearing the **cache** can help!
32+
```
33+
34+
### Tasks
35+
36+
- [x] Finished task
37+
- [ ] Something todo
38+
- [ ] Something else
39+
40+
```markdown
41+
- [x] Finished task
42+
- [ ] Something todo
43+
- [ ] Something else
44+
```
45+
46+
### Image resizing
47+
The image instruction can receive reseizing information `':size=WIDTHxHEIGHT'`.
48+
![logo](../_img/typo3.png)
49+
![logo](../_img/typo3.png ':size=50x50')
50+
![logo](../_img/typo3.png ':size=100')
51+
![logo](../_img/typo3.png ':size=10%')
52+
53+
```markdown
54+
![logo](../_img/typo3.png ':size=50x50')
55+
![logo](../_img/typo3.png ':size=100')
56+
![logo](../_img/typo3.png ':size=10%')
57+
```
58+
59+
### Using raw HTML
60+
61+
You need to insert a space between the html and markdown content.
62+
63+
<details>
64+
<summary>Self-assessment (Click to expand)</summary>
65+
66+
- Abc
67+
- Abc
68+
69+
</details>
70+
71+
72+
```markdown
73+
<details>
74+
<summary>Self-assessment (Click to expand)</summary>
75+
76+
- Abc
77+
- Abc
78+
79+
</details>
80+
```
81+
82+
!> Be aware that raw HTML does also mean JavaScript which can quickly lead to security issues!!

‎Resources/Public/ExampleDocs/_img/ExtensionConfiguration.png

15.7 KB
Loading

‎Resources/Public/ExampleDocs/_img/typo3.png

3.37 KB
Loading

‎Resources/Public/ExampleDocs/_navbar.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
* [Start](/)
2+
* [↗️ Extension on GitHub](https://github.com/georgringer/doc)

‎Resources/Public/ExampleDocs/_sidebar.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
* Contentelements
2+
* [Teaser](ContentElements/Teaser)
3+
* [Gallery](ContentElements/Gallery)
4+
* Plugins
5+
* [News](Plugins/News)
6+
-----
7+
* **Setup**
8+
* **[Using this extension](Setup/Extension)**
9+
* **[Markdown](Setup/Markdown)**

‎Resources/Public/Icons/Extension.svg

+6
Loading

0 commit comments

Comments
 (0)