md2pango
The first Markdown to Pango Markup Converter!
md2pango is a simple regex-based line-by-line converter to convert simple Markdown to Pango Markup.
Purpose
Use Markdown + md2pango to define short texts for small dialogs in lightweight GTK apps. Pango's scope is very limited and thus are md2pango's supported Markdown features. For true richtext support and interactive apps use WebKitGTK.
The project started as part of a Gnome Extension and was later refactored to become a generic NPM module.
Usage
To use it in a GTK app, first add src/md2pango.js to the imports
;
either by just copying the file or during
packaging.
// Gnome Extension, with `md2pango.js` copied next to your `extension.js`
const md2pango = Me.imports.md2pango
// GTK app
imports.searchPath.unshift('path/to/md2pango')
const md2pango = imports.md2pango
// node.js app after installing the md2pango module
const md2pango = require('md2pango')
Thereafter just use md2pango.convert(str:String) -> str:String
.
let pangoText = md2pango.convert('### Heading')
// pangoText: <big>Heading</big>
CLI Mode
The module comes with a installable binary md2pango
.
Using md2pango FILE [FILE...]
one or more Markdown files can
be converted to Pango Markup. The result is written to process.stdout
.
Use it to convert Markdown files in your Pango/GTK projects if you cannot
or don't want to ship md2pango.js
with your code.
Converted Elements
headings: #, ##, ###, ===, ---
unordered list: * item
ordered list: 1. item
escaping: <, >, &
code block start: ```, ```lang
code block stop: ```
inline styles: **bold**, *emph*, `fixed`
inline urls: [name](link)
url detection: http[s]?://.*
comments: <!-- -->
color marcos: <!--fg|bg=COLOR|#RGB-->
Macros
Pango colors can be set as Markdown comments using <!--fg=#RGB bg=#RGB-->
.
Color names instead of #RGB
are also supported.
Use <!--/-->
to close the currently coloring block.
Currently, colors modifications cannot be nested.
Use only one macro per line!
Limitations
- All undetected markdown features will be escaped and converted as regular text.
- Multiple URIs on one line may cause trouble.
- Valid but unsupported Markdown/Pango XML tags are escaped and converted as regular text.
- Conversion and escaping are best effort (there are probably some ways to break it).
- The effects of nesting styles are unpredictable (requires a smarter Markdown parser).
- Multi-line list items are not supported.
Licenses
Code: MIT
Visuals: CC-BY-4.0
Contributing
When making changes to the project, please ensure that all changes also work in GJS/GTK apps and in Gnome Extensions. Also see CONTRIBUTING.md.