Skip to content
Last updated

recheck

Introduction

The recheck command lints Markdown files for prose and structure problems. It checks headings, sentences, links, images, and Markdoc tags against a set of rules.

Rules come from presets, such as recheck/markdown, that you add to the root extends in redocly.yaml. The recheck block adjusts those rules. With no redocly.yaml, the command uses recheck/markdown. With a redocly.yaml that has neither, the command checks nothing and says so. The command reads the root recheck config; settings under apis.<name> are not used.

Usage

redocly recheck
redocly recheck <paths>...
redocly recheck [--fix]
redocly recheck [--readability]
redocly recheck [--generate-baseline]
redocly recheck [--generate-markdoc-schema] [--from=<path>...] [--output=<path>] [--check]
redocly recheck --help
One action per run

--readability, --generate-baseline, and --generate-markdoc-schema each replace the default lint action. Use at most one of them in a run. --fix works with the default lint action only.

Options

OptionTypeDescription
paths[string]Files or directories to lint. Default value is the current directory.
--checkbooleanFail when the generated schema differs from the file in --output. Use with --generate-markdoc-schema.
--configstringPath to the configuration file.
--fixbooleanApply fixes to the Markdown files. Alias: -f.
--formatstringFormat for the report.
Possible values: table, json, sarif, github-actions. Default value is table.
--from[string]Module paths to read Markdoc tags from. Use with --generate-markdoc-schema.
--generate-baselinebooleanWrite a baseline file from the current errors.
--generate-markdoc-schemabooleanGenerate a Markdoc tag schema from theme modules. Needs --from and --output.
--helpbooleanShow help.
--lint-configstringSpecify the severity level for the configuration file.
Possible values: warn, error, off. Default value is warn.
--max-problemsnumberMaximum number of problems in the report; applies to every format.
--outputstringOutput file for the generated schema.
--readabilitybooleanReport readability scores instead of lint findings.
--rule[string]Run only these rules. Alias: -r.
--skip-rule[string]Skip these rules.
--statsbooleanPrint statistics per rule. Alias: -s.
--summarystringPrint a summary of the run.
Possible values: json, text.
--summary-pathstringWrite the summary to this file.
--tags[string]Run only rules with these tags.
--versionbooleanShow version number.

Examples

Lint a folder

Add a preset to the root extends:

extends:
  - recheck/markdown

Then run the command on a folder:

redocly recheck docs

The command lints every Markdown file under docs with the rules from recheck/markdown. The report goes to stdout and progress messages go to stderr.

Turn off a rule

Set the rule to off in the recheck block:

extends:
  - recheck/markdown
recheck:
  rules:
    recheck/line-length: off

The run applies every rule from recheck/markdown except recheck/line-length.

Annotate a pull request

redocly recheck docs --format=github-actions

In a GitHub Actions workflow, this format adds each finding as an annotation on the changed line. An error becomes ::error, a warning ::warning, and an info finding ::notice. Each finding is one line of output:

::error title=recheck/single-h1,file=docs/index.md,line=2,endLine=2,col=1,endColumn=1::Multiple top-level headings in the same document

Use a baseline

A baseline records the current errors. Later runs report only errors that the baseline does not list.

redocly recheck docs --generate-baseline

The command writes .redocly.recheck-baseline.yaml next to redocly.yaml. Commit the file. Later runs pick it up automatically.

After you fix errors, generate the baseline again and commit the smaller file.

Check readability

redocly recheck docs --readability

The command prints readability scores for each Markdown file instead of lint findings.

drift