287 lines
9.8 KiB
Markdown
287 lines
9.8 KiB
Markdown
# Markwon
|
|
|
|
[](http://search.maven.org/#search|ga|1|g%3A%22ru.noties%22%20AND%20a%3A%markwon%22)
|
|
|
|
|
|
## Installation
|
|
```groovy
|
|
compile 'ru.noties:markwon:1.0.0'
|
|
```
|
|
|
|
## Intoduction
|
|
|
|
The aim for this library is to render markdown as first class citizen on Android - Spannables. It has reasonable defaults to display markdown, but also gives ability to customize almost every detail for your liking.
|
|
|
|
The most basic example would be:
|
|
```java
|
|
Markwon.setMarkdown(textView, "**Hello *there*!!**")
|
|
|
|
// or
|
|
Markwon.setMarkdown(textView, spannableConfiguration, "**There <u>hello</u>~~!~~**")
|
|
```
|
|
|
|
Please note, that this library depends on [commonmark-java][commonmark-java] (and some extensions):
|
|
```groovy
|
|
compile 'com.atlassian.commonmark:commonmark:0.9.0'
|
|
compile 'com.atlassian.commonmark:commonmark-ext-gfm-strikethrough:0.9.0'
|
|
compile 'com.atlassian.commonmark:commonmark-ext-gfm-tables:0.9.0'
|
|
```
|
|
|
|
## Configuration
|
|
In order to render correctly markdown, this library need a `SpannableConfiguration` instance. It has 2 factory methods:
|
|
```java
|
|
// creates default instance
|
|
SpannableConfiguration.create(Context);
|
|
|
|
// returns configurable Builder
|
|
SpannableConfiguration.builder(Context);
|
|
```
|
|
|
|
`SpannableConfiguration.Builder` class has these configurable properties (which are described in more detail further):
|
|
```java
|
|
public Builder theme(SpannableTheme theme);
|
|
public Builder asyncDrawableLoader(AsyncDrawable.Loader asyncDrawableLoader);
|
|
public Builder syntaxHighlight(SyntaxHighlight syntaxHighlight);
|
|
public Builder linkResolver(LinkSpan.Resolver linkResolver);
|
|
public Builder urlProcessor(UrlProcessor urlProcessor);
|
|
public Builder htmlParser(SpannableHtmlParser htmlParser);
|
|
|
|
// and obviously:
|
|
public SpannableConfiguration build();
|
|
```
|
|
|
|
## Images
|
|
|
|
By default this library does not render any of the images. It's done to simplify rendering of text-based markdown. But if images must be supported, then the `AsyncDrawable.Loader` can be specified whilst building a `SpannableConfiguration` instance:
|
|
|
|
```java
|
|
final AsyncDrawable.Loader loader = new AsyncDrawable.Loader() {
|
|
@Override
|
|
public void load(@NonNull String destination, @NonNull final AsyncDrawable drawable) {
|
|
// `download` method is here for demonstration purposes, it's not included in this interface
|
|
download(destination, new Callback() {
|
|
@Override
|
|
public void onDownloaded(Drawable d) {
|
|
// additionally we can call `drawable.isAttached()`
|
|
// to ensure if AsyncDrawable is in layout
|
|
drawable.setResult(d);
|
|
}
|
|
});
|
|
}
|
|
|
|
@Override
|
|
public void cancel(@NonNull String destination) {
|
|
// cancel download here
|
|
}
|
|
};
|
|
|
|
// `this` here referrs to a Context instance
|
|
final SpannableConfiguration configuration = SpannableConfiguration.builder(this)
|
|
.asyncDrawableLoader(loader)
|
|
.build();
|
|
```
|
|
|
|
There is also standalone artifact that supports image loading *out-of-box* (including support for **SVG** & **GIF**), but provides little to none configuration and could be somewhat not optimal. Please refer to the [README][mil-README] of the module.
|
|
|
|
|
|
## Tables
|
|
|
|
Tables are supported but with some limitations. First of all: table will always take the full width of the TextView Canvas. Second: each column will have the same width (we do not calculate the weight of column) - so, a column width will be: `totalWidth / columnsNumber`.
|
|
|
|
|
|
## Syntax highlight
|
|
This library does not provide ready-to-be-used implementation of syntax highlight, but it can be added via `SyntaxHighlight` interface whilst building `SpannableConfiguration`:
|
|
|
|
```java
|
|
final SyntaxHighlight syntaxHighlight = new SyntaxHighlight() {
|
|
@NonNull
|
|
@Override
|
|
public CharSequence highlight(@Nullable String info, @NonNull String code) {
|
|
// create Spanned of highlight here
|
|
return null; // must not return `null` here
|
|
}
|
|
};
|
|
|
|
final SpannableConfiguration configuration = SpannableConfiguration.builder(this)
|
|
.syntaxHighlight(syntaxHighlight)
|
|
.build();
|
|
```
|
|
|
|
## Url processing
|
|
If you wish to process urls (links & images) that markdown contains, the `UrlProcessor` can be used:
|
|
```java
|
|
final UrlProcessor urlProcessor = new UrlProcessor() {
|
|
@NonNull
|
|
@Override
|
|
public String process(@NonNull String destination) {
|
|
// modify the `destination` or return as-is
|
|
return null;
|
|
}
|
|
};
|
|
|
|
final SpannableConfiguration configuration = SpannableConfiguration.builder(this)
|
|
.urlProcessor(urlProcessor)
|
|
.build();
|
|
```
|
|
The primary goal of additing this abstraction is to give ability to convert relative urls to absolute ones. If it fits your purpose, then `UrlProcessorRelativeToAbsolute` can be used:
|
|
```java
|
|
final UrlProcessor urlProcessor = new UrlProcessorRelativeToAbsolute("https://this-is-base.org");
|
|
```
|
|
|
|
## Link resolver
|
|
Link resolver is used to navigate to clicked link. By default `LinkResolverDef` is used and it just constructs an `Intent` and launches activity that can handle it, or silently fails if activity cannot be resolved. The main interface:
|
|
```java
|
|
public interface Resolver {
|
|
void resolve(View view, @NonNull String link);
|
|
}
|
|
```
|
|
|
|
## Theme
|
|
`SpannableTheme` controlls the appearance of rendered markdown. It has pretty reasonable defaults, which are established based on style of a TextView to which it is applied. It has some factory methods:
|
|
```java
|
|
// creates ready-to-use SpannableThemeObject
|
|
SpannableTheme.create(Context);
|
|
|
|
// can be used to tweak default appearance
|
|
SpannableTheme.builderWithDefaults(Context);
|
|
|
|
// returns empty builder (no default values are set)
|
|
SpannableTheme.builder();
|
|
|
|
// returns a builder that is instantiated with all values from specified SpannableTheme
|
|
SpannableTheme.builder(SpannableTheme copyFrom);
|
|
```
|
|
|
|
`SpannableTheme.Builder` have these configurations:
|
|
#### Link
|
|
```java
|
|
public Builder linkColor(@ColorInt int linkColor);
|
|
```
|
|
|
|
#### Block
|
|
```java
|
|
// left margin for: lists & quotes (text is shifted)
|
|
public Builder blockMargin(@Dimension int blockMargin);
|
|
```
|
|
|
|
#### Quote
|
|
```java
|
|
// width of quote indication (the `|`)
|
|
public Builder blockQuoteWidth(@Dimension int blockQuoteWidth);
|
|
|
|
// color of `|` quote indication
|
|
public Builder blockQuoteColor(@ColorInt int blockQuoteColor);
|
|
```
|
|
|
|
#### Lists
|
|
```java
|
|
// color of list item bullets(●, ○, ■)/numbers
|
|
public Builder listItemColor(@ColorInt int listItemColor);
|
|
|
|
// stroke width for list bullet (2nd level - `○`)
|
|
public Builder bulletListItemStrokeWidth(@Dimension int bulletListItemStrokeWidth);
|
|
|
|
// width of list bullet (●, ○, ■)
|
|
public Builder bulletWidth(@Dimension int bulletWidth);
|
|
```
|
|
|
|
#### Code
|
|
```java
|
|
// text color for `code` blocks
|
|
public Builder codeTextColor(@ColorInt int codeTextColor);
|
|
|
|
// background color for `code` blocks
|
|
public Builder codeBackgroundColor(@ColorInt int codeBackgroundColor);
|
|
|
|
// left margin for multiline `code` blocks
|
|
public Builder codeMultilineMargin(@Dimension int codeMultilineMargin);
|
|
|
|
// typeface of `code` block
|
|
public Builder codeTypeface(@NonNull Typeface codeTypeface);
|
|
|
|
// text size for `code` block
|
|
public Builder codeTextSize(@Dimension int codeTextSize);
|
|
```
|
|
|
|
#### Headings
|
|
```java
|
|
// height of the `break` line under h1 & h2
|
|
public Builder headingBreakHeight(@Dimension int headingBreakHeight);
|
|
|
|
// color of the `break` line under h1 & h2
|
|
public Builder headingBreakColor(@ColorInt int headingBreakColor);
|
|
```
|
|
|
|
#### SuperScript & SupScript
|
|
```java
|
|
// ratio for <sup> & <sub> text size (calculated based on TextView text size)
|
|
public Builder scriptTextSizeRatio(@FloatRange(from = .0F, to = Float.MAX_VALUE) float scriptTextSizeRatio);
|
|
```
|
|
|
|
#### Thematic break
|
|
```java
|
|
// the `---` thematic break color
|
|
public Builder thematicBreakColor(@ColorInt int thematicBreakColor);
|
|
|
|
// the `---` thematic break height
|
|
public Builder thematicBreakHeight(@Dimension int thematicBreakHeight);
|
|
```
|
|
|
|
#### Tables
|
|
```java
|
|
// padding inside a table cell
|
|
public Builder tableCellPadding(@Dimension int tableCellPadding);
|
|
|
|
// color of table borders
|
|
public Builder tableBorderColor(@ColorInt int tableBorderColor);
|
|
|
|
// the `stroke` width of table border
|
|
public Builder tableBorderWidth(@Dimension int tableBorderWidth);
|
|
|
|
// the background of odd table rows
|
|
public Builder tableOddRowBackgroundColor(@ColorInt int tableOddRowBackgroundColor);
|
|
```
|
|
|
|
|
|
## HTML parser
|
|
As markdown supports HTML to be inlined, we need to introduce another entity that does (limited) parsing. Obtain an instance of `SpannableHtmlParser` via one of these factory methods:
|
|
|
|
```java
|
|
SpannableHtmlParser.create(SpannableTheme, AsyncDrawable.Loader)
|
|
SpannableHtmlParser.create(SpannableTheme, AsyncDrawable.Loader, UrlProcessor, LinkSpan.Resolver)
|
|
```
|
|
|
|
Or, if further tweaking is requered builder methods:
|
|
```java
|
|
// creates empty builder
|
|
SpannableHtmlParser.builder();
|
|
|
|
// creates builder that is set-up to default values
|
|
SpannableHtmlParser.builderWithDefaults(
|
|
@NonNull SpannableTheme theme,
|
|
@Nullable AsyncDrawable.Loader asyncDrawableLoader,
|
|
@Nullable UrlProcessor urlProcessor,
|
|
@Nullable LinkSpan.Resolver resolver
|
|
)
|
|
```
|
|
|
|
Builder with defaults additionally handles these HTML tags:
|
|
* `b`, `strong`
|
|
* `i`, `em`, `cite`, `dfn`
|
|
* `sup`
|
|
* `sub`
|
|
* `u`
|
|
* `del`, `s`, `strike`
|
|
* `a`
|
|
* `img` (only if `AsyncDrawable.Loader` was provided)
|
|
|
|
You can add own simple tags handling (or override default) via:
|
|
```java
|
|
SpannableHtmlParser.Builder.simpleTag(String, SpanProvider)
|
|
```
|
|
|
|
Please note, that not all tags are possible to handle via this. These are so called `void` tags ([link](https://www.w3.org/TR/html51/syntax.html#void-elements)) and so-called `html-blocks` ([link](http://spec.commonmark.org/0.18/#html-blocks)). An exception is made only for `img` tag -> it's possible to handle it via `imageProvider` property in `Builder`
|
|
|
|
[commonmark-java]: https://github.com/atlassian/commonmark-java
|
|
[mil-README]: https://github.com/noties/Markwon/blob/master/library-image-loader/README.md
|