From a76ceebc22dee146f9d0e14517d6aaa64e5e917d Mon Sep 17 00:00:00 2001 From: Dimitry Ivanov Date: Tue, 21 Aug 2018 18:06:42 +0300 Subject: [PATCH] Filling documentation gaps --- app/src/main/java/ru/noties/markwon/Blah.java | 18 +-- .../ru/noties/markwon/MarkdownRenderer.java | 3 - docs/docs/factory.md | 47 ++++++++ docs/docs/html.md | 109 +++++++++++++++++- docs/docs/image-loader.md | 2 + docs/docs/syntax-highlight.md | 2 + docs/docs/theme.md | 90 +++++++++++++++ docs/docs/view.md | 40 +++++++ 8 files changed, 298 insertions(+), 13 deletions(-) diff --git a/app/src/main/java/ru/noties/markwon/Blah.java b/app/src/main/java/ru/noties/markwon/Blah.java index f77fc2b8..3e3c0071 100644 --- a/app/src/main/java/ru/noties/markwon/Blah.java +++ b/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() - .mediaDecoders( -SvgMediaDecoder.create(Resources), -GifMediaDecoder.create(boolean), -ImageMediaDecoder.create(Resources) - ) -.build(); +final CssInlineStyleParser inlineStyleParser = CssInlineStyleParser.create(); +for (CssProperty property: inlineStyleParser.parse("width: 100%; height: 100%;")) { + // [0] = CssProperty({width=100%}), + // [1] = CssProperty({height=100%}) +} } } diff --git a/app/src/main/java/ru/noties/markwon/MarkdownRenderer.java b/app/src/main/java/ru/noties/markwon/MarkdownRenderer.java index 133290a1..a868bbcd 100644 --- a/app/src/main/java/ru/noties/markwon/MarkdownRenderer.java +++ b/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) diff --git a/docs/docs/factory.md b/docs/docs/factory.md index 9c3129af..edf4a018 100644 --- a/docs/docs/factory.md +++ b/docs/docs/factory.md @@ -1,5 +1,35 @@ # Factory +`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` +* `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` @@ -11,4 +41,21 @@ public Object emphasis() { return null; } ``` +::: + +:::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 red: + +```java +@Nullable +@Override +public Object emphasis() { + return new Object[] { + super.emphasis(), + new ForegroundColorSpan(Color.RED) + }; +} +``` ::: \ No newline at end of file diff --git a/docs/docs/html.md b/docs/docs/html.md index decd073b..d08fe2eb 100644 --- a/docs/docs/html.md +++ b/docs/docs/html.md @@ -1,5 +1,4 @@ -# HTML - +# HTML 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 `
  • First
  • Second
`) 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 & 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 diff --git a/docs/docs/image-loader.md b/docs/docs/image-loader.md index d58c51dd..1dee8d58 100644 --- a/docs/docs/image-loader.md +++ b/docs/docs/image-loader.md @@ -16,6 +16,8 @@ public interface Loader { ## AsyncDrawableLoader + + `AsyncDrawableLoader` from `markwon-image-loader` artifact can be used. :::tip Install diff --git a/docs/docs/syntax-highlight.md b/docs/docs/syntax-highlight.md index 95406581..c8044f3d 100644 --- a/docs/docs/syntax-highlight.md +++ b/docs/docs/syntax-highlight.md @@ -1,5 +1,7 @@ # 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. theme-default diff --git a/docs/docs/theme.md b/docs/docs/theme.md index c3e9e77b..b01f7f31 100644 --- a/docs/docs/theme.md +++ b/docs/docs/theme.md @@ -120,3 +120,93 @@ Typeface of code content Text size of code content + +## Heading + +### Break height + +The height of a brake under H1 & H2 + + + +### Break color + +The color of a brake under H1 & H2 + + + +### Typeface + +The typeface of heading elements + + + +### Text size + +Array of heading text sizes _ratio_ that is applied to text size + + + +## Script ratio + +Ratio to be applied for `sup` (super script) & `sub` (sub script) + + + +## Thematic break + +### Color + +Color of a thematic break + + + +### Height + +Height of a thematic break + + + +## Table + +### Cell padding + +Padding inside a table cell + + + +### Border color + +The color of table borders + + + +### Border width + +The width of table borders + + + +### Odd row background + +Background of an odd table row + + + +### Even row background + +Background of an even table row + + + +### Header row background + +Background of header table row + + + +## Task list drawable + +Drawable of task list item + + diff --git a/docs/docs/view.md b/docs/docs/view.md index 3bc5f982..c43b4e9d 100644 --- a/docs/docs/view.md +++ b/docs/docs/view.md @@ -1 +1,41 @@ # MarkwonView + + + +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