Markdown Dictionary Generation Tool
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.
- 📄 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
- .NET SDK 8.0, 9.0, or 10.0
Install DictionaryMark as a global .NET tool for system-wide use:
dotnet tool install --global DemaConsulting.DictionaryMarkVerify the installation:
dictionarymark --versionInstall 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.DictionaryMarkRun the tool:
dotnet dictionarymark --versionTo update to the latest version:
# Global installation
dotnet tool update --global DemaConsulting.DictionaryMark
# Local installation
dotnet tool update DemaConsulting.DictionaryMark| Component | Version | Status |
|---|---|---|
| .NET SDK | 8.0 | ✅ Supported |
| .NET SDK | 9.0 | ✅ Supported |
| .NET SDK | 10.0 | ✅ Supported |
| OS | Windows | ✅ Supported |
| OS | Linux | ✅ Supported |
| OS | macOS | ✅ Supported |
| Option | Description |
|---|---|
-v, --version |
Display version information |
-?, -h, --help |
Display help |
--silent |
Suppress console output |
--validate |
Run self-validation |
-i, --input <pattern> |
Input YAML file or glob pattern (repeatable) |
-o, --output <file> |
Output Markdown file (default: stdout) |
-f, --format <format> |
Output format: bullets (default) or table |
-s, --section <heading> |
Section heading text |
--term-header <header> |
Term column header for table format (default: Term) |
--def-header <header> |
Definition column header (default: Definition) |
--sort <order> |
Sort order: file (default) or alpha |
--log <file> |
Write output to log file |
--results <file> |
Write validation results (.trx or .xml) |
--result <file> |
Alias for --results |
--depth <n> |
Set heading depth (default: 1) |
Generate a bullet list from a YAML dictionary:
dictionarymark --input glossary.yamlGenerate a table with a section heading:
dictionarymark --input glossary.yaml --format table --section "Glossary" --output docs/glossary.mdMerge multiple files and sort alphabetically:
dictionarymark --input file1.yaml --input file2.yaml --sort alphaProcess all YAML files in a directory:
dictionarymark --input "terms/*.yaml" --format table --output docs/glossary.mdGiven an input file glossary.yaml:
API: Application Programming Interface
CLI: Command-Line Interface
SDK: Software Development KitRunning:
dictionarymark --input glossary.yaml --format table --section "Glossary" --depth 1Produces:
# 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 KitDictionaryMark includes a built-in self-validation mode for use in regulated environments where tool qualification evidence is required.
dictionarymark --validateThe 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---versionflag outputs a valid version stringDictionaryMark_HelpDisplay---helpflag outputs usage and options textDictionaryMark_BulletGeneration- Bullet list is generated correctly from YAML inputDictionaryMark_TableGeneration- Markdown table is generated correctly from YAML inputDictionaryMark_CustomHeaders---term-headerand--def-headeroverride column textDictionaryMark_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 formatOn validation failure the tool will exit with a non-zero exit code.
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
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.
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.
- 🐛 Report Bugs: GitHub Issues
- 💡 Request Features: GitHub Issues
- ❓ Ask Questions: GitHub Discussions
- 🤝 Contributing: Contributing Guide
For security concerns and vulnerability reporting, please see our Security Policy.
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