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

Command line

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
   
   # The rules below are based on recommended practices and do not prevent
   # successful conversion to DITA.  If your product is not bound by these
   # guidelines, uncomment the following lines to disable them:
   #AsciiDocDITA.CalloutList = NO
   #AsciiDocDITA.ShortDescription = NO
   #AsciiDocDITA.ConceptLink = NO

3. Download and install the AsciiDocDITA package:

   vale sync

GitHub workflows

To set up a workflow to validate all relevant files in a specific branch:

1. Copy the workflows/dita-main.yml file to the .github/workflows/ directory in your GitHub repository.

2. Optional: Customize the list of branches to run the workflow on (default: main). For example, to run the workflow on dev and experimental:

   # Customize the list of branches to run this workflow on:
   branches:
     - dev
     - experimental

3. Optional: Customize the discovery of relevant AsciiDoc files (default: all *.adoc files). For example, to ignore the README.adoc file:

   # Customize the discovery of relevant files:
   - name: Discover files
     run: find . -type f -name '*.adoc' -not -name 'README.adoc' > RELEVANT_FILES

To set up a workflow to validate only files modified in a pull request:

1. Copy the workflows/dita-pull.yml file to the .github/workflows/ directory in your GitHub repository.

2. Optional: Customize the list of target branches for pull requests (default: main). For example, to run the workflow on pull request that target the dev branch:

   # Customize the list of target branches for pull requests:
   branches:
     - dev

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.
MismatchedId	The opening and closing quote in a custom ID assignment must match. Make sure you use the same single quote or double quote on both sides of the ID.
NestedSection	DITA 1.3 allows the <section> element to appear only within the main body of the topic, not inside of another <section>. If a level 2 section (===) is needed, create a dedicated topic for it.
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.
ConceptLink	To improve content usability and user focus, links and cross references in the main body of a concept topic are discouraged. If the links and cross references are needed, move them to the Additional resources section.
ContentType	Without a clear content type definition, the Vale style cannot reliably report problems relevant for specific topic types. 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. Assign [role="_abstract"] to the 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.
TaskInclude	DITA 1.3 allows only one <steps> or <steps-unordered> element in a task topic. Because Vale is only able to validate files that are explicitly supplied to it, verify that the content that is imported from a separate file by using the include directive results in a single ordered or unordered list.
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.

Recognized content types

To report problems relevant for specific topic types, the Vale rules recognize the following :_mod-docs-content-type: attribute definition values:

Value	Explanation
ASSEMBLY	Identifies the AsciiDoc file as a modular documentation assembly. This implies that the assembly file follows the modular documentation guidelines and in addition to include directives, it contains a title and an introduction.
ATTRIBUTES	Identifies the AsciiDoc file as an attribute definition file. This implies that the file is only used to provide attribute definitions and does not contain any printable content.
CONCEPT	Identifies the AsciiDoc file as a modular documentation concept module.
PROCEDURE	Identifies the AsciiDoc file as a modular documentation procedure module.
REFERENCE	Identifies the AsciiDoc file as a modular documentation reference module.
SNIPPET	Identifies the AsciiDoc file as a modular documentation text snippet.

For example, to identify an AsciiDoc file as an attribute definition file:

:_mod-docs-content-type: ATTRIBUTES

Copyright

Copyright © 2025, 2026 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.