[Improvement] Define a standard for Markdown document formatting
- Dominant language
- Java
- Stars
- 3.2k
- Forks
- 935
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 339
Description
## Summary
Design-document reviews keep spending time on Markdown formatting, especially unaligned tables, because `design-docs/` has no written format standard and no shared lint environment.
## Desired outcome
Adopt markdownlint defaults as the standard, record only a few overrides, and enforce them with rumdl: local Gradle blocking, CI warn-only until a follow-up formats existing docs and turns CI blocking.
## Scope and boundaries
- **In scope**: `design-docs/**/*.md` in Apache Gravitino.
- **Non-goal**: product `docs/`, RFCs, or Enterprise docs in this first pass.
- **Non-goal**: a custom Gravitino Markdown aesthetic. Accept markdownlint defaults and override only where design docs already conflict.
- **Unchanged**: design-doc section structure; Apache license HTML comment as the first block.
## Acceptance criteria
- A Markdown document in `design-docs/` states the standard (defaults plus overrides).
- `.rumdl.toml` implements that document from markdownlint defaults.
- `./gradlew markdownlint` fails on violations (local blocking).
- CI on `design-docs/**` reports the same findings as warnings and does not fail the job.
- A later PR formats existing design docs, attaches the task to `check`, and makes CI blocking.
## How should we improve?
Ship the standard and warn-first CI now. Do not rewrite every existing table in the first PR.
- **Syntax**: GitHub Flavored Markdown
- **Default**: markdownlint `default: true`
- **Tables**: aligned pipes (Santilli / MD060)
- **Overrides**: MD013 120 and skip tables/code; MD040 off for ASCII diagrams; MD055 leading-and-trailing pipes
- **Runner**: rumdl, pinned and downloaded by Gradle so local and CI use the same binary
- **Local**: `./gradlew markdownlint` blocking; `./gradlew markdownlintFormat` to fix
- **CI**: same Gradle task with `-Pmarkdownlint.failOn=never`
Nevin
Sent from my 🤖 (Cursor)
Contributor guide
Research direction
Start with the existing design-docs/**/*.md scope and locate the Gradle and CI configuration used for markdown checks. Add the standard document and .rumdl.toml, wire the blocking markdownlint and markdownlintFormat tasks, and configure CI for warn-only findings. Done means the stated acceptance criteria pass without rewriting existing design documents.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- build-system, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100