Joomla Documenter Manual

Preface

This article arose from a presentation at the Joomla! User Group London on 20 May 2025. For preparation I made a series of screen shots with minimal notes, which are expanded a little here.

In the beginning...

I began contributing to Joomla! documentation in 2020 when I revised all of the Help screens for Joomla 4 (and later 5). In the process I became very familiar with the MediaWiki installation that powers docs.joomla.org. This is the Home page:

• I am a beginner: which link first?
• Beginners: Quite long and mostly links to other places
• Beginners Tutorials: Links to resources, many out of date
• Tasks: Where to start?

My Lists

Being unable to easily re-find articles after a first visit I started making categorised lists:

There are category lists for this sort of thing but they include all language versions and are no more helpful than the Home page. So my lists are a personally selected list of useful articles.

Translation markup:

MediaWiki uses a version of Markdown, which is supposed to make text clear and simple. However it provides for translation markup, which makes an edit page cluttered and difficult to use for the inexperienced:

Conclusion

Something better was needed! I decided to build a custom Joomla! component, something easy to use, easy to update and easy to translate: Jdocmanual.

Inspiration

I took inspiration from other software documentation projects that typically have an Index of Articles to the left, Article text in the centre and article Contents to the right. Some examples:

Compare with 5.1.3: the formerly collapsible index is now expanded.

Docusaurus

I was not aware of Docusaurus at the outset. The core developers had started using it at the same time as I started Jdocmanual.

I tried Docusaurus and was not satisfied with it. Amongst other problems there was no obvious provision for translation other than vague references to Crowdin, which I tried and found wanting.

Jdocmanual

Jdocmanual evolved from the initial idea and went through several major changes of approach. This is the current incarnation:

Index of Articles to the left, Article content in the centre and article Contents to the right, just like the doctor ordered. The initial idea was to use Jdocmanual as an Administrator component for backend users. The frontend usage came later as an option.

The Manuals

The original documentation attempted to separate users into Beginners, Administrators, Developers and Core Developers. Some have suggested there should be other groups such as Template Developers and Site Builders. I chose to organise articles by the following groups:

• The Joomla! User Manual contains articles requiring no knowledge of HTML, CSS or JavaScript.
• The Joomla! Help Screens are the pages delivered in response to selection of an Administrator Toolbar Help button. They are defined in the code.
• The Joomla! Developer Manual contains articles requiring knowledge of HTML, CSS or JavaScript. This initially used the same MediaWiki sources as manual.joomla.org (Docusaurus) but my intention is to move the articles to...
• The Joomla! Programmers Documentation This is an import of the docs pages from manual.joomla.org that allows Jdocmanual to keep everything together.
• The Joomla Documenter Manual contains articles on how to create and maintain documentation.

The Languages

The User, Help and Developer manuals have all been translated into a selection of languages using AI (more on that later). The Page language and the Index language can be separately selected:

If an article is not available in the selected language the English version is delivered instead.

Search

The search feature is very helpful for answering Forum questions. I often stumble upon articles I had forgotten existed!

Help Screens

Joomla! Help screens follow a common pattern described in the Documenter articles. They use a lot of chunks, some from Joomla 3 documentation, and many links to here, there and everywhere. This is difficult to maintain and translate! I decided the Help pages needed to be simplified for delivery on another platform. So I made sections such Toolbar and List descriptions into Common Elements so that individual Help pages could focus on the important page elements.

Jdocmanual Data

The source text for Jdocmanual is stored in files in GitHub flavoured Markdown. Jdocmanual contains tools to edit and otherwise manage source content - more on that under Stashes later. However, I now prefer to use VSCode or VSCodium:

• Markdown: simple, clean text with a few markup symbols.
• The top HTML comment contains a link key and the real title.
• The image link may look strange! It is done this way to allow images to be saved before the text is ready to use them. In Vscode you can type in ../../../and then select from a list.

Preview

To see what it looks like so far (on Mac: Shift + cmd + V):

Make a few more changes and switch back to the Preview. Easy!

Articles Index

Articles stored in Markdown format are converted to HTML and stored in a Joomla database table using a build process that also generates a suite of responsive images from the single image stored in the source. The build process for Help pages also creates article versions for the Help proxy server. The list of articles to be included in a manual is kept in an articles-index.txt file in the English section of the source:

• The order does not matter but it is convenient to use the same order as the menu.
• Each language is a separate git repository.

Menu Index

At the outset I decided not to use Joomla menus: too many articles in too many languages.

• The menus are simple text files easily used in scripting.
• The menu order is the item order in the menu-index.txt file.
• There is a simple method to control nesting. Originally, only one nesting level was used. More nesting leads to accessibility problems.
• The menu-index.txt file in the English manual is used to build menus in other languages.

Commit and Push

Changes made to sources locally can be immediately built to see how they look in Jdocmanual. When I am happy, I commit the changes to the GitHub repository (one for each Language in each Manual).

The changes are then available to Pull in the public site (jdocmanual.org).

Jdocmanual Administration

Manual View

The Administrator, Manual view is similar to the Site view:

The extra Toolbar button allows the Administrator menu to toggle on/off.

Sources View

The Sources view shows the list of Manuals available and the buttons to build a Manual in a selected language. Building an entire manual in one language can take 5 minutes or more. Building a single article takes a few seconds. This screenshot shows my localhost installation:

This screenshot shows my live site with an extra column of buttons to Pull any changes from GitHub. So the normal procedure is to Pull then Build.

• There is a CLI interface so building can be accomplished from the command line.

Article Stashes View

The original idea was to manage all contributions within Jdocmanual. So custom Groups can be configured for the equivalent of Editor and Publisher. Either way, the process starts with a user making a personal Stash copy of an article to work on. This is the list of articles, one with a Stash already created.

• Some of the Tabs are for Publisher only...

Article Edit Stash

And this is the Stash view with the Edit tab selected:

The additional tabs show other parts of the Stash preparation process:

• Details: all read only data showing article details.
• Source: the original source for reference.
• Diff: the diff between the Stash and Source to show what has changed.
• Preview: a preview of the Stash version.
• Comments: for the Pull request and Publisher.

I have stopped using this method as it does not Push to GitHub and can be confusing. Also, I did not want to manage Joomla users.

Screenshots with Playwright

To make screenshots for Help pages I make bilingual Joomla installations with a number of settings designed to illustrate the features of each Help page. I then use Playwright to capture the screenshots. It takes a few minutes to capture all 469 screenshots. That can be done before any translations are available.

• The functions beforeAll, beforeEach and afterEach set up and tear down individual tests.
• A single test can be run manually for debugging purposes.
• Debugging can be performed with Browser activation so the problem points can be identified.
• The screenshots are usually collected using a console command.

Translation with Openai

Three of the Manuals have been translated into 8 langues using Open AI. Each one costs a few dollars and I pay for that myself. I could translate the Joomla! Programmers Documentation but was waiting for it to be more nearly finished! This is a fragment of my stand-alone PHP translation script.

This script is not published!

The Help Proxy Server

The configuration.php file contains the url of the Help server. It is easy to change it to point at the Jdocmanual proxy to get its Help pages rather than those coming from help.joomla.org.

Questions

• How am I doing for time?

Some Statistics

Number of articles in each manual:

Manual	Count
User	222
Help	279
Developer	39
Programmer	275
Docs	32
Total	857

With translations there are currently a total of 5175 articles.