jaspr_markdown_plus #

A powerful and highly customizable Markdown renderer for the Jaspr web framework.

jaspr_markdown_plus makes it easy to render rich text content in your Jaspr applications. It supports GitHub Flavored Markdown, comes with beautiful default themes, offers full styling control for every element, and includes syntax highlighting for code blocks right out of the box.

Features #

• GitHub Flavored Markdown: Renders tables, fenced code blocks, strikethrough text, and more.
• Beautiful Themes: Includes pre-built light and dark themes inspired by modern designs.
• Fully Customizable Styling: Take complete control over the appearance of every element, from headings and links to tables and code snippets.
• Syntax Highlighting: Automatic, themeable syntax highlighting for dozens of programming languages in code blocks.
• Advanced Customization:(still in the works) Use builder functions to completely change how elements like code blocks are rendered, perfect for adding "Copy to Clipboard" buttons or custom headers.
• Seamless Integration: Works as a standard Jaspr component, accepting styles, classes, events, and other attributes for its container.

Installation #

Add the package to your pubspec.yaml file:

dart pub add jaspr_markdown_plus

Quick Start #

Using the component is simple. Import the library and use the Markdown widget, providing it with your markdown string. It comes with a beautiful default light theme.

import 'package:jaspr/jaspr.dart';
import 'package:jaspr_markdown_plus/jaspr_markdown_plus.dart';

class MyComponent extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    const myMarkdown = """
# Hello, Jaspr!

This is a **Markdown** component for your Jaspr app.
""";

    return Markdown(
      markdown: myMarkdown,
      // Apply some padding to the outer container
      styles: const Styles.box(padding: EdgeInsets.all(Unit.em(2))),
    );
  }
}

Customization Guide #

jaspr_markdown_plus is designed to be highly customizable through the MarkdownStyleConfig class.

Using Themes #

The package includes two built-in themes. You can easily switch between them:

// Use the default light theme (this is the default)
Markdown(
  markdown: content,
  styleConfig: MarkdownStyleConfig.defaultLight,
);

// Or switch to the dark theme
Markdown(
  markdown: content,
  styleConfig: MarkdownStyleConfig.defaultDark,
);

Creating Your Own Theme #

You can create a custom theme by starting from scratch or, more easily, by modifying one of the default themes. MarkdownStyleConfig provides two powerful methods for this: copyWith and addWith.

1. Overriding Styles with copyWith

Use copyWith when you want to completely replace the style for an element. For example, to change the color and decoration of links in the light theme:

final myTheme = MarkdownStyleConfig.defaultLight.copyWith(
   linkStyle: Styles(
      color: Colors.red,
      fontWeight: FontWeight.w900,
      textDecoration: TextDecoration(line: TextDecorationLine.lineThrough),
    ),
);

Markdown(
  markdown: content,
  styleConfig: myTheme,
);

2. Merging Styles with addWith

Use addWith when you want to add or modify a few properties without losing the existing styles. For example, let's add a border to all paragraphs in the default theme while keeping their default margins:

final myTheme = MarkdownStyleConfig.defaultLight.addWith(
  pStyle: const Styles(
    border: Border.only(
      left: BorderSide.solid(width: Unit.pixels(3), color: Colors.blue),
    ),
    padding: Padding.only(left: Unit.em(1)),
  ),
);

Markdown(
  markdown: content,
  styleConfig: myTheme,
);

Styling the Container #

The styleConfig property styles the content of the markdown. To style the outer div that contains the markdown, use the styles property, just like with any other Jaspr component.

Markdown(
  markdown: content,
  // These styles apply to the container div
  styles: const Styles(
    maxWidth: Unit.pixels(800),
    margin: Margin.symmetric(horizontal: Unit.auto),
    padding: Padding.all(Unit.em(2)),
    backgroundColor: Colors.white,
  ),
);

custimize code highlighting #

code highlight colors can be customized by providing Map<String, Styles> for MarkdownStyleConfig.highlightMap. the availble keys are :

'root
'comment'
'quote'
'keyword'
'selector-tag'
'subst'
'meta'
'name'
'symbol'
'number'
'literal'
'variable'
'template-variable'
'string'
'doctag'
'title'
'section'
'selector-id'
'selector-class'
'function'
'deletion'
'type'
'class-title'
'built_in'
'attribute'
'regexp'
'link'
'params'
'tag'
'emphasis'
'strong'

NOTE that rootis the styling for text that is not part of the highlighted words for that language and is overrided by the MarkdownStyleConfig.codeStyle text specific attributes.

Advanced Usage: Builder Functions #

currently allows for custom code and pre blocs only

For ultimate control, you can use the MarkdownParseConfig to provide builder functions that change the structure of the rendered output.

This is perfect for adding features like a "Copy to Clipboard" button to code blocks.

API Reference #

• Markdown: The main component for rendering markdown.
• MarkdownStyleConfig: A class to define the visual styles for all rendered markdown elements and the syntax highlighting theme. Comes with defaultLight and defaultDark presets.
• MarkdownParseConfig: An advanced configuration class that allows you to provide custom builder functions (codeBuilder, preBuilder) to modify the rendered output.

Roadmap #

• Add support for html tags rendering.
• Add support for latex.

License #

jaspr_markdown_plus is licenced under the terms of MIT License.

ScreenShots #

light theme	dark theme