DOCSEARCHbyAlgolia
Submit Docs

flexmark-java

repository·master·Indexed 25 days ago

https://github.com/vsch/flexmark-java

A high-performance Java implementation of the CommonMark spec providing an extensible Markdown parser and HTML renderer. It features a detailed AST for tracking source positions, utilities for tree iteration via flexmark-tree-iteration, and support for DOCX conversion and Pegdown migration. The library requires Java 8 or above.

Tokens
12.9K
Snippets
16
Records
92
Agent score
82%

What's inside flexmark-java

  1. Overview of flexmark-tree-iteration

    master
    The flexmark-tree-iteration module (specifically the tree-iteration-util) provides utilities for iterating over tree structure elements, such as a Markdown AST. It allows for recursive traversal with the ability to filter nodes based on their class or attributes, and provides mechanisms to convert nodes to other types.

  2. Configure flexmark-java for Android Studio

    master

    When using flexmark-java in Android Studio, you must exclude certain duplicate metadata files in your packagingOptions to avoid build errors.

    packagingOptions {
    exclude 'META-INF/LICENSE-LGPL-2.1.txt'
    exclude 'META-INF/LICENSE-LGPL-3.txt'
    exclude 'META-INF/LICENSE-W3C-TEST'
    exclude 'META-INF/DEPENDENCIES'
}

  3. Migrate flexmark-java from 0.40.x to 0.42.0 in IntelliJ

    master

    To upgrade from version 0.40.x to 0.42.0, use the IntelliJ migration tool:

    Steps:

    1. Copy the migration file [migrate flexmark-java 0_40_x to 0_42_0] to your IntelliJ application settings migration subdirectory.
    2. Close your current project in IntelliJ.
    3. Open your project in IntelliJ Ultimate or Community.
    4. Update your flexmark-java dependency version to 0.42.0 (or later).
    5. Use the menu Refactor > Migrate....
    6. Select migrate flexmark-java 0.40.x to 0.42.0.
    7. Press Run and click Do Refactor in the preview window.

  5. Use Admonition syntax for block-styled side content

    master

    The flexmark-ext-admonition extension allows you to create block-styled side content using syntax compatible with the Material for MkDocs Admonition extension.

    Block-Styled Side Content

    Use !!! followed by a qualifier and an optional title.

    !!! qualifier "Optional Title"
    block content

    No-Heading Content

    To create a block without a title, use an empty string for the title.

    !!! qualifier ""
    block content

  6. Migrate flexmark-java 0.35.x to 0.40.0 in IntelliJ

    master

    To upgrade from version 0.35.x to 0.40.0 or later using IntelliJ IDEA, follow these steps:

    1. Copy the migration file migrate flexmark-java 0.35.x to 0.40.0.xml to your IntelliJ application settings migrations subdirectory.
    2. Close any open projects.
    3. Open your project in IntelliJ (Ultimate or Community).
    4. Update your flexmark-java dependency version to 0.40.0 or later and ensure the library is downloaded/updated.
    5. Use the menu Refactor > Migrate....
    6. Select migrate flexmark-java 0.35.x to 0.40.0.
    7. Press Run.
    8. In the refactoring preview tool window, click Do Refactor.

    Note: The IDE may miss some class migrations, especially in files that are not currently open. If migrations are not applied, try re-running the process. Common classes requiring manual editing if the migration fails include:

    • com.vladsch.flexmark.ast.Document $\rightarrow$ com.vladsch.flexmark.util.ast.Document
    • com.vladsch.flexmark.ast.Node $\rightarrow$ com.vladsch.flexmark.util.ast.Node
    • com.vladsch.flexmark.formatter.internal.Formatter $\rightarrow$ com.vladsch.flexmark.formatter.Formatter

  7. Migrate to BasedSequence and RichSequence (v0.59.42)

    master

    In version 0.59.42, BasedSequence.append(CharSequence[]) now constructs a segmented sequence to enforce proper ordering. This will throw an IllegalArgumentException if the condition is not met.

    Workaround: To achieve the old functionality (where segments were simply concatenated), create an appended string of all sequences first, then use BasedSequence.of(string).

  8. Use enumerated references for element anchors and bookmarks

    master

    To create an anchor or bookmark for an element, use the {#type:reference} syntax immediately following the element.

    • type: A category used to maintain separate numbering (e.g., fig, tbl). Note: type must not start with a digit.
    • reference: A unique identifier for the element within that category.

    The resulting anchor ID will be type:reference.

  9. Migrate from Pegdown using PegdownOptionsAdapter

    master

    If you are migrating from the pegdown parser, use the PegdownOptionsAdapter class (available in the flexmark-profile-pegdown module) to convert Pegdown extension flags into flexmark options.

    To emulate Pegdown's HTML block parsing behavior (which is less strict than flexmark's default), use the flexmarkOptions(boolean strictHtml, int extensions) method with strictHtml set to true.

    import com.vladsch.flexmark.html.HtmlRenderer;
import com.vladsch.flexmark.parser.Parser;
import com.vladsch.flexmark.profile.pegdown.Extensions;
import com.vladsch.flexmark.profile.pegdown.PegdownOptionsAdapter;
import com.vladsch.flexmark.util.data.DataHolder;

public class PegdownOptions {
     // Emulate pegdown with all extensions
     final private static DataHolder OPTIONS = PegdownOptionsAdapter.flexmarkOptions(
            Extensions.ALL
    );

    // Emulate pegdown with all extensions AND strict HTML block parsing
    final private static DataHolder STRICT_OPTIONS = PegdownOptionsAdapter.flexmarkOptions(true, 
            Extensions.ALL
    );

    static final Parser PARSER = Parser.builder(OPTIONS).build();
    static final HtmlRenderer RENDERER = HtmlRenderer.builder(OPTIONS).build();
}

  10. Use PositionList and Position for stable list iteration

    master

    A PositionList<T> provides a way to track elements in a list using Position<T> objects. This allows you to maintain a reference to an element's location even when the underlying list is modified (elements added or removed).

    Key behaviors:

    • Stable Iteration: Using the positions() iterable allows for stable iteration. Inserting elements immediately after the current position during forward iteration (or before during reverse iteration) will not increase the iteration count.
    • Relative Offsets: All position operations use an offset from the current element. Offsets can be negative or positive, provided the resulting absolute index is within the range [0, size()).
    • Handling Modifications:
      • If an element is removed, Position.isValidElement() will return false (the position will have a 0 span).
      • If the element still exists, getIndex() returns its current index, and methods like get(), get(0), set(value), and set(0, value) operate on that element.
      • If the element was removed, the position returns the index where the element was located.

  11. Configure AsideExtension options

    master

    To ensure AsideExtension behaves independently of block quote options, you should set its options explicitly. This prevents changes to block quote settings from unintentionally altering aside block parsing.

    Recommended explicit settings for default behavior:

    options.set(EXTEND_TO_BLANK_LINE, false);
options.set(IGNORE_BLANK_LINE, false);
options.set(ALLOW_LEADING_SPACE, true);
options.set(INTERRUPTS_PARAGRAPH, true);
options.set(INTERRUPTS_ITEM_PARAGRAPH, true);
options.set(WITH_LEAD_SPACES_INTERRUPTS_ITEM_PARAGRAPH, true);