georgringer/doc

Project documentation for editors & integratiors, visible in the TYPO3 backend

TYPO3 Extension doc

This extension adds an option to the Help menu called Project Documentation, that lets you deliver documentation about your project from within TYPO3 CMS backend.

The extension also ships with a widget for the TYPO3 Dashboad extension to give you quick access to your project documentation.

The documentation is based on Markdown. This makes it easy to write documentation while you're building a custom extension, or afterward. You could include descriptions of content elements, release notes, instructions for raising issues or anything else that needs to be documented.

The JS library docsify transforms markdown files into beautiful HTML content.

Setup the extension

Download the extension. Use one of the following options:

1. Composer: composer req georgringer/doc
2. TER: Download extension from TER
3. TYPO3 Backend: Download extension in Extension Manager

Configuration

Switch to Install Tool/Settings and customize the global configuration. As seen in the screenshot below, the following configuration options are available:

• Documentation Root Path: Define the path to the Markdown files
• Documentation Name: Documentation name as it appears in the sidebar
• Dark mode: Enable the dark mode

Write the documentation

Without any documentation, this extension is not useful at all :)

Check out the sample documentation included in this extension which you can use as a guide EXT:doc/Resources/Private/ExampleDocs. See also the Markdown Cheatsheet as there are some nice features available.

When you create your own documentation make sure to put the folder with your markdown files in Resources/Private. Otherwise your markdown files may be publicly accessible.

doc's Issues

EXT:doc and composer-installer v4

I see with typo3/cms-composer-installers v4 only a blank page when calling the documentation.
How do I have to specify the path to the documentation (documentationRootPath) correctly?

TYPO3 11.5.26
PHP 8.1
EXT:doc 1.1.1

Feature request: Provide functionality to link to documentation (instead of using the Markdown)

I currently have the feature request to add a link to our documentation for editors to the Help menu (?) in the topbar.

(I think the possibility to use Markdown is quite cool and we might consider it, but for now we already have several pages with information / documentation / styleguide for editors).

I realize, this extension does something completely different (show Markdown). I need exactly the same functionality, but not with the Markdown.

How can this be implemented

• add configuration for entering the target URL (preferably as URL or typolink so you can link to external documentation or documentation within the site). In this case, that would be used instead of the Markdown
• the rest would stay the same, but a link to the (external or internal) page or file will be used instead of showing the markdown

Inlcude md from other extension ?

It is possible to start a README from a different ext. I have a link in the sitebar.md [other Ext](../../../other_ext/README.md) but unfortunately only a 404 is output.

is there a way to include them directly?

What is the correct path to the doc files in TYPO3 12 with composer mode ?

My sitepackage extension is in
/src/ext/mysitepackage/
and the documentation files are in
/src/ext/mysitepackage/Resources/Private/Docs

Link to doc-Home incorrect

The main-Link to doc-Home open the complete TYPO3 backend within the iFrame.
The markup of the link:
<a class="app-name-link" data-nosearch="" href="/typo3/module/help/doc">Documentation</a>
should be:
<a class="app-name-link" data-nosearch="" href="/typo3/module/help/doc" target="_top">Documentation</a>

TYPO3 11.5.24
PHP 8.1
EXT:doc 1.1.1

Protect markdown files from public access

Currently it is necessary for Docsify to work that the markdown files are placed in a subfolder of Resources/Public/ or a subfolder of fileadmin. This makes them publicly accessible even though you need to guess the path.

Since project documentation can sometimes contain confidential information I'd love to have a solution where I can put the markdown files in Resources/Private/.