Fix markdownlint issues in keyset pagination design doc#196
Conversation
Reviewer's GuideThis PR cleans up markdownlint violations in the keyset pagination design doc by disabling long-line checks inline, normalizing all fenced code blocks with proper language annotations and removing stray artifacts, and adjusts the markdownlint config to ignore Terraform directories. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Summary by CodeRabbit
WalkthroughAdd a global ignore pattern for any Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API as HTTP API
participant Service as Pagination Service
participant Repo as Repository
Client->>API: GET /users?limit=...&cursor=...
API->>Service: Cursor::decode(cursor)
Service->>Repo: query with key boundary + direction
Repo-->>Service: results (<= limit + 1)
Service->>Service: determine next/prev cursors
Service->>Service: Cursor::encode(new cursors)
Service-->>API: Paginated<T> + PaginationLinks
API-->>Client: 200 PaginatedUsersResponse
sequenceDiagram
autonumber
participant Client
participant CursorOps as Cursor::encode/decode
Client->>CursorOps: request encode(Cursor{dir, key})
CursorOps->>CursorOps: serde JSON -> base64url
CursorOps-->>Client: cursor string
Client->>CursorOps: provide cursor string
CursorOps->>CursorOps: base64url -> parse JSON
CursorOps-->>Client: Cursor{dir, key}
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
.markdownlint-cli2.jsonc(1 hunks)docs/keyset-pagination-design.md(16 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
docs/**/*.md
📄 CodeRabbit inference engine (docs/documentation-style-guide.md)
docs/**/*.md: Use British English based on the Oxford English Dictionary (en-oxendict) in documentation
The word “outwith” is acceptable in documentation
Use the Oxford comma
Treat company names as collective nouns (e.g., “Lille Industries are…”)
Write headings in sentence case
Use Markdown headings (#, ##, ###, …) in order without skipping levels
Follow markdownlint recommendations
Provide code blocks and lists using standard Markdown syntax
Always provide a language identifier for fenced code blocks; use plaintext for non-code text
Use '-' as the first-level bullet and renumber lists when items change
Prefer inline links using text or angle-bracketed URLs
Ensure blank lines before and after bulleted lists and fenced code blocks
Ensure tables have a delimiter line below the header row
Expand any uncommon acronym on first use (e.g., Continuous Integration (CI))
Wrap paragraphs at 80 columns
Wrap code at 120 columns (within documentation)
Do not wrap tables
Use footnotes referenced with [^label]
Include Mermaid diagrams where they add clarity
When embedding figures, use Markdown image syntaxand provide brief, descriptive alt text
Add a short description before each Mermaid diagram for screen readers
docs/**/*.md: Use docs/ as the source of truth for requirements, dependencies, and architectural decisions, and proactively update it when things change
Documentation in docs/ must use en-GB-oxendict spelling and grammar (LICENSE naming is exempt)
Keep TypeScript examples in docs small and compilable (typecheck during builds); mirror production patterns
Files:
docs/keyset-pagination-design.md
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/*.md: Validate Markdown with make markdownlint; wrap paragraphs/bullets at 80 columns, code blocks at 120, do not wrap tables/headings; use dashes for bullets and GFM footnotes
Run make fmt after documentation changes to format Markdown and fix table markup; validate Mermaid diagrams with make nixie
Files:
docs/keyset-pagination-design.md
⚙️ CodeRabbit configuration file
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-GB-oxendict (-ize / -yse / -our) spelling and grammar
- Headings must not be wrapped.
- Documents must start with a level 1 heading
- Headings must correctly increase or decrease by no more than one level at a time
- Use GitHub-flavoured Markdown style for footnotes and endnotes.
- Numbered footnotes must be numbered by order of appearance in the document.
Files:
docs/keyset-pagination-design.md
docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (docs/contents.md)
Follow the Documentation style guide for all Markdown-based documentation
Files:
docs/keyset-pagination-design.md
🔍 Remote MCP Deepwiki, Ref
Additional Context for PR #196 Review
-
Markdownlint Rule MD013 (Line Length)
- Rule MD013 enforces a maximum line length.
- To suppress MD013 inline, the syntax is:
<!-- markdownlint-disable MD013 --> <!-- markdownlint-enable MD013 -->
- This allows selectively ignoring long lines within a document.
-
.markdownlint-cli2.jsonc Configuration
- The PR adds:
"ignores": [ ".terraform/**", "**/.terraform/**" ]
- This ensures that any
.terraformdirectory at any depth is excluded from lint checks, preventing Terraform artifacts from causing errors.
- The PR adds:
-
Fenced Code Block Language Declarations
- Markdownlint recommends specifying a language for each code fence to enable proper linting and syntax highlighting.
- The PR updates all fenced blocks in
docs/keyset-pagination-design.mdaccordingly (e.g.,rust,json).
-
Impact on Keyset Pagination Doc
- Inline MD013 suppression is scoped to the necessary sections, ensuring long example URLs or formatted code aren’t flagged while preserving line-length checks elsewhere.
- All other lint rules remain enforced, improving doc consistency without altering content semantics.
⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Sourcery review
- GitHub Check: build
|
|
||
| ``` | ||
| bashCopy code`"next": "/api/users?cursor=eyJkaXIiOiJOZXh0Iiwia2V5eyJjcmVhdGVkX2F0Ijoi2023... | ||
| ` | ||
| ```bash | ||
| "next": "/api/users?cursor=eyJkaXIiOiJOZXh0Iiwia2V5eyJjcmVhdGVkX2F0Ijoi2023... | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Fix the fenced code block language.
Align the language tag with the snippet. The block shows a JSON fragment, not a Bash command, so keep markdownlint happy by switching to json (or plaintext). As per coding guidelines
-```bash
+```json
"next": "/api/users?cursor=eyJkaXIiOiJOZXh0Iiwia2V5eyJjcmVhdGVkX2F0Ijoi2023...
```🤖 Prompt for AI Agents
In docs/keyset-pagination-design.md around lines 176 to 180, the fenced code
block is labeled as bash but contains a JSON fragment; change the code fence
language tag from bash to json (or plaintext) so the block is correctly
highlighted and markdownlint-compliant.
Wrap the markdown to satisfy markdownlint MD013 without disabling the rule globally, and fix fenced code blocks to use JSON and text annotations where appropriate.
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
docs/keyset-pagination-design.md (1)
297-299: Fix incorrect fence language for JSON fragment.Label the snippet as JSON to satisfy markdownlint and improve readability. As per coding guidelines
-```bash +```json "next": "/api/users?cursor=eyJkaXIiOiJOZXh0Iiwia2V5eyJjcmVhdGVkX2F0Ijoi2023...</blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: CodeRabbit UI **Review profile**: ASSERTIVE **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between df961ac84149cae20c337729fbe3a1b44a6d2bbe and 1261b6ac91170b640734deb8d4d45ebe6eb77b3f. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `docs/keyset-pagination-design.md` (9 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (3)</summary> <details> <summary>docs/**/*.md</summary> **📄 CodeRabbit inference engine (docs/documentation-style-guide.md)** > `docs/**/*.md`: Use British English based on the Oxford English Dictionary (en-oxendict) in documentation > The word “outwith” is acceptable in documentation > Use the Oxford comma > Treat company names as collective nouns (e.g., “Lille Industries are…”) > Write headings in sentence case > Use Markdown headings (#, ##, ###, …) in order without skipping levels > Follow markdownlint recommendations > Provide code blocks and lists using standard Markdown syntax > Always provide a language identifier for fenced code blocks; use plaintext for non-code text > Use '-' as the first-level bullet and renumber lists when items change > Prefer inline links using [text](url) or angle-bracketed URLs > Ensure blank lines before and after bulleted lists and fenced code blocks > Ensure tables have a delimiter line below the header row > Expand any uncommon acronym on first use (e.g., Continuous Integration (CI)) > Wrap paragraphs at 80 columns > Wrap code at 120 columns (within documentation) > Do not wrap tables > Use footnotes referenced with [^label] > Include Mermaid diagrams where they add clarity > When embedding figures, use Markdown image syntax  and provide brief, descriptive alt text > Add a short description before each Mermaid diagram for screen readers > > `docs/**/*.md`: Use docs/ as the source of truth for requirements, dependencies, and architectural decisions, and proactively update it when things change > Documentation in docs/ must use en-GB-oxendict spelling and grammar (LICENSE naming is exempt) > Keep TypeScript examples in docs small and compilable (typecheck during builds); mirror production patterns Files: - `docs/keyset-pagination-design.md` </details> <details> <summary>**/*.md</summary> **📄 CodeRabbit inference engine (AGENTS.md)** > `**/*.md`: Validate Markdown with make markdownlint; wrap paragraphs/bullets at 80 columns, code blocks at 120, do not wrap tables/headings; use dashes for bullets and GFM footnotes > Run make fmt after documentation changes to format Markdown and fix table markup; validate Mermaid diagrams with make nixie Files: - `docs/keyset-pagination-design.md` --- **⚙️ CodeRabbit configuration file** > `**/*.md`: * Avoid 2nd person or 1st person pronouns ("I", "you", "we") > * Use en-GB-oxendict (-ize / -yse / -our) spelling and grammar > * Headings must not be wrapped. > * Documents must start with a level 1 heading > * Headings must correctly increase or decrease by no more than one level at a time > * Use GitHub-flavoured Markdown style for footnotes and endnotes. > * Numbered footnotes must be numbered by order of appearance in the document. Files: - `docs/keyset-pagination-design.md` </details> <details> <summary>docs/**/*.{md,mdx}</summary> **📄 CodeRabbit inference engine (docs/contents.md)** > Follow the Documentation style guide for all Markdown-based documentation Files: - `docs/keyset-pagination-design.md` </details> </details><details> <summary>🔍 Remote MCP Ref</summary> Summary of additional relevant facts for PR #196 review - PR metadata: open PR #196 on leynos/wildside, branch codex/run-make-fmt-and-fix-markdownlint-errors → main; author leynos; created 2025-10-11T09:09:36Z. - Markdownlint change: .markdownlint-cli2.jsonc adds ignores entries for ".terraform/**" and "**/.terraform/**" (intended to exclude Terraform directories at any depth). This prevents Terraform artifacts from triggering markdownlint failures. - MD013 suppression: docs/keyset-pagination-design.md now contains inline markdownlint MD013 disable/enable comments to scope line-length rule suppression to required sections (so long example lines are exempt while line-length is still enforced elsewhere). Verify the disable/enable are correctly placed and only cover intended regions. - Fenced code blocks: All fenced blocks in docs/keyset-pagination-design.md were annotated with explicit language identifiers (e.g., ```rust, ```json) and stray copy/paste artifacts were removed—confirm language tags are accurate for each block and that no content changed semantically. - Testing steps listed in PR: run make fmt and bun x markdownlint-cli2 docs/keyset-pagination-design.md. Recommend running these locally to confirm no remaining lint failures. Sources used - PR page for leynos/wildside PR #196 (review and diff): </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)</summary> * GitHub Check: build </details> <details> <summary>🔇 Additional comments (1)</summary><blockquote> <details> <summary>docs/keyset-pagination-design.md (1)</summary><blockquote> `3-4`: **Scope MD013 correctly; good.** Keep the disable/enable paired and scoped. Verify it covers the intended long‑line section only. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| - **Opaque Cursors:** The cursor tokens will not expose internal IDs or SQL offsets. Instead, they will be **base64url-encoded JSON** strings that the server interprets([1](https://github.com/leynos/wildside/issues/52#L19-L24)). Clients should treat them as opaque. | ||
|
|
||
| - **No Total Counts:** We will **avoid returning total item counts** in the response([1](https://github.com/leynos/wildside/issues/52#L19-L24)) to prevent expensive `COUNT(*)` queries on large tables. Clients can detect the end of data by the absence of a `next` link. | ||
| ## Overview and Goals |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Write headings in sentence case.
Lowercase non‑proper nouns. As per coding guidelines
-## Overview and Goals
+## Overview and goals📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Overview and Goals | |
| ## Overview and goals |
🤖 Prompt for AI Agents
In docs/keyset-pagination-design.md around line 6, the heading "Overview and
Goals" uses title case; change it to sentence case by lowercasing non-proper
nouns so it reads "Overview and goals" to comply with the project's style
guidelines.
| ```text | ||
| <base64-opaque-token> | ||
| ``` |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Use 'plaintext' for non‑code fences.
Replace text with plaintext per docs style. As per coding guidelines
-```text
+```plaintext
<base64-opaque-token>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In docs/keyset-pagination-design.md around lines 122 to 124 the fenced block
uses text which violates docs style; replace the fence language token from text to plaintext so the block reads plaintext, keep the inner content
unchanged and ensure closing fence stays ``` to follow the style guideline.
</details>
<!-- fingerprinting:phantom:triton:chinchilla -->
<!-- This is an auto-generated comment by CodeRabbit -->
| - **Object format:** e.g. | ||
| `{"dir":"Next","key":{"created_at":"2025-10-10T19:17:56Z","id":"<uuid>"}}`. | ||
| This is more verbose but self-describing and robust if we extend the key with | ||
| additional fields later. We favor this **object format** for clarity and | ||
| extensibility, at the cost of a slightly longer token. | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Use en‑GB spelling.
Change “favor” → “favour”. As per coding guidelines
- additional fields later. We favor this **object format** for clarity and
+ additional fields later. We favour this **object format** for clarity and📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Object format:** e.g. | |
| `{"dir":"Next","key":{"created_at":"2025-10-10T19:17:56Z","id":"<uuid>"}}`. | |
| This is more verbose but self-describing and robust if we extend the key with | |
| additional fields later. We favor this **object format** for clarity and | |
| extensibility, at the cost of a slightly longer token. | |
| - **Object format:** e.g. | |
| `{"dir":"Next","key":{"created_at":"2025-10-10T19:17:56Z","id":"<uuid>"}}`. | |
| This is more verbose but self-describing and robust if we extend the key with | |
| additional fields later. We favour this **object format** for clarity and | |
| extensibility, at the cost of a slightly longer token. |
🤖 Prompt for AI Agents
In docs/keyset-pagination-design.md around lines 268 to 273, the text uses US
spelling "favor"; update it to en‑GB spelling by replacing "favor" with "favour"
(and scan nearby text for any other US/UK inconsistencies to keep the document
consistent). Ensure the sentence reads "...We favour this **object format** for
clarity and extensibility..." with no other changes.
1 participant
Summary
.terraformdirectories so Terraform artifacts no longer trigger lint failuresTesting
https://chatgpt.com/codex/tasks/task_e_68ea15c3cfc88322b9a5d6be7e019b0f
Summary by Sourcery
Fix markdownlint issues in the keyset pagination design document by adding an inline suppression for line-length linting, cleaning up code fences with language identifiers, and configuring the linter to ignore Terraform artifacts
Documentation:
Chores: