DemaConsulting.DictionaryMark 0.1.0-beta.1

DictionaryMark

Markdown Dictionary Generation Tool

Overview

DictionaryMark is a .NET command-line tool that reads YAML dictionary files and generates formatted Markdown output as either bullet lists or tables. It supports glob patterns for processing multiple files, detects conflicting definitions, and is designed for easy integration into documentation pipelines.

Features

• 📄 YAML Dictionary Input - Read term/definition pairs from YAML files
• 📝 Markdown Output - Generate bullet lists or formatted tables
• 🔍 Glob Patterns - Process multiple input files with wildcards
• ⚔️ Conflict Detection - Detect conflicting definitions across files
• 🎯 Customizable Output - Control headings, column headers, sort order, and depth
• 🌐 Multi-Platform - Windows, Linux, and macOS on .NET 8, 9, and 10
• ✅ Self-Validation - Built-in qualification tests for regulated environments

Installation

Prerequisites

• .NET SDK 8.0, 9.0, or 10.0

Global Installation

Install DictionaryMark as a global .NET tool for system-wide use:

dotnet tool install --global DemaConsulting.DictionaryMark

Verify the installation:

dictionarymark --version

Local Installation

Install DictionaryMark as a local tool in your project (recommended for team projects):

dotnet new tool-manifest  # if you don't have a tool manifest already
dotnet tool install DemaConsulting.DictionaryMark

Run the tool:

dotnet dictionarymark --version

Update

To update to the latest version:

# Global installation
dotnet tool update --global DemaConsulting.DictionaryMark

# Local installation
dotnet tool update DemaConsulting.DictionaryMark

Compatibility

Usage

Options

Quick Start Examples

Generate a bullet list from a YAML dictionary:

dictionarymark --input glossary.yaml

Generate a table with a section heading:

dictionarymark --input glossary.yaml --format table --section "Glossary" --output docs/glossary.md

Merge multiple files and sort alphabetically:

dictionarymark --input file1.yaml --input file2.yaml --sort alpha

Process all YAML files in a directory:

dictionarymark --input "terms/*.yaml" --format table --output docs/glossary.md

Example

Given an input file glossary.yaml:

API: Application Programming Interface
CLI: Command-Line Interface
SDK: Software Development Kit

Running:

dictionarymark --input glossary.yaml --format table --section "Glossary" --depth 1

Produces:

# Glossary

| Term | Definition |
| :--- | :--- |
| API | Application Programming Interface |
| CLI | Command-Line Interface |
| SDK | Software Development Kit |

Or with --format bullets:

# Glossary

- **API**: Application Programming Interface
- **CLI**: Command-Line Interface
- **SDK**: Software Development Kit

Self-Validation

DictionaryMark includes a built-in self-validation mode for use in regulated environments where tool qualification evidence is required.

dictionarymark --validate

The validation report includes system information (tool version, OS, .NET runtime) and the results of each self-test. Each test proves a specific capability:

• DictionaryMark_VersionDisplay - --version flag outputs a valid version string
• DictionaryMark_HelpDisplay - --help flag outputs usage and options text
• DictionaryMark_BulletGeneration - Bullet list is generated correctly from YAML input
• DictionaryMark_TableGeneration - Markdown table is generated correctly from YAML input
• DictionaryMark_CustomHeaders - --term-header and --def-header override column text
• DictionaryMark_ConflictDetection - Conflicting definitions across files are detected

Results can be saved to a file:

dictionarymark --validate --results results.trx   # TRX (MSTest) format
dictionarymark --validate --results results.xml   # JUnit XML format

On validation failure the tool will exit with a non-zero exit code.

Project Practices

The DictionaryMark repository itself follows these development practices:

• 🔍 Linting Enforcement - markdownlint, cspell, and yamllint enforced on every CI run
• 📋 Continuous Compliance - Compliance evidence generated automatically on every CI run, following the Continuous Compliance methodology
• ☁️ SonarCloud Integration - Quality gate and security analysis on every build
• 🔗 Requirements Traceability - Requirements linked to passing tests with auto-generated trace matrix

Contributing

Contributions are welcome! We appreciate your interest in improving DictionaryMark.

Please see our Contributing Guide for development setup, coding standards, and submission guidelines. Also review our Code of Conduct for community guidelines.

For bug reports, feature requests, and questions, please use GitHub Issues.

License

This project is licensed under the MIT License - see the LICENSE file for details.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

Support

• 🐛 Report Bugs: GitHub Issues
• 💡 Request Features: GitHub Issues
• ❓ Ask Questions: GitHub Discussions
• 🤝 Contributing: Contributing Guide

Security

For security concerns and vulnerability reporting, please see our Security Policy.

Acknowledgements

DictionaryMark is built with the following open-source projects:

• .NET - Cross-platform framework for building applications
• YamlDotNet - YAML parsing library for .NET
• Microsoft.Extensions.FileSystemGlobbing - Glob pattern matching for file system paths
• DemaConsulting.TestResults - TRX and JUnit XML test results library