Filling documentation gaps

app/src/main/java/ru/noties/markwon/Blah.java

@@ -1,21 +1,25 @@
 package ru.noties.markwon;
 
 import android.content.res.Resources;
+import android.graphics.Color;
+import android.support.annotation.Nullable;
+import android.text.style.ForegroundColorSpan;
 
 import ru.noties.markwon.il.AsyncDrawableLoader;
 import ru.noties.markwon.il.GifMediaDecoder;
 import ru.noties.markwon.il.ImageMediaDecoder;
 import ru.noties.markwon.il.SvgMediaDecoder;
+import ru.noties.markwon.renderer.html2.CssInlineStyleParser;
+import ru.noties.markwon.renderer.html2.CssProperty;
+import ru.noties.markwon.renderer.html2.MarkwonHtmlRenderer;
 
 public class Blah {
 
     static {
-AsyncDrawableLoader.builder()
+final CssInlineStyleParser inlineStyleParser = CssInlineStyleParser.create();
-        .mediaDecoders(
+for (CssProperty property: inlineStyleParser.parse("width: 100%; height: 100%;")) {
-SvgMediaDecoder.create(Resources),
+    // [0] = CssProperty({width=100%}),
-GifMediaDecoder.create(boolean),
+    // [1] = CssProperty({height=100%})
-ImageMediaDecoder.create(Resources)
+}
-        )
-.build();
     }
 }

app/src/main/java/ru/noties/markwon/MarkdownRenderer.java

@@ -87,8 +87,6 @@ public class MarkdownRenderer {
                         0x20000000
                 );
 
-                final int red = 0xFFff0000;
-
                 final SpannableConfiguration configuration = SpannableConfiguration.builder(context)
                         .asyncDrawableLoader(loader)
                         .urlProcessor(urlProcessor)
@@ -96,7 +94,6 @@ public class MarkdownRenderer {
                         .theme(SpannableTheme.builderWithDefaults(context)
                                 .codeBackgroundColor(background)
                                 .codeTextColor(prism4jTheme.textColor())
-                                .codeMultilineMargin(100)
                                 .build())
                         .factory(new GifAwareSpannableFactory(gifPlaceholder))
                         .trimWhiteSpaceEnd(false)

docs/docs/factory.md

@@ -1,5 +1,35 @@
 # Factory <Badge text="1.1.0" />
 
+`SpannableFactory` is used to create Span implementations.
+
+```java
+SpannableConfiguration.builder(context)
+        .factory(SpannableFactory)
+        .build();
+```
+
+`Markwon` provides default `SpannableFactoryDef` implementation that is
+used by default.
+
+Spans:
+* `strongEmphasis`
+* `emphasis`
+* `blockQuote`
+* `code`
+* `orderedListItem`
+* `bulletListItem`
+* `thematicBreak`
+* `heading`
+* `strikethrough`
+* `taskListItem`
+* `tableRow`
+* `paragraph` <Badge text="1.1.1" />
+* `image`
+* `link`
+* `superScript` (HTML content only)
+* `subScript` (HTML content only)
+* `underline` (HTML content only)
+
 :::tip
 `SpannableFactory` can be used to ignore some kinds of text markup. If, for example,
 you do not wish to apply _emphasis_ styling to your final result, just return `null`
@@ -12,3 +42,20 @@ public Object emphasis() {
 }
 ```
 :::
+
+:::tip
+All factory methods in `SpannableFactory` return an `Object`, but you can actually
+return an **array of Objects** if you wish to apply multiple Spans to a single styling node.
+For example, let's make all _emphasis_ also <span :style="{color: '#F00'}">red</span>:
+
+```java
+@Nullable
+@Override
+public Object emphasis() {
+    return new Object[] {
+            super.emphasis(),
+            new ForegroundColorSpan(Color.RED)
+    };
+}
+```
+:::

docs/docs/html.md

@@ -1,5 +1,4 @@
-# HTML
+# HTML <Badge text="2.0.0" />
-<Badge text="2.0.0" />
 
 Starting with version `2.0.0` `Markwon` brings the whole HTML parsing/rendering
 stack _on-site_. The main reason for this are _special_ definitions of HTML nodes
@@ -165,8 +164,112 @@ All tags that are not _inline_ are considered to be _block_ ones.
 
 ## Renderer
 
+Unlike `MarkwonHtmlParser` `Markwon` comes with a `MarkwonHtmlRenderer` by default.
+
+Default implementation can be obtain like this:
+
+```java
+MarkwonHtmlRenderer.create();
+```
+
+Default instance have these tags _handled_:
+* emphasis
+  * `i`
+  * `em`
+  * `cite`
+  * `dfn`
+* strong emphasis
+  * `b`
+  * `strong`
+* `sup` (super script)
+* `sub` (sub script)
+* underline
+  * `u`
+  * `ins`
+* strike through
+  * `del`
+  * `s`
+  * `strike`
+* `a` (link)
+* `ul` (unordered list)
+* `ol` (ordered list)
+* `img` (image)
+* `blockquote` (block quote)
+
+If you wish to _extend_ default handling (or override existing),
+`#builderWithDefaults` factory method can be used:
+
+```java
+MarkwonHtmlRenderer.builderWithDefaults();
+```
+
+For a completely _clean_ configurable instance `#builder` method can be used:
+
+```java
+MarkwonHtmlRenderer.builder();
+```
+
 ### Custom tag handler
-CssInlineStyleParser
+
+To configure `MarkwonHtmlRenderer` to handle tags differently or 
+create a new tag handler - `TagHandler` can be used
+
+```java
+public abstract class TagHandler {
+
+    public abstract void handle(
+            @NonNull SpannableConfiguration configuration,
+            @NonNull SpannableBuilder builder,
+            @NonNull HtmlTag tag
+    );
+}
+```
+
+For the most simple _inline_ tag handler a `SimpleTagHandler` can be used:
+
+```java
+public abstract class SimpleTagHandler extends TagHandler {
+
+    @Nullable
+    public abstract Object getSpans(@NonNull SpannableConfiguration configuration, @NonNull HtmlTag tag);
+}
+```
+
+For example, `EmphasisHandler`:
+
+```java
+public class EmphasisHandler extends SimpleTagHandler {
+    @Nullable
+    @Override
+    public Object getSpans(@NonNull SpannableConfiguration configuration, @NonNull HtmlTag tag) {
+        return configuration.factory().emphasis();
+    }
+}
+```
+
+If you wish to handle a _block_ HTML node (for example `<ul><li>First<li>Second</ul>`) refer
+to `ListHandler` source code for reference.
+
+:::warning
+The most important thing when implementing custom `TagHandler` is to know
+what type of `HtmlTag` we are dealing with. There are 2: inline &amp; block.
+Inline tag cannot contain children. Block _can_ contain children. And they
+_most likely_ should also be visited and _handled_ by registered `TagHandler` (if any)
+accordingly. See `TagHandler#visitChildren(configuration, builder, child);`
+:::
+
+#### Css inline style parser
+
+When implementing own `TagHandler` you might want to inspect inline CSS styles
+of a HTML element. `Markwon` provides an utility parser for that purpose:
+
+```java
+final CssInlineStyleParser inlineStyleParser = CssInlineStyleParser.create();
+for (CssProperty property: inlineStyleParser.parse("width: 100%; height: 100%;")) {
+    // [0] = CssProperty({width=100%}),
+    // [1] = CssProperty({height=100%})
+}
+```
 
 ## Exclude HTML parsing
 

docs/docs/image-loader.md

@@ -16,6 +16,8 @@ public interface Loader {
 
 ## AsyncDrawableLoader
 
+<MavenBadge artifact="markwon-image-loader" />
+
 `AsyncDrawableLoader` from `markwon-image-loader` artifact can be used.
 
 :::tip Install

docs/docs/syntax-highlight.md

@@ -1,5 +1,7 @@
 # Syntax highlight
 
+<MavenBadge artifact="markwon-syntax-highlight" />
+
 This is a simple module to add **syntax highlight** functionality to your markdown rendered with `Markwon` library. It is based on [Prism4j](https://github.com/noties/Prism4j) so lead there to understand how to configure `Prism4j` instance.
 
 <img :src="$withBase('/art/markwon-syntax-default.png')" alt="theme-default" width="80%">

docs/docs/theme.md

@@ -120,3 +120,93 @@ Typeface of code content
 Text size of code content
 
 <ThemeProperty name="codeTextSize" type="@Px int" defaults="(Content text size) * 0.87 if no custom <a href='#code-typeface'>Typeface</a> was set, otherwise (content text size)" />
+
+## Heading
+
+### Break height
+
+The height of a brake under H1 &amp; H2
+
+<ThemeProperty name="headingBreakHeight" type="@Px int" defaults="Stroke width of context TextPaint" />
+
+### Break color
+
+The color of a brake under H1 &amp; H2
+
+<ThemeProperty name="headingBreakColor" type="@ColorInt int" defaults="(text color) with 75 (0-255) alpha" />
+
+### Typeface <Badge text="1.1.0" />
+
+The typeface of heading elements
+
+<ThemeProperty name="headingTypeface" type="android.graphics.Typeface" defaults="default text Typeface" />
+
+### Text size <Badge text="1.1.0" />
+
+Array of heading text sizes _ratio_ that is applied to text size
+
+<ThemeProperty name="headingTextSizeMultipliers" type="float[]" defaults="<code>{2.F, 1.5F, 1.17F, 1.F, .83F, .67F}</code> (HTML spec)" />
+
+## Script ratio
+
+Ratio to be applied for `sup` (super script) &amp; `sub` (sub script)
+
+<ThemeProperty name="scriptTextSizeRatio" type="float" defaults="0.75F" />
+
+## Thematic break
+
+### Color
+
+Color of a thematic break
+
+<ThemeProperty name="thematicBreakColor" type="@ColorInt int" defaults="(text color) with 25 (0-255) alpha" />
+
+### Height
+
+Height of a thematic break
+
+<ThemeProperty name="thematicBreakHeight" type="@Px int" defaults="Stroke width of context TextPaint" />
+
+## Table
+
+### Cell padding
+
+Padding inside a table cell
+
+<ThemeProperty name="tableCellPadding" type="@Px int" defaults="0" />
+
+### Border color
+
+The color of table borders
+
+<ThemeProperty name="tableBorderColor" type="@ColorInt int" defaults="(text color) with 75 (0-255) alpha" />
+
+### Border width
+
+The width of table borders
+
+<ThemeProperty name="tableBorderWidth" type="@Px int" defaults="Stroke with of context TextPaint" />
+
+### Odd row background
+
+Background of an odd table row
+
+<ThemeProperty name="tableOddRowBackgroundColor" type="@ColorInt int" defaults="(text color) with 22 (0-255) alpha" />
+
+### Even row background <Badge text="1.1.1" />
+
+Background of an even table row
+
+<ThemeProperty name="tableEventRowBackgroundColor" type="@ColorInt int" defaults="0" />
+
+### Header row background <Badge text="1.1.1" />
+
+Background of header table row
+
+<ThemeProperty name="tableHeaderRowBackgroundColor" type="@ColorInt int" defaults="0" />
+
+## Task list drawable <Badge text="1.0.1" />
+
+Drawable of task list item
+
+<ThemeProperty name="taskListDrawable" type="android.graphics.drawable.Drawable" defaults="ru.noties.markwon.spans.TaskListDrawable" />

docs/docs/view.md

@@ -1 +1,41 @@
 # MarkwonView
+
+<MavenBadge artifact="markwon-view" />
+
+This is simple library containing 2 views that are able to display markdown:
+* MarkwonView - extends `android.view.TextView`
+* MarkwonViewCompat - extends `android.support.v7.widget.AppCompatTextView`
+
+Both of them implement common `IMarkwonView` interface:
+```java
+public interface IMarkwonView {
+
+    interface ConfigurationProvider {
+        @NonNull
+        SpannableConfiguration provide(@NonNull Context context);
+    }
+
+    void setConfigurationProvider(@NonNull ConfigurationProvider provider);
+
+    void setMarkdown(@Nullable String markdown);
+    void setMarkdown(@Nullable SpannableConfiguration configuration, @Nullable String markdown);
+
+    @Nullable
+    String getMarkdown();
+}
+```
+
+Both views support layout-preview in Android Studio (with some exceptions, for example, bold span is not rendered due to some limitations of layout preview).
+These are XML attributes:
+```
+app:mv_markdown="string"
+app:mv_configurationProvider="string"
+```
+
+`mv_markdown` accepts a string and represents raw markdown
+
+`mv_configurationProvider` accepts a string and represents a full class name of a class of type `ConfigurationProvider`,
+for example: `com.example.my.package.MyConfigurationProvider` (this class must have an empty constructor
+in order to be instantiated via reflection).
+
+Please note that those views parse markdown in main thread, so their usage must be for relatively small markdown portions only