Page 1 of 1
Rendering warnings / alerts from markdown to HTML
Posted: Fri Feb 06, 2026 1:24 pm
by Sergio_7
Hi everyone,
We work with DITA and Markdown files and output them as webhelp HTML. To achieve a consistent look, I would like to use a standardized style for Markdown warnings and customize them individually in CSS. Unfortunately, in HTML the warnings are output as quotes without a specific class or ID that could be used to style them individually (icon, color, etc.).
Can you help me figure out how to do this?
Markdown syntax for warnings:
> [!NOTE]
---------------
> [!TIP]
---------------
> [!IMPORTANT]
---------------
> [!WARNING]
---------------
> [!CAUTION]
---------------
Example:
Text in markdown:
Code: Select all
> [!WARNING]
> here is the text ...
Output in HTML as quotes (see image) without any class or ID for the type "warning".
output-html.png
A good approach could be to achieve this look:
default-md-alerts.png
Re: Rendering warnings / alerts from markdown to HTML
Posted: Fri Feb 06, 2026 3:58 pm
by julien_lacour
Hello,
One possibility could be to integrate HTML content directly in the Markdown topic:
Code: Select all
<div class="- topic/note note note note_note"><span class="note__title">Note:</span>
In this instance, the technical writer knows nothing about his subject.</div>
<div class="- topic/note note caution note_caution" type="caution"><span class="note__title">CAUTION:</span>
You must be grounded before doing this.</div>
<div class="- topic/note note warning note_warning" type="warning"><span class="note__title">WARNING:</span>
This is a dangerous operation.</div>
By using original classes, you will fall back to the original DITA processing and you can apply the style easily.
Regards,
Julien
Re: Rendering basic admonitions (warnings/alerts) from markdown to HTML
Posted: Mon Feb 09, 2026 10:44 am
by Sergio_7
Hi Julien,
Thanks for your reply.
Yes, that would work, but the problem is that the md files usually come directly from developers and their content should not be changed. It would be ideal if the basic admonitions (note, tip, important, warning, caution, danger, info, success etc.) were recognized directly by Oxygen by default and rendered correctly in the output. Is something like this in your backlog? Is this a case for a feature request? I can't imagine that I'm the only one with this problem. Warning messages are a central part of the documentation.
Regards,
Sergio
Re: Rendering warnings / alerts from markdown to HTML
Posted: Mon Feb 09, 2026 11:01 am
by julien_lacour
Hi Sergio,
In this case you could use
Mardown DITA syntax:
Regards,
Julien
Re: Rendering warnings / alerts from markdown to HTML
Posted: Mon Feb 09, 2026 12:50 pm
by Sergio_7
Hi Julien,
that's a much better approach, thank you.
Question:
Is there any way to further expand the admonitions support for DITA (it appears that only “Docusaurus” and “MkDocs” are currently supported) so that widely used admonitions such as "GitHub" and "GitLab" can also be taken into account?
You will find an overview here:
https://blog.markdowntools.com/posts/ma ... lete-guide
Thank you!
Re: Rendering warnings / alerts from markdown to HTML
Posted: Tue Feb 10, 2026 10:16 am
by julien_lacour
Hello,
Markdown support is supplied by the Lightweight DITA for DITA-OT plugin.
You could add an improvement issue in the plugin repository:
https://github.com/jelovirt/org.lwdita
Regards,
Julien