Merge pull request #215 from noties/v.4.3.0

V4.3.0

CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+# 4.3.0-SNAPSHOT
+* add `MarkwonInlineParserPlugin` in `inline-parser` module
+* `JLatexMathPlugin` now supports inline LaTeX structures via `MarkwonInlineParserPlugin` 
+dependency (must be explicitly added to `Markwon` whilst configuring)
+* `JLatexMathPlugin`: add `theme` (to customize both inlines and blocks)
+* add `JLatexMathPlugin.ErrorHandler` to catch latex rendering errors and (optionally) display error drawable ([#204])
+* `JLatexMathPlugin` add text color customization ([#207])
+* `JLatexMathPlugin` will use text color of widget in which it is displayed **if color is not set explicitly**
+* add `SoftBreakAddsNewLinePlugin` plugin (`core` module)
+* `LinkResolverDef` defaults to `https` when a link does not have scheme information ([#75])
+* add `option` abstraction for `sample` module allowing switching of multiple cases in runtime via menu
+* non-empty bounds for `AsyncDrawable` when no dimensions are not yet available ([#189])
+* `linkify` - option to use `LinkifyCompat` in `LinkifyPlugin` ([#201])
+<br>Thanks to [@drakeet]
+* `MarkwonVisitor.BlockHandler` and `BlockHandlerDef` implementation to control how blocks insert new lines after them
+
+
+```java
+// default usage: new blocks parser, no inlines
+final Markwon markwon = Markwon.builder(this)
+    .usePlugin(JLatexMathPlugin.create(textSize))
+    .build();
+```
+
+```java
+// legacy blocks (pre `4.3.0`) parsing, no inlines
+final Markwon markwon =  Markwon.builder(this)
+        .usePlugin(JLatexMathPlugin.create(textView.getTextSize(), builder -> builder.blocksLegacy(true)))
+        .build();
+```
+
+```java
+// new blocks parsing and inline parsing
+final Markwon markwon =  Markwon.builder(this)
+        .usePlugin(JLatexMathPlugin.create(textView.getTextSize(), builder -> {
+            // blocksEnabled and blocksLegacy can be omitted
+            builder
+                    .blocksEnabled(true)
+                    .blocksLegacy(false)
+                    .inlinesEnabled(true);
+        }))
+        .build();
+```
+
+[#189]: https://github.com/noties/Markwon/issues/189
+[#75]: https://github.com/noties/Markwon/issues/75
+[#204]: https://github.com/noties/Markwon/issues/204 
+[#207]: https://github.com/noties/Markwon/issues/207
+[#201]: https://github.com/noties/Markwon/issues/201
+[@drakeet]: https://github.com/drakeet
+
+
 # 4.2.2
 * Fixed `AsyncDrawable` display when it has placeholder with empty bounds ([#189])
 * Fixed `syntax-highlight` where code input is empty string ([#192])
@@ -84,7 +136,7 @@ use `Markwon#builderNoCore()` to obtain a builder without `CorePlugin`
 * Added `MarkwonPlugin.Registry` and `MarkwonPlugin#configure(Registry)` method
 * `CorePlugin#addOnTextAddedListener` (process raw text added)
 * `ImageSizeResolver` signature change (accept `AsyncDrawable`)
-* `LinkResolver` is now an independent entity (previously part of `LinkSpan`)
+* `LinkResolver` is now an independent entity (previously part of the `LinkSpan`), `LinkSpan.Resolver` -&gt; `LinkResolver`
 * `AsyncDrawableScheduler` can now be called multiple times without performance penalty
 * `AsyncDrawable` now exposes its destination, image-size, last known dimensions (canvas, text-size)
 * `AsyncDrawableLoader` signature change (accept `AsyncDrawable`)

build.gradle

@@ -4,7 +4,8 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.5.3'
+        // on `3.5.3` tests are not run from CLI
+        classpath 'com.android.tools.build:gradle:3.5.2'
         classpath 'com.github.ben-manes:gradle-versions-plugin:0.27.0'
     }
 }
@@ -16,6 +17,7 @@ allprojects {
         }
         google()
         jcenter()
+//        maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
     }
     version = VERSION_NAME
     group = GROUP
@@ -69,7 +71,7 @@ ext {
             'commonmark-table'        : "com.atlassian.commonmark:commonmark-ext-gfm-tables:$commonMarkVersion",
             'android-svg'             : 'com.caverock:androidsvg:1.4',
             'android-gif'             : 'pl.droidsonroids.gif:android-gif-drawable:1.2.15',
-            'jlatexmath-android'      : 'ru.noties:jlatexmath-android:0.1.0',
+            'jlatexmath-android'      : 'ru.noties:jlatexmath-android:0.1.1',
             'okhttp'                  : 'com.squareup.okhttp3:okhttp:3.9.0',
             'prism4j'                 : 'io.noties:prism4j:2.0.0',
             'debug'                   : 'io.noties:debug:5.0.0@jar',

docs/README.md

@@ -109,7 +109,8 @@ and 2 themes included: Light & Dark. It can be downloaded from [releases](ht
 <AwesomeGroup :apps="[
     {name: 'Nextcloud', image: $withBase(`/assets/apps/nextcloud.png`), link: 'https://github.com/nextcloud/android', description: 'A safe home for all your data. Access & share your files, calendars, contacts, mail & more from any device, on your terms.'},
     {name: 'Habitica', image: $withBase(`/assets/apps/habitica.png`), link: 'https://play.google.com/store/apps/details?id=com.habitrpg.android.habitica', description: 'Treat your life like a game to stay motivated and organized! Habitica makes it simple to have fun while accomplishing goals.'},
-    {name: 'Cinopsys: Movies and Shows', image: $withBase(`/assets/apps/cinopsys.png`), link: 'https://play.google.com/store/apps/details?id=com.cinopsys.movieshows'}
+    {name: 'Cinopsys: Movies and Shows', image: $withBase(`/assets/apps/cinopsys.png`), link: 'https://play.google.com/store/apps/details?id=com.cinopsys.movieshows'},
+    {name: 'Pure Writer', image: $withBase(`/assets/apps/purewriter.png`), link: 'https://play.google.com/store/apps/details?id=com.drakeet.purewriter', description: 'Never lose content editor & Markdown'}
 ]" />
 
 

docs/docs/v4/core/core-plugin.md

@@ -81,10 +81,15 @@ More information about props can be found [here](/docs/v4/core/render-props.md)
 ---
 
 :::tip Soft line break
-Since <Badge text="3.0.0" /> Markwon core does not give an option to
-insert a new line when there is a soft line break in markdown. Instead a
-custom plugin can be used:
+Since <Badge text="4.3.0" /> there is a dedicated plugin to insert a new line for 
+markdown soft breaks - `SoftBreakAddsNewLinePlugin`:
+```java
+final Markwon markwon = Markwon.builder(this)
+        .usePlugin(SoftBreakAddsNewLinePlugin.create())
+        .build();
+```
 
+It is still possible to do it manually with a custom visitor:
 ```java
 final Markwon markwon = Markwon.builder(this)
         .usePlugin(new AbstractMarkwonPlugin() {

docs/docs/v4/core/visitor.md

@@ -70,4 +70,33 @@ public void configureVisitor(@NonNull MarkwonVisitor.Builder builder) {
         }
     });
 }
+```
+
+### BlockHandler <Badge text="4.3.0" />
+
+Since <Badge text="4.3.0" /> there is class to control insertions of new lines after markdown blocks
+`BlockHandler` (`MarkwonVisitor.BlockHandler`) and its default implementation `BlockHandlerDef`. For example,
+to disable an empty new line after `Heading`:
+
+```java
+final Markwon markwon = Markwon.builder(this)
+        .usePlugin(new AbstractMarkwonPlugin() {
+            @Override
+            public void configureVisitor(@NonNull MarkwonVisitor.Builder builder) {
+                builder.blockHandler(new BlockHandlerDef() {
+                    @Override
+                    public void blockEnd(@NonNull MarkwonVisitor visitor, @NonNull Node node) {
+                        if (node instanceof Heading) {
+                            if (visitor.hasNext(node)) {
+                                visitor.ensureNewLine();
+                                // ensure new line but do not force insert one
+                            }
+                        } else {
+                            super.blockEnd(visitor, node);
+                        }
+                    }
+                });
+            }
+        })
+        .build();
 ```

docs/docs/v4/ext-latex/README.md

@@ -2,51 +2,130 @@
 
 <MavenBadge4 :artifact="'ext-latex'" />
 
-This is an extension that will help you display LaTeX formulas in your markdown.
-Syntax is pretty simple: pre-fix and post-fix your latex with `$$` (double dollar sign).
-`$$` should be the first characters in a line.
+This is an extension that will help you display LaTeX content in your markdown.
+Since <Badge text="4.3.0" /> supports both blocks and inlines markdown structures (blocks only before `4.3.0`).
 
+## Blocks
+Start a line with 2 (or more) `$` symbols followed by a new line:
 ```markdown
 $$
 \\text{A long division \\longdiv{12345}{13}
 $$
 ```
+LaTeX block content will be considered ended when a starting sequence of `$` is found on
+a new line. If block was started with `$$$` it must be ended with `$$$` symbols.
 
+## Inline
+Exactly `$$` before and after _inline_ LaTeX content:
 ```markdown
 $$\\text{A long division \\longdiv{12345}{13}$$
 ```
 
+:::warning
+By default inline nodes are disabled and must be enabled explicitly:
 ```java
-Markwon.builder(context)
-    .use(JLatexMathPlugin.create(textSize))
-    .build();
+final Markwon markwon = Markwon.builder(this)
+        // required plugin to support inline parsing
+        .usePlugin(MarkwonInlineParserPlugin.create())
+        .usePlugin(JLatexMathPlugin.create(textView.getTextSize(), new JLatexMathPlugin.BuilderConfigure() {
+            @Override
+            public void configureBuilder(@NonNull JLatexMathPlugin.Builder builder) {
+                // ENABLE inlines
+                builder.inlinesEnabled(true);
+            }
+        }))
+        .build();
 ```
+Please note that usage of inline nodes **require** [MarkwonInlineParserPlugin](../inline-parser/)
+:::
 
 This extension uses [jlatexmath-android](https://github.com/noties/jlatexmath-android) artifact to create LaTeX drawable. 
 
 ## Config
 
 ```java
-final Markwon markwon = Markwon.builder(context)
-        .usePlugin(JLatexMathPlugin.create(textSize, new BuilderConfigure() {
+// create default instance of plugin and use specified text size for both blocks and inlines
+JLatexMathPlugin.create(textView.getTextSize());
+
+// create default instance of plugin and use specified text sizes
+JLatexMathPlugin.create(inlineTextSize, blockTextSize);
+
+JLatexMathPlugin.create(textView.getTextSize(), new JLatexMathPlugin.BuilderConfigure() {
+    @Override
+    public void configureBuilder(@NonNull JLatexMathPlugin.Builder builder) {
+        // enable inlines (require `MarkwonInlineParserPlugin`), by default `false`
+        builder.inlinesEnabled(true);
+
+        // use pre-4.3.0 LaTeX block parsing (by default `false`)
+        builder.blocksLegacy(true);
+
+        // by default true
+        builder.blocksEnabled(true);
+
+        // @since 4.3.0
+        builder.errorHandler(new JLatexMathPlugin.ErrorHandler() {
+            @Nullable
             @Override
-            public void configureBuilder(@NonNull Builder builder) {
-                builder
-                        .align(JLatexMathDrawable.ALIGN_CENTER)
-                        .fitCanvas(true)
-                        .padding(paddingPx)
-                        // @since 4.0.0 - horizontal and vertical padding
-                        .padding(paddingHorizontalPx, paddingVerticalPx)
-                        // @since 4.0.0 - change to provider
-                        .backgroundProvider(() -> new MyDrawable()))
-                        // @since 4.0.0 - optional, by default cached-thread-pool will be used
-                        .executorService(Executors.newCachedThreadPool());
+            public Drawable handleError(@NonNull String latex, @NonNull Throwable error) {
+                // Receive error and optionally return drawable to be displayed instead
+                return null;
             }
-        }))
-        .build();
+        });
+
+        // executor on which parsing of LaTeX is done (by default `Executors.newCachedThreadPool()`)
+        builder.executorService(Executors.newCachedThreadPool());
+    }
+});
 ```
 
+## Theme
+
+```java
+JLatexMathPlugin.create(textView.getTextSize(), new JLatexMathPlugin.BuilderConfigure() {
+    @Override
+    public void configureBuilder(@NonNull JLatexMathPlugin.Builder builder) {
+
+        // background provider for both inlines and blocks
+        //  or more specific: `inlineBackgroundProvider` & `blockBackgroundProvider`
+        builder.theme().backgroundProvider(new JLatexMathTheme.BackgroundProvider() {
+            @NonNull
+            @Override
+            public Drawable provide() {
+                return new ColorDrawable(0xFFff0000);
+            }
+        });
+
+        // should block fit the whole canvas width, by default true
+        builder.theme().blockFitCanvas(true);
+
+        // horizontal alignment for block, by default ALIGN_CENTER 
+        builder.theme().blockHorizontalAlignment(JLatexMathDrawable.ALIGN_CENTER);
+
+        // padding for both inlines and blocks
+        builder.theme().padding(JLatexMathTheme.Padding.all(8));
+
+        // padding for inlines
+        builder.theme().inlinePadding(JLatexMathTheme.Padding.symmetric(16, 8));
+
+        // padding for blocks
+        builder.theme().blockPadding(new JLatexMathTheme.Padding(0, 1, 2, 3));
+
+        // text color of LaTeX content for both inlines and blocks
+        //  or more specific: `inlineTextColor` & `blockTextColor`
+        builder.theme().textColor(Color.RED);
+    }
+});
+```
 
 :::tip
-Since <Badge text="4.0.0" /> `JLatexMathPlugin` operates independently of `ImagesPlugin`
+Sometimes it is enough to use rendered to an image LaTeX formula and 
+inline it directly in your markdown document. For this markdown references can be useful. For example:
+```markdown
+<!-- your mardown -->
+![markdown-reference] of a solution...
+
+<!-- then reference prerendered and converted to base64 SVG/PNG/GIF/etc -->
+[markdown-reference]: data:image/svg+xml;base64,base64encodeddata==
+```
+For this to work an image loader that supports data uri and base64 must be used. Default `Markwon` [image-loader](../image/) supports it out of box (including SVG support)
 :::

docs/docs/v4/inline-parser/README.md

@@ -3,6 +3,16 @@
 **Experimental** commonmark-java inline parser that allows customizing 
 core features and/or extend with own. 
 
+:::tip
+Since <Badge text="4.3.0" /> there is also `MarkwonInlineParserPlugin` which can be used 
+to allow other plugins to customize inline parser
+```java
+final Markwon markwon = Markwon.builder(this)
+        .usePlugin(MarkwonInlineParserPlugin.create())
+        .build();
+```
+:::
+
 Usage of _internal_ classes:
 ```java
 import org.commonmark.internal.Bracket;

docs/docs/v4/install.md

@@ -5,8 +5,18 @@ next: /docs/v4/core/getting-started.md
 
 # Installation
 
-![stable](https://img.shields.io/maven-central/v/io.noties.markwon/core.svg?label=stable)
-![snapshot](https://img.shields.io/nexus/s/https/oss.sonatype.org/io.noties.markwon/core.svg?label=snapshot)
+<table>
+    <tbody>
+        <tr>
+            <td><img alt="stable" src="https://img.shields.io/maven-central/v/io.noties.markwon/core.svg?label=stable"></td>
+            <td><a href="https://github.com/noties/Markwon/blob/master/CHANGELOG.md">changelog<OutboundLink/></a></td>
+        </tr>
+        <tr>
+            <td><img alt="snapshot" src="https://img.shields.io/nexus/s/https/oss.sonatype.org/io.noties.markwon/core.svg?label=snapshot"></td>
+            <td><a href="https://github.com/noties/Markwon/blob/develop/CHANGELOG.md">changelog<OutboundLink/></a></td>
+        </tr>
+    </tbody>
+</table>
 
 <ArtifactPicker4 />
 

gradle.properties

@@ -8,7 +8,7 @@ android.enableJetifier=true
 android.enableBuildCache=true
 android.buildCacheDir=build/pre-dex-cache
 
-VERSION_NAME=4.2.2
+VERSION_NAME=4.3.0
 
 GROUP=io.noties.markwon
 POM_DESCRIPTION=Markwon markdown for Android

markwon-core/src/main/java/io/noties/markwon/BlockHandlerDef.java

@@ -0,0 +1,23 @@
+package io.noties.markwon;
+
+import androidx.annotation.NonNull;
+
+import org.commonmark.node.Node;
+
+/**
+ * @since 4.3.0
+ */
+public class BlockHandlerDef implements MarkwonVisitor.BlockHandler {
+    @Override
+    public void blockStart(@NonNull MarkwonVisitor visitor, @NonNull Node node) {
+        visitor.ensureNewLine();
+    }
+
+    @Override
+    public void blockEnd(@NonNull MarkwonVisitor visitor, @NonNull Node node) {
+        if (visitor.hasNext(node)) {
+            visitor.ensureNewLine();
+            visitor.forceNewLine();
+        }
+    }
+}