markparsr

package module
v1.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2026 License: MIT Imports: 15 Imported by: 0

README

markparsr Go Reference

A terraform documentation validation tool that keeps README files aligned with their module sources.

Ensures your module docs stay accurate, highlights drift automatically, and provides detailed reporting for reliable infrastructure documentation.

Why markparsr?

Terraform modules evolve rapidly and documentation often lags behind—missing sections, outdated variable descriptions, or stale resource lists create confusion.

Manual auditing is tedious and error-prone.

markparsr helps you:

Validate docs against Terraform source before shipping changes.

Keep documentation aligned with Terraform definitions.

Run lightweight checks in CI/CD for every module.

Support custom sections, provider prefixes, and file requirements.

Automate documentation hygiene across teams and repositories.

Installation

go get github.com/dkooll/markparsr

Usage

See the examples/ directory for sample Terraform modules and validator tests.

Run the Go tests inside examples/usage/ to validate the bundled example module.

Features

README Section Validation

Enforces Terraform-docs sections (Requirements, Providers, Inputs, Outputs, Resources).

Detects missing or misspelled headings with typo-friendly matching.

Extracts items even when headings disappear by leveraging anchors.

HCL ↔ README Consistency

Compares documented variables and outputs with those declared in HCL.

Verifies resources and data sources referenced in the README actually exist in code.

Supports provider prefix configuration for custom naming schemes.

File & URL Checks

Ensures key module files (README, variables.tf, outputs.tf, terraform.tf) are present and non-empty.

Validates URLs in the README respond successfully.

Flexible Configuration

Functional options for additional sections, extra files, provider prefixes, and README paths.

Environment variable overrides for CI/CD (README_PATH, MODULE_PATH, FORMAT, VERBOSE).

Lightweight output suitable for Go test integration and automation.

Configuration

Functional Options

WithFormat(format): Force the markdown format (defaults to document).

WithAdditionalSections(sections...): Require extra documentation sections.

WithAdditionalFiles(files...): Ensure additional files exist beside Terraform defaults.

WithRelativeReadmePath(path): Point to the README when it is not in the module root.

WithProviderPrefixes(prefixes...): Recognize custom resource prefixes.

Environment Variables

README_PATH: Absolute README path when not passed via options.

MODULE_PATH: Module root directory (defaults to the README directory).

FORMAT: Set to document; other values fall back to document mode with a warning.

VERBOSE: When true, prints diagnostic information.

Notes

markparsr assumes Terraform-docs style READMEs with H2/H3 headings and anchor links.

Provider prefixes help resource detection across custom modules and registries.

Run validators in CI to prevent documentation drift before merging.

Contributors

We welcome contributions from the community! Whether it's reporting a bug, suggesting a new feature, or submitting a pull request, your input is highly valued.

Documentation

Overview

Package markparsr provides utilities for validating Terraform module documentation.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ComparisonValidator added in v1.22.0 

type ComparisonValidator interface {
	ValidateItems(tfItems, mdItems []string, itemType string) []error
}

func NewComparisonValidator added in v1.22.0 

func NewComparisonValidator() ComparisonValidator
Example 
tfItems := []string{"var1", "var2"}
mdItems := []string{"var1", "var3"}

validator := NewComparisonValidator()
errs := validator.ValidateItems(tfItems, mdItems, "Variables")

for _, err := range errs {
	fmt.Println(err)
}

type DocumentParser added in v1.22.0 

type DocumentParser interface {
	GetContent() string
	GetAllSections() []string
	HasSection(sectionName string) bool
}

type ErrorCollector added in v1.22.0 

type ErrorCollector struct {
	// contains filtered or unexported fields
}

func (*ErrorCollector) Add added in v1.22.0 

func (c *ErrorCollector) Add(err error)

func (*ErrorCollector) AddMany added in v1.22.0 

func (c *ErrorCollector) AddMany(errs []error)

func (*ErrorCollector) Errors added in v1.22.0 

func (c *ErrorCollector) Errors() []error

func (*ErrorCollector) HasErrors added in v1.22.0 

func (c *ErrorCollector) HasErrors() bool

type FileReader added in v1.22.0 

type FileReader interface {
	ReadFile(path string) ([]byte, error)
}

type FileValidator 

type FileValidator struct {
	// contains filtered or unexported fields
}

func NewFileValidator 

func NewFileValidator(readmePath string, modulePath string, additionalFiles []string) *FileValidator

func (*FileValidator) Validate 

func (fv *FileValidator) Validate() []error

type HCLParser added in v1.22.0 

type HCLParser interface {
	ParseHCL(content []byte, filename string) (*hcl.File, hcl.Diagnostics)
}

type ItemValidator 

type ItemValidator struct {
	// contains filtered or unexported fields
}

func NewItemValidator 

func NewItemValidator(markdown *MarkdownContent, terraform *TerraformContent, itemType, blockType string, sections []string, fileName string) *ItemValidator

func (*ItemValidator) Validate 

func (iv *ItemValidator) Validate() []error

type MarkdownContent 

type MarkdownContent struct {
	// contains filtered or unexported fields
}

func NewMarkdownContent 

func NewMarkdownContent(data string, format MarkdownFormat, providerPrefixes []string) *MarkdownContent

func (*MarkdownContent) ExtractResourcesAndDataSources 

func (mc *MarkdownContent) ExtractResourcesAndDataSources() ([]string, []string, error)

func (*MarkdownContent) ExtractSectionItems 

func (mc *MarkdownContent) ExtractSectionItems(sectionNames ...string) []string

func (*MarkdownContent) GetAllSections 

func (mc *MarkdownContent) GetAllSections() []string

func (*MarkdownContent) GetContent 

func (mc *MarkdownContent) GetContent() string

func (*MarkdownContent) HasSection 

func (mc *MarkdownContent) HasSection(sectionName string) bool

type MarkdownFormat 

type MarkdownFormat string
const (
	FormatDocument MarkdownFormat = "document"
)

type Option 

type Option func(*Options)

func WithAdditionalFiles 

func WithAdditionalFiles(files ...string) Option

func WithAdditionalSections 

func WithAdditionalSections(sections ...string) Option

func WithFormat 

func WithFormat(format MarkdownFormat) Option

func WithProviderPrefixes added in v1.21.0 

func WithProviderPrefixes(prefixes ...string) Option

func WithRelativeReadmePath 

func WithRelativeReadmePath(path string) Option

type Options 

type Options struct {
	Format             MarkdownFormat
	AdditionalSections []string
	AdditionalFiles    []string
	ReadmePath         string
	ProviderPrefixes   []string
}

type ReadmeValidator 

type ReadmeValidator struct {
	// contains filtered or unexported fields
}

func NewReadmeValidator 

func NewReadmeValidator(opts ...Option) (*ReadmeValidator, error)

func (*ReadmeValidator) GetFormat 

func (rv *ReadmeValidator) GetFormat() MarkdownFormat

func (*ReadmeValidator) Validate 

func (rv *ReadmeValidator) Validate() []error

type ResourceDocumentExtractor added in v1.22.0 

type ResourceDocumentExtractor interface {
	ExtractResourcesAndDataSources() ([]string, []string, error)
}

type ResourceExtractor added in v1.22.0 

type ResourceExtractor interface {
	ExtractResourcesAndDataSources() ([]string, []string, error)
	ExtractItems(filePath, blockType string) ([]string, error)
}

type SectionExtractor added in v1.22.0 

type SectionExtractor interface {
	ExtractSectionItems(sectionNames ...string) []string
}

type SectionValidator 

type SectionValidator struct {
	// contains filtered or unexported fields
}

func NewSectionValidator 

func NewSectionValidator(content *MarkdownContent, additionalSections []string) *SectionValidator

func (*SectionValidator) Validate 

func (sv *SectionValidator) Validate() []error

type StringUtils added in v1.22.0 

type StringUtils interface {
	LevenshteinDistance(s1, s2 string) int
	IsSimilarSection(found, expected string) bool
}

func NewStringUtils added in v1.22.0 

func NewStringUtils() StringUtils

type TerraformContent 

type TerraformContent struct {
	// contains filtered or unexported fields
}

func NewTerraformContent 

func NewTerraformContent(modulePath string) (*TerraformContent, error)

func (*TerraformContent) ExtractItems 

func (tc *TerraformContent) ExtractItems(filePath, blockType string) ([]string, error)
Example 
tmpDir := os.TempDir()
varsFile := filepath.Join(tmpDir, "example_vars.tf")

content := `
variable "name" {
  type = string
}

variable "location" {
  type = string
}
`
if err := os.WriteFile(varsFile, []byte(content), 0o644); err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}
defer os.Remove(varsFile)

tc, _ := NewTerraformContent(tmpDir)
items, _ := tc.ExtractItems(varsFile, "variable")

for _, item := range items {
	fmt.Println(item)
}

func (*TerraformContent) ExtractModuleItems added in v1.22.0 

func (tc *TerraformContent) ExtractModuleItems(blockType string) ([]string, error)

func (*TerraformContent) ExtractResourcesAndDataSources 

func (tc *TerraformContent) ExtractResourcesAndDataSources() ([]string, []string, error)

type TerraformDefinitionValidator 

type TerraformDefinitionValidator struct {
	// contains filtered or unexported fields
}

func NewTerraformDefinitionValidator 

func NewTerraformDefinitionValidator(markdown *MarkdownContent, terraform *TerraformContent) *TerraformDefinitionValidator

func (*TerraformDefinitionValidator) Validate 

func (tdv *TerraformDefinitionValidator) Validate() []error

type URLValidator 

type URLValidator struct {
	// contains filtered or unexported fields
}

func NewURLValidator 

func NewURLValidator(content *MarkdownContent) *URLValidator

func (*URLValidator) Validate 

func (uv *URLValidator) Validate() []error

type Validator 

type Validator interface {
	Validate() []error
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.