Filling documentation gaps
This commit is contained in:
Dimitry Ivanov
parent
8b8bf60290
commit
a76ceebc22
@ -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%})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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`
|
||||
@ -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 <span :style="{color: '#F00'}">red</span>:
|
||||
|
||||
```java
|
||||
@Nullable
|
||||
@Override
|
||||
public Object emphasis() {
|
||||
return new Object[] {
|
||||
super.emphasis(),
|
||||
new ForegroundColorSpan(Color.RED)
|
||||
};
|
||||
}
|
||||
```
|
||||
:::
|
||||
@ -1,5 +1,4 @@
|
||||
# HTML
|
||||
<Badge text="2.0.0" />
|
||||
# HTML <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 & 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
|
||||
|
||||
|
||||
@ -16,6 +16,8 @@ public interface Loader {
|
||||
|
||||
## AsyncDrawableLoader
|
||||
|
||||
<MavenBadge artifact="markwon-image-loader" />
|
||||
|
||||
`AsyncDrawableLoader` from `markwon-image-loader` artifact can be used.
|
||||
|
||||
:::tip Install
|
||||
|
||||
@ -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%">
|
||||
|
||||
@ -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 & H2
|
||||
|
||||
<ThemeProperty name="headingBreakHeight" type="@Px int" defaults="Stroke width of context TextPaint" />
|
||||
|
||||
### Break color
|
||||
|
||||
The color of a brake under H1 & 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) & `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" />
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user