Finished core documentation

docs/docs/v3/core/html-renderer.md

@@ -1 +1,82 @@
-# HTML Renderer
+# HTML Renderer
+
+Starting with <Badge text="3.0.0" /> `MarkwonHtmlRenderer` controls how HTML
+is rendered:
+
+```java
+Markwon.builder(context)
+        .usePlugin(new AbstractMarkwonPlugin() {
+            @Override
+            public void configureHtmlRenderer(@NonNull MarkwonHtmlRenderer.Builder builder) {
+                builder.setHandler("a", new MyTagHandler());
+            }
+        });
+```
+
+:::danger
+Customizing `MarkwonHtmlRenderer` is not enough to include HTML content in your application.
+You must explicitly include [markwon-html](/docs/v3/html/) artifact (include HtmlParser) 
+to you project and register `HtmlPlugin`:
+
+```java
+Markwon.builder(context)
+        .usePlugin(HtmlPlugin.create())
+```
+:::
+
+For example, to create an `<a>` HTML tag handler:
+
+```java
+builder.setHandler("a", new SimpleTagHandler() {
+    @Override
+    public Object getSpans(
+            @NonNull MarkwonConfiguration configuration,
+            @NonNull RenderProps renderProps,
+            @NonNull HtmlTag tag) {
+        return new LinkSpan(
+                configuration.theme(), 
+                tag.attributes().get("href"), 
+                configuration.linkResolver());
+    }
+});
+```
+
+`SimpleTagHandler` can be used for simple cases when a tag does not require any special
+handling (like visiting it's children)
+
+:::tip
+One can return `null` a single span or an array of spans from `getSpans` method
+:::
+
+For a more advanced usage `TagHandler` can be used directly:
+
+```java
+builder.setHandler("a", new TagHandler() {
+    @Override
+    public void handle(@NonNull MarkwonVisitor visitor, @NonNull MarkwonHtmlRenderer renderer, @NonNull HtmlTag tag) {
+        
+        // obtain default spanFactory for Link node
+        final SpanFactory factory = visitor.configuration().spansFactory().get(Link.class);
+        
+        if (factory != null) {
+            
+            // set destination property
+            CoreProps.LINK_DESTINATION.set(
+                    visitor.renderProps(), 
+                    tag.attributes().get("href"));
+            
+            // Obtain spans from the factory
+            final Object spans = factory.getSpans(
+                    visitor.configuration(), 
+                    visitor.renderProps());
+            
+            // apply spans to SpannableBuilder
+            SpannableBuilder.setSpans(
+                    visitor.builder(), 
+                    spans, 
+                    tag.start(), 
+                    tag.end());
+        }
+    }
+});
+```

docs/docs/v3/core/spans-factory.md

@@ -1 +1,61 @@
-# Spans Factory
+# Spans Factory
+
+Starting with <Badge text="3.0.0" /> `MarkwonSpansFactory` controls what spans are displayed
+for markdown nodes.
+
+```java
+Markwon.builder(context)
+        .usePlugin(new AbstractMarkwonPlugin() {
+            @Override
+            public void configureSpansFactory(@NonNull MarkwonSpansFactory.Builder builder) {
+                // passing null as second argument will remove previously added 
+                // factory for the Link node
+                builder.setFactory(Link.class, null);
+            }
+        });
+```
+
+## SpanFactory
+
+In order to create a _generic_ interface for all possible Nodes, a `SpanFactory`
+was added:
+
+```java
+builder.setFactory(Link.class, new SpanFactory() {
+    @Nullable
+    @Override
+    public Object getSpans(@NonNull MarkwonConfiguration configuration, @NonNull RenderProps props) {
+        return null;
+    }
+});
+```
+
+All possible arguments are passed via [RenderProps](/docs/v3/core/render-props.md):
+
+```java
+builder.setFactory(Link.class, new SpanFactory() {
+    @Override
+    public Object getSpans(@NonNull MarkwonConfiguration configuration, @NonNull RenderProps props) {
+        final String href = CoreProps.LINK_DESTINATION.require(props);
+        return new LinkSpan(configuration.theme(), href, configuration.linkResolver());
+    }
+});
+```
+
+`SpanFactory` allows returning `null` for a certain span (no span will be applied).
+Or an array of spans:
+
+```java
+builder.setFactory(Link.class, new SpanFactory() {
+    @Override
+    public Object getSpans(@NonNull MarkwonConfiguration configuration, @NonNull RenderProps props) {
+        return new Object[]{
+                new LinkSpan(
+                        configuration.theme(),
+                        CoreProps.LINK_DESTINATION.require(props),
+                        configuration.linkResolver()),
+                new ForegroundColorSpan(Color.RED)
+        };
+    }
+});
+```

docs/docs/v3/core/theme.md

@@ -128,12 +128,24 @@ Typeface of code content
 
 <ThemeProperty name="codeTypeface" type="android.graphics.Typeface" defaults="Typeface.MONOSPACE" />
 
+### Block code typeface <Badge text="3.0.0" />
+
+Typeface of block code content
+
+<ThemeProperty name="codeBlockTypeface" type="android.graphics.Typeface" defaults="<code>codeTypeface</code> if set or Typeface.MONOSPACE" />
+
 ### Code text size
 
 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)" />
 
+### Block code text size <Badge text="3.0.0" />
+
+Text size of block code content
+
+<ThemeProperty name="codeBlockTextSize" type="@Px int" defaults="<code>codeTextSize</code> if set or (content text size) * 0.87 if no custom <a href='#code-typeface'>Typeface</a> was set, otherwise (content text size)" />
+
 ## Heading
 
 ### Break height

markwon-core/src/main/java/ru/noties/markwon/MarkwonSpansFactory.java

@@ -32,7 +32,7 @@ public interface MarkwonSpansFactory {
     interface Builder {
 
         @NonNull
-        <N extends Node> Builder setFactory(@NonNull Class<N> node, @NonNull SpanFactory factory);
+        <N extends Node> Builder setFactory(@NonNull Class<N> node, @Nullable SpanFactory factory);
 
         @NonNull
         MarkwonSpansFactory build();

markwon-core/src/main/java/ru/noties/markwon/MarkwonSpansFactoryImpl.java

@@ -43,8 +43,12 @@ class MarkwonSpansFactoryImpl implements MarkwonSpansFactory {
 
         @NonNull
         @Override
-        public <N extends Node> Builder setFactory(@NonNull Class<N> node, @NonNull SpanFactory factory) {
+        public <N extends Node> Builder setFactory(@NonNull Class<N> node, @Nullable SpanFactory factory) {
-            factories.put(node, factory);
+            if (factory == null) {
+                factories.remove(node);
+            } else {
+                factories.put(node, factory);
+            }
             return this;
         }
 

markwon-core/src/main/java/ru/noties/markwon/html/MarkwonHtmlRenderer.java

@@ -42,10 +42,10 @@ public abstract class MarkwonHtmlRenderer {
         Builder allowNonClosedTags(boolean allowNonClosedTags);
 
         @NonNull
-        Builder addHandler(@NonNull String tagName, @NonNull TagHandler tagHandler);
+        Builder setHandler(@NonNull String tagName, @NonNull TagHandler tagHandler);
 
         @NonNull
-        Builder addHandler(@NonNull Collection<String> tagNames, @NonNull TagHandler tagHandler);
+        Builder setHandler(@NonNull Collection<String> tagNames, @NonNull TagHandler tagHandler);
 
         @NonNull
         Builder removeHandler(@NonNull String tagName);

markwon-core/src/main/java/ru/noties/markwon/html/MarkwonHtmlRendererImpl.java

@@ -100,14 +100,14 @@ class MarkwonHtmlRendererImpl extends MarkwonHtmlRenderer {
 
         @NonNull
         @Override
-        public Builder addHandler(@NonNull String tagName, @NonNull TagHandler tagHandler) {
+        public Builder setHandler(@NonNull String tagName, @NonNull TagHandler tagHandler) {
             tagHandlers.put(tagName, tagHandler);
             return this;
         }
 
         @NonNull
         @Override
-        public Builder addHandler(@NonNull Collection<String> tagNames, @NonNull TagHandler tagHandler) {
+        public Builder setHandler(@NonNull Collection<String> tagNames, @NonNull TagHandler tagHandler) {
             for (String tagName : tagNames) {
                 if (tagName != null) {
                     tagHandlers.put(tagName, tagHandler);

markwon-html/src/main/java/ru/noties/markwon/html/HtmlPlugin.java

@@ -45,37 +45,37 @@ public class HtmlPlugin extends AbstractMarkwonPlugin {
     public void configureHtmlRenderer(@NonNull MarkwonHtmlRenderer.Builder builder) {
 
         builder
-                .addHandler(
+                .setHandler(
                         "img",
                         ImageHandler.create())
-                .addHandler(
+                .setHandler(
                         "a",
                         new LinkHandler())
-                .addHandler(
+                .setHandler(
                         "blockquote",
                         new BlockquoteHandler())
-                .addHandler(
+                .setHandler(
                         "sub",
                         new SubScriptHandler())
-                .addHandler(
+                .setHandler(
                         "sup",
                         new SuperScriptHandler())
-                .addHandler(
+                .setHandler(
                         asList("b", "strong"),
                         new StrongEmphasisHandler())
-                .addHandler(
+                .setHandler(
                         asList("s", "del"),
                         new StrikeHandler())
-                .addHandler(
+                .setHandler(
                         asList("u", "ins"),
                         new UnderlineHandler())
-                .addHandler(
+                .setHandler(
                         asList("ul", "ol"),
                         new ListHandler())
-                .addHandler(
+                .setHandler(
                         asList("i", "em", "cite", "dfn"),
                         new EmphasisHandler())
-                .addHandler(
+                .setHandler(
                         asList("h1", "h2", "h3", "h4", "h5", "h6"),
                         new HeadingHandler());
     }