AsciiDocDITA

AsciiDocDITA is a style package for Vale that allows you to validate your AsciiDoc content and identify markup that does not have a direct equivalent in DITA 1.3.

Installation

1. Install the latest available version of Vale as described in the official documentation.

2. Create a .vale.ini file in the main directory of your AsciiDoc project:

   StylesPath = .vale/styles
   MinAlertLevel = warning
   Packages = https://github.com/jhradilek/asciidoctor-dita-vale/releases/latest/download/AsciiDocDITA.zip
   
   [*.adoc]
   BasedOnStyles = AsciiDocDITA

3. Download and install the AsciiDocDITA package:

   vale sync

Usage

• Validate a single AsciiDoc file:

  vale source_file.adoc

• Validate all AsciiDoc files in the current directory:

  vale *.adoc

• Generate a report with each message on an individual line:

  vale --output line *.adoc

  To import this report to a spreadsheet, make sure suggestions are disabled and select a colon (:) as a separator.

• Validate all AsciiDoc files in the current directory and all of its subdirectories:

  vale .

  Note that on larger documentation projects, running vale like this may be slow or even fail with an error if your project uses symbolic links to other directories. To work around this problem, run vale in multiple parallel processes simultaneously, for example:

  find . -type f -name '*.adoc' | xargs -n 1 -P 14 vale --output line

• List suggestions that are normally disabled by setting the MinAlertLevel option to warning in the configuration:

  vale --filter '.Level=="suggestion"' .

• Read the official documentation to learn how to use Vale in an editor such as VSCode, Neovim, or Emacs, or run it as a GitHub action.

Available rules

Errors

The following rules have their severity set to error. The AsciiDoc markup reported by these rules causes the conversion tooling to produce invalid DITA output.

Vale rule	Explanation
EntityReference	DITA 1.3 supports five character entity references defined in the XML standard: &, <, >, ', and ". Replace any other character entity references with an appropriate built-in AsciiDoc attribute.
ExampleBlock	DITA 1.3 allows the <example> element to appear only within the main body of the topic. Do not use example blocks in sections, within other blocks, or as part of lists.
NestedSection	DITA 1.3 allows the <section> element to appear only within the main body of the topic. If a level 2 section is needed, move it to a separate file.
TaskExample	DITA 1.3 allows only one <example> element in a task topic. If multiple examples are needed, combine them in a single example block.
TaskSection	DITA 1.3 does not allow sections in a task topic. If a section is needed, move it to a separate file.

Warnings

The following rules have their severity set to warning. The AsciiDoc markup reported by these rules causes the conversion tooling to issue a warning, but does not produce invalid DITA output.

Vale rule	Explanation
AdmonitionTitle	In DITA 1.3, the <note> element cannot have a title. Do not assign block titles to admonitions.
AssemblyContents	In assemblies, include directives can be followed only by the Additional resources section. Do not place any other contents between or after include directives.
AuthorLine	AsciiDoc interprets the first line that directly follows the document title as an author line. Add an empty line after the document title.
BlockTitle	In DITA 1.3, only the <example>, <fig>, and <table> elements can have a title. Do not assign block titles to other blocks such as paragraphs or lists.
CalloutList	DITA 1.3 does not support callouts. Rewrite your content to avoid the need for callout numbers and replace the explanation with simple sentences, an unordered list, or a description list as appropriate.
ContentType	Without a clear content type definition, the Vale style cannot reliably report problems related to procedure modules such as TaskSection or TaskExample. Add the correct :_mod-docs-content-type: definition at the top of the file.
DiscreteHeading	DITA 1.3 does not support discrete headings. Depending on your use case, use a description list, a level 1 section, or move the content to a separate file.
DocumentId	DITA 1.3 requires topics to have an ID. Assign a valid ID to the document title.
DocumentTitle	DITA 1.3 requires topics to have a title. Add a document title if it is an assembly or a module, or add the :_mod-docs-content-type: SNIPPET definition at the top of the file to mark it as a snippet.
EquationFormula	The conversion tooling does not implement LaTeX and AsciiMath formulas.
LineBreak	DITA 1.3 does not support hard line breaks. Split the text in multiple paragraphs and add the a operator inside of tables.
PageBreak	DITA 1.3 does not support page breaks. If visual separation of the text is needed, rewrite your content without using a page break.
RelatedLinks	In DITA 1.3, the <related-links> element can only contain links. Format additional resources as an unordered list, remove lines that do not contain a link or a cross reference, and remove any text that precedes or follows a link or a cross reference.
ShortDescription	DITA 1.3 supports the <shortdesc> element to provide a short description of the topic. Assigning [role="_abstract"] to a paragraph you want to convert to the <shortdesc> element.
SidebarBlock	DITA 1.3 does not support sidebar content. If visual separation of the text is needed, rewrite your content without using a sidebar block.
TableFooter	DITA 1.3 does not support table footers. Rewrite your content without using a table footer.
TaskContents	To correctly map contents to <steps> or <steps-unordered> in DITA 1.3, all procedure modules must contain the Procedure block title in AsciiDoc.
TaskDuplicate	DITA 1.3 expects task topics to be composed of the following optional elements: <prereq>, <context>, <steps> or <steps-unordered>, <result>, <tasktroubleshooting>, <example>, and <postreq>. These elements directly correspond to the following block titles in AsciiDoc: Prerequisite/Prerequisites, Procedure, Verification/Result/Results, Troubleshooting/Troubleshooting step/Troubleshooting steps, and Next step/Next steps. Because each element can appear only once in a DITA task, duplicate titles are not allowed. Remove any duplicate titles or combine them into one.
TaskStep	DITA 1.3 allows only one <steps> or <steps-unordered> element in a task topic. Verify that any content that follows the Procedure block title is part of a single ordered or unordered list. If any content precedes the steps, move it above the Procedure and Prerequisites block titles. If any content immediately follows the steps, either append it to the last step by using a list continuation, or add the Result or Next steps block title above it.
TaskTitle	DITA 1.3 expects task topics to be composed of the following optional elements: <prereq>, <context>, <steps> or <steps-unordered>, <result>, <tasktroubleshooting>, <example>, and <postreq>. These elements directly correspond to the following block titles in AsciiDoc: Prerequisite/Prerequisites, Procedure, Verification/Result/Results, Troubleshooting/Troubleshooting step/Troubleshooting steps, and Next step/Next steps. In addition, the Additional resources block title directly maps to the <related-links> element. Do not use any other block titles.
ThematicBreak	DITA 1.3 does not support thematic breaks. If visual separation of the text is needed, rewrite your content without using a thematic break.

Suggestions

The following rules have their severity set to suggestion. These are convenience rules and do not report problems with the AsciiDoc markup.

Vale rule	Explanation
AttributeReference	Lists all attribute references in the file. Use this information to decide which attribute definitions to supply during conversion.
ConditionalCode	Lists all ifdef, ifndef, and ifeval conditional statements in the file. Use this information to decide which attribute definitions to supply during conversion.
IncludeDirective	Lists all include directives in the file. Use this information to decide if include directives should be processed during conversion.
TagDirective	Lists all tag directives in the file. Use this information to decide how to approach conditional content after conversion.

Copyright

Copyright © 2025 Jaromir Hradilek

This program is free software, released under the terms of the MIT license. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.