Custom schemas

You can create a custom plug-in to set different configuration options for Markdown parsing and conversion to DITA. Custom Markdown schema configurations can be defined using the Java ServiceLoader class.

The service type interface com.elovirta.dita.markdown.SchemaProvider has two methods:

  • isSupportedSchema(URI) — check whether schema URI is supported by this provider.
  • createMarkdownParser(URI) — create MarkdownParser instance for given schema. We suggest returning a configured MarkdownParserImpl instance.

Example

Sample customization for urn:acme:dita:custom schema.

Create a src/main/java/com/acme/AcmeSchemaProvider.java class that extends SchemaProvider to define a scheme and what customization options it uses:

package com.acme;

import com.elovirta.dita.markdown.DitaRenderer;
import com.elovirta.dita.markdown.MarkdownParser;
import com.elovirta.dita.markdown.MarkdownParserImpl;
import com.elovirta.dita.markdown.SchemaProvider;
import com.vladsch.flexmark.ext.abbreviation.AbbreviationExtension;
import com.vladsch.flexmark.ext.anchorlink.AnchorLinkExtension;
import com.vladsch.flexmark.ext.attributes.AttributesExtension;
import com.vladsch.flexmark.ext.autolink.AutolinkExtension;
import com.vladsch.flexmark.ext.definition.DefinitionExtension;
import com.vladsch.flexmark.ext.footnotes.FootnoteExtension;
import com.vladsch.flexmark.ext.gfm.strikethrough.StrikethroughSubscriptExtension;
import com.vladsch.flexmark.ext.ins.InsExtension;
import com.vladsch.flexmark.ext.jekyll.tag.JekyllTagExtension;
import com.vladsch.flexmark.ext.superscript.SuperscriptExtension;
import com.vladsch.flexmark.ext.tables.TablesExtension;
import com.vladsch.flexmark.ext.yaml.front.matter.YamlFrontMatterExtension;
import com.vladsch.flexmark.parser.Parser;
import com.vladsch.flexmark.util.data.MutableDataSet;

import java.net.URI;

import static java.util.Arrays.asList;

public class AcmeSchemaProvider implements SchemaProvider {
    private static final URI SCHEMA = URI.create("urn:acme:dita:custom.xsd");

    @Override
    public boolean isSupportedSchema(URI schema) {
        return SCHEMA.equals(schema);
    }

    @Override
    public MarkdownParser createMarkdownParser(URI schema) {
        return new MarkdownParserImpl(new MutableDataSet()
                // See https://github.com/vsch/flexmark-java/wiki/Extensions
                .set(Parser.EXTENSIONS, asList(
                        AbbreviationExtension.create(),
                        AnchorLinkExtension.create(),
                        AttributesExtension.create(),
                        FootnoteExtension.create(),
                        InsExtension.create(),
                        JekyllTagExtension.create(),
                        SuperscriptExtension.create(),
                        TablesExtension.create(),
                        AutolinkExtension.create(),
                        YamlFrontMatterExtension.create(),
                        DefinitionExtension.create(),
                        StrikethroughSubscriptExtension.create()))
                .set(DefinitionExtension.TILDE_MARKER, false)
                .set(TablesExtension.COLUMN_SPANS, true)
                .set(TablesExtension.APPEND_MISSING_COLUMNS, false)
                .set(TablesExtension.DISCARD_EXTRA_COLUMNS, true)
                .set(TablesExtension.HEADER_SEPARATOR_COLUMN_MATCH, true)
                // See https://github.com/jelovirt/org.lwdita/wiki/Custom-schemas
                .set(DitaRenderer.FIX_ROOT_HEADING, false)
                .set(DitaRenderer.SHORTDESC_PARAGRAPH, false)
                .set(DitaRenderer.ID_FROM_YAML, false)
                .set(DitaRenderer.LW_DITA, false)
                .set(DitaRenderer.SPECIALIZATION, false)
                .set(DitaRenderer.SPECIALIZATION_CONCEPT, false)
                .set(DitaRenderer.SPECIALIZATION_TASK, false)
                .set(DitaRenderer.SPECIALIZATION_REFERENCE, false)
                .toImmutable());
    }
}

To make AcmeSchemaProvider discoverable, create a provider configuration file src/test/resources/META-INF/services/com.elovirta.dita.markdown.SchemaProvider:

com.acme.AcmeSchemaProvider

A sample project is available in the org.lwdita-sample GitHub project repository. It contains a Gradle build to compile the code and package it into a DITA-OT plug-in.

The following configuration options can be specified in custom schemas:

Parsing

Static FieldDefaultDescription
DitaRenderer.FIX_ROOT_HEADINGfalseIf root heading is missing, generate based on title key from YAML header or filename.

Conversion to DITA

Static FieldDefaultDescription
DitaRenderer.SHORTDESC_PARAGRAPHfalseConvert first paragraph to shortdesc.
DitaRenderer.TIGHT_LISTtrueSupport tight lists.
DitaRenderer.ID_FROM_YAMLfalseUse id key from YAML header for topic @id.
DitaRenderer.LW_DITAfalseConvert to XDITA instead of DITA. Deprecated, use DitaRenderer.MDITA_EXTENDED_PROFILE instead.
DitaRenderer.SPECIALIZATIONfalseConvert to concept/task/reference if root heading has matching class.
DitaRenderer.SPECIALIZATION_CONCEPTfalseConvert to DITA concept.
DitaRenderer.SPECIALIZATION_TASKfalseConvert to DITA task.
DitaRenderer.SPECIALIZATION_REFERENCEfalseConvert to DITA concept.
DitaRenderer.MDITA_CORE_PROFILEfalseParse as MDITA core profile and convert to XDITA.
DitaRenderer.MDITA_EXTENDED_PROFILEfalseParse as MDITA extended profile and convert to XDITA.
DitaRenderer.MAPfalseConvert to DITA map.