Update clarity-formatter.md #1807
Conversation
There was a problem hiding this comment.
Pull request overview
This PR attempts to update the Clarity Formatter documentation, but the changes introduce severe markdown formatting issues that render the document broken and unreadable. The update removes all markdown syntax including heading symbols (#), bullet points, code block delimiters, and table formatting, converting what was a properly formatted documentation file into plain text that will not render correctly.
Changes:
- Removed all markdown heading symbols (# and ##) from section headers
- Eliminated all code block delimiters (triple backticks) causing code examples to display incorrectly
- Stripped table pipe delimiters making comparison and CLI options tables unreadable
- Added new content including CLI options table, additional resources section, and important notes section
- Added an inappropriate editorial note at the beginning of the document
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| You can customize these defaults to match your preferences. | ||
| Integration points | ||
| The Clarity formatter is available through two primary tools: | ||
| Clarity VS Code Extension |
There was a problem hiding this comment.
The heading syntax is missing the markdown hash symbols. It should be "### Clarity VS Code Extension" to maintain proper heading hierarchy (as a subsection under Integration points).
| Clarity VS Code Extension | |
| ### Clarity VS Code Extension |
|
|
||
| ## Best practices | ||
| Comparison table | ||
| AspectManual formattingClarity formatterConsistencyVaries by developerUniform across the codebaseSpeedTime-consumingInstantError-proneYesNoTeam coordinationRequires a style guideAutomatic enforcement |
There was a problem hiding this comment.
The table formatting is broken. This line appears to be a table that has lost all markdown pipe delimiters (|), making it unreadable. The table should use proper markdown table syntax with pipes separating columns and header/body separator rows.
| clarity(let ( | ||
| (a u1) | ||
| (b u2) | ||
| ) | ||
| (body-expression) | ||
| ) |
There was a problem hiding this comment.
The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.
| # Preview formatting changes without modifying files | ||
| clarinet format --dry-run | ||
| CLI options | ||
| OptionShortDescriptionRequired--checkCheck if code is formatted without modifying filesNo--dry-runOnly echo the result of formattingNo--in-placeReplace the contents of a file with the formatted codeNo--file <path>Specify a specific file to formatNo |
There was a problem hiding this comment.
The table formatting is broken. This line appears to be a table that has lost all markdown pipe delimiters (|), making it unreadable. The table should use proper markdown table syntax with pipes separating columns and header/body separator rows.
| clarity;; @format-ignore | ||
| (define-constant something (list | ||
| 1 2 3 ;; Preserves custom spacing | ||
| 4 5 )) |
There was a problem hiding this comment.
The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.
| clarity(define-read-only (get-balance (who principal)) | ||
| (ok u0) | ||
| ) |
There was a problem hiding this comment.
The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.
|
|
||
| ### Tuples and maps | ||
|
|
||
| Tuples and maps |
There was a problem hiding this comment.
The heading syntax is missing the markdown hash symbols. It should be "### Tuples and maps" to maintain proper heading hierarchy (as a subsection under Formatting rules in detail).
| Tuples and maps | |
| ### Tuples and maps |
| Formatter README – Detailed technical documentation about the formatter | ||
| Official documentation – Visit the Stacks documentation for comprehensive guides | ||
|
|
||
| Important notes |
There was a problem hiding this comment.
The heading syntax is missing the markdown hash symbols. It should be "## Important notes" to maintain proper heading hierarchy.
| Important notes | |
| ## Important notes |
| Line length – wraps lines at 80 characters by default | ||
| Indentation – uses two spaces for consistency | ||
| Structure – enforces consistent patterns for functions, let bindings, and control flow |
There was a problem hiding this comment.
The bullet point formatting has been removed. These lines should use markdown list syntax with asterisks (*) or dashes (-) to create proper bullet points for better readability.
| Format on demand | ||
| Format selection (format only highlighted code) | ||
|
|
||
| Clarinet CLI |
There was a problem hiding this comment.
The heading syntax is missing the markdown hash symbols. It should be "### Clarinet CLI" to maintain proper heading hierarchy (as a subsection under Integration points).
| Clarinet CLI | |
| ### Clarinet CLI |
1 participant
Description
Describe the changes that were made in this pull request. When possible start with the motivations behind the change.