Leveraging the new schemaProvider mechanism

[kirkilj]

I want to have a discussion area to help ourselves and others leverage the new schemaProvider mechanism. Perhaps some of this discussion can be used to supplement the existing documentation if needed. I'd also like Syncrosoft to comment since we'd need a way for Oxygen to somehow use our schema providers as well for validation, rendering, authoring of Markdown content. Previously I used the DITA-OT Slack group to ask such questions, but it probably belongs here.

[kirkilj]

Since no information design has been done on any of our R&D Markdown files, they can all be considered generic DITA topics at this point. However, when we start requiring the R&D authors to choose task, concept, reference, troubleshooting, etc., would it be best practice to create one Schema provider for all of the topic types or to create one for each topic type. It looks like you already have URNs for the various topic types.

Questions for @jelovirt:

1. There's also the prior mechanism of putting a class on the first H1, such as {.task}, so how would you recommend we apply these two mechanisms? Are they mutually exclusive?
2. Since all of the existing Markdown content can be considered to be generic topics, we can just start with a schemaProvider for that, and make sure the default behavior still works for us using a single topic provider, but I'd just like to know how you'd recommend we proceed after that when we start to specialize further.

[kirkilj]

We've created a local repo based on the https://github.com/jelovirt/org.lwdita-sample project and are configuring it to use our internal Artifactory server that contains a GitHub mirror for selected dependency repos since our Jenkins CI is isolated from the public Internet. We use Maven for the great majority of our dependency management and lifecycle management, so we're just learning how to map our practices onto Gradle. We use NPM for our React and Node.js work of course, so we're not completely new to an alternative to Maven.

Since the lwdita-sample, doesn't have a unit test scaffold in place, we're also setting up our own, based on the LwDITA repo's use of JUnit5 and the practice of comparing Markdown to DITA conversion output to a baseline for test results.

[jelovirt]

You don't have to use Gradle, you can make the project using Maven.

[kirkilj]

Thanks @jelovirt, we've got the Gradle config working now with our Artifactory server, but it's good to know that we can build and test either way.

Btw, I edited my 2nd post above to make my 2 questions to you more visible.

[raducoravu]

Adding what I answered @kirkilj on the Slack channel below about Oxygen XML specific functionality (validation, rendering, authoring of custom markdown):
We do not have the APIs for this (yet). If you manage to get something working on the publishing part as a DITA OT plugin maybe you can email us for an improvement request and we can think about how we could do this.
But besides Markdown editing with preview, we also have Markdown to DITA conversions which use a patched lw dita jar, so yes things will be complicated.
How do you plan to use Oxygen in general? I assume your engineers will write in markdown? And Oxygen will be used by the tech writers as a tool to double check the received Markdown content and see how it would convert to DITA before publishing?

[kirkilj]

Hi @raducoravu,

re: things will be complicated... I expected no less. ;)

Our R&D authors use VS-Code for authoring Markdown content, where linting rules and vale are used to warn against any Markdown source that will fail the Markdown to DITA gauntlet. The dockerized version of our DITA-OT is used to trigger OT builds on certain Markdown workflow conditions.

Our DITA technical writers use Oxygen to author the DITA content and load Markdown repo content as Git submodules. R&D's current Markdown review tool leverages Gitlab's merge request facility which is configured so only technical writers can approve any changes to customer-facing Markdown content. The technical writers will need to be able to make changes to the Markdown content, in Oxygen if possible, so they won't have to install and use VS-Code and all the extensions that are needed for authoring there.

Our first POC is simply enabling the Markdown admonition extension, since it is as simple as a one line change, and it will prove whether our build scripts can produce artifacts that can be used in our DITA-OT deployments. Currently, the admonitions are not parsed and rendered as DITA in Oxygen's LwDITA framework, but it's working in our dev environment.

We'll send you our plugin project as soon as it's sharable.