Package icyllis.modernui.markflow

Class Markflow

java.lang.Object
icyllis.modernui.markflow.Markflow
@Immutable public final class Markflow extends Object
Entry point of Markdown API, it provides a context for parsing and rendering Markdown. Markdown parsed and rendered by the same Markflow object is done in the same manner.

Note that Markflow does not provide any caching for parsing and rendering. Each call to parse(java.lang.CharSequence) and render(org.commonmark.node.Node) will create an instance for tracking internal states. Therefore they are also thread-safe and can be done in any background thread.

To display a Markdown document on the screen, you need to follow the following steps:

  1. Call parse(CharSequence) with the raw Markdown input (treated as plain text) to obtain a tree of nodes.
  2. Call render(Node) with the tree of nodes to obtain a text with styling spans, which is also known as rendered Markdown.
  3. Call setRenderedMarkdown(TextView, Spanned) to install the rendered Markdown to a TextView on UI thread. Then TextView will then be responsible for creating text layout and the render node for multi-frame rendering.
For convenience, convert(CharSequence) can be used to parse invalid input: '&' render Markdown, this method can be called from any thread. setMarkdown(TextView, CharSequence) can be used to parse invalid input: '&' render invalid input: '&' install Markdown, but it can only be called from UI thread.

Note that: Once a TextView installs Markdown text through Markflow, it must also be uninstalled using the same Markflow.

Since:
3.12

  • Method Details

    • create

      @NonNull public static Markflow create(@NonNull Context context)
      Create a minimal Markflow instance with the default theme and the core plugin. Only core Markdown features are enabled, and images will not be resolved.
      Parameters:
      context - view context
      Returns:
      a new Markflow instance with only core plugin registered

    • builder

      @NonNull public static Markflow.Builder builder(@NonNull Context context)
      Create a new instance of Markflow.Builder with core plugin registered.
      Parameters:
      context - view context
      Returns:
      a new Builder instance with core plugin registered

    • builder

      @NonNull public static Markflow.Builder builder(@NonNull Context context, boolean withCore)
      Create a new instance of Markflow.Builder, optionally with core plugin registered.
      Parameters:
      context - view context
      withCore - whether to register core plugin
      Returns:
      a new Builder instance

    • parse

      @NonNull public org.commonmark.node.Node parse(@NonNull CharSequence input)
      Parse the input Markdown text into AST.

      This method is thread-safe and allows multiple threads to start parsings for different source text concurrently.

      Parameters:
      input - the Markdown text to parse
      Returns:
      the root document, can be cast to Document

    • render

      @NonNull public Spanned render(@NonNull org.commonmark.node.Node document)
      Render the tree of nodes to a Spanned text, which can be handled by framework's text layout engine.

      This method is thread-safe and allows multiple threads to start renderings for different documents concurrently.

      Note that returned Spanned has few limitations. For example, images, tables and ordered lists require TextView to be properly displayed. Ordered list items require text layout based on TextView's parameters. Whenever possible use setMarkdown(TextView, CharSequence) or setRenderedMarkdown(TextView, Spanned) as these methods will additionally call specific MarkflowPlugin methods to prepare proper display.

      Parameters:
      document - the root node
      Returns:
      the rendered Markdown

    • convert

      @NonNull public Spanned convert(@NonNull CharSequence input)
      This is a helper method, calling this method is the same as calling parse(CharSequence) and then render(Node). See render(Node) for details.
      Parameters:
      input - the raw Markdown text
      Returns:
      the rendered Markdown

    • setMarkdown

      @UiThread public void setMarkdown(@NonNull TextView textView, @NonNull CharSequence markdown)
      This is a helper method, calling this method is the same as calling parse(CharSequence) then render(Node), and then setRenderedMarkdown(TextView, Spanned).

      In most cases, you just need this to display Markdown, when Markdown is static and small. Note that you should not change TextView typography attributes after calling this.

      This method can be called only from UI thread.

    • setRenderedMarkdown

      @UiThread public void setRenderedMarkdown(@NonNull TextView textView, @NonNull Spanned markdown)
      Install a rendered Markdown to the given TextView.

      This method can be called only from UI thread.

      Parameters:
      textView - the target text view used to display the Markdown
      markdown - the rendered Markdown to display

    • getPlugin

      @Nullable public <P extends MarkflowPlugin> P getPlugin(@NonNull Class<P> type)
      Requests information if certain plugin has been registered.

    • requirePlugin

      @NonNull public <P extends MarkflowPlugin> P requirePlugin(@NonNull Class<P> type)
      Requests information for certain plugin. Throws an exception if the plugin is not registered.
      See Also:

    • getAllPlugins

      @NonNull public @UnmodifiableView List<? extends MarkflowPlugin> getAllPlugins()
      Returns an immutable view of all registered plugins, sorted by dependencies.

    • getConfig

      @NonNull public MarkflowConfig getConfig()