Finished core documentation
This commit is contained in:
Dimitry Ivanov
parent
0a965e4cbc
commit
12ef0b5703
@ -1 +1,82 @@
|
||||
# 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());
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
@ -1 +1,61 @@
|
||||
# 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)
|
||||
};
|
||||
}
|
||||
});
|
||||
```
|
||||
@ -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
|
||||
|
||||
@ -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();
|
||||
|
||||
@ -43,8 +43,12 @@ class MarkwonSpansFactoryImpl implements MarkwonSpansFactory {
|
||||
|
||||
@NonNull
|
||||
@Override
|
||||
public <N extends Node> Builder setFactory(@NonNull Class<N> node, @NonNull SpanFactory factory) {
|
||||
factories.put(node, factory);
|
||||
public <N extends Node> Builder setFactory(@NonNull Class<N> node, @Nullable SpanFactory factory) {
|
||||
if (factory == null) {
|
||||
factories.remove(node);
|
||||
} else {
|
||||
factories.put(node, factory);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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());
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user