{"id":26163501,"url":"https://github.com/jlevy/flowmark","last_synced_at":"2025-04-14T14:09:30.149Z","repository":{"id":276841661,"uuid":"930475655","full_name":"jlevy/flowmark","owner":"jlevy","description":"Better auto-formatting for Markdown and plaintext","archived":false,"fork":false,"pushed_at":"2025-03-10T17:10:10.000Z","size":101,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T17:16:43.711Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-10T17:35:58.000Z","updated_at":"2025-03-10T17:10:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"e1be56a7-5cb1-40c0-bae8-669b45031fc5","html_url":"https://github.com/jlevy/flowmark","commit_stats":null,"previous_names":["jlevy/flowmark"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fflowmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fflowmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fflowmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fflowmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlevy","download_url":"https://codeload.github.com/jlevy/flowmark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243050934,"owners_count":20228100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-11T14:27:22.740Z","updated_at":"2025-04-14T14:09:30.125Z","avatar_url":"https://github.com/jlevy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flowmark\n\nFlowmark is a new Python implementation of **text and Markdown line wrapping and\nfilling**, with an emphasis on making **git diffs** and **LLM edits** to text documents\neasier to diff and review.\n\nIn addition, it offers **Markdown auto-formatting and normalization** as a library or\nfrom the command line.\nThis is much like [markdownfmt](https://github.com/shurcooL/markdownfmt) or\n[prettier's Markdown support](https://prettier.io/blog/2017/11/07/1.8.0) but is pure\nPython and has (in my humble opinion) better options and defaults.\n\n## Installation\n\nThe simplest way to use the tool is to use [uv](https://github.com/astral-sh/uv).\nThen run `uvx flowmark --help`.\n\nTo install the command-line properly:\n\n```shell\nuv tool install flowmark\n```\n\nOr [pipx](https://github.com/pypa/pipx):\n\n```shell\npipx install flowmark\n```\n\nThen\n\n```\nflowmark --help\n```\n\nTo use as a library, use uv/poetry/pip to install\n[`flowmark`](https://pypi.org/project/flowmark/).\n\n## Use in VSCode/Cursor\n\nYou can use Flowmark to auto-format Markdown on save in VSCode or Cursor.\nInstall the \"Run on Save\" (`emeraldwalk.runonsave`) extension.\nThen add to your `settings.json`:\n\n```json\n  \"emeraldwalk.runonsave\": {\n    \"commands\": [\n        {\n            \"match\": \"\\\\.md$\",\n            \"cmd\": \"flowmark --auto ${file}\"\n        }\n    ]\n  }\n```\n\nThe `--auto` option is just the same as `--inplace --nobackup --semantic`.\n\n## Use Cases\n\nThe main ways to use Flowmark are:\n\n- To **autoformat Markdown on save in VSCode/Cursor** or any other editor that supports\n  running a command on save.\n  Flowmark uses a readable format that makes diffs easy to read and use on GitHub.\n  It also normalizes all Markdown syntax variations (such as different header or\n  formatting styles). This can be especially useful for documentation and editing\n  workflows where clean diffs and minimal merge conflicts on GitHub are important.\n\n- As a **command line formatter** to format text or Markdown files using the `flowmark`\n  command.\n\n- As a **library to autoformat Markdown**. For example, it is great to normalize the\n  outputs from LLMs to be consistent, or to run on the inputs and outputs of LLM\n  transformations that edit text, so that the resulting diffs are clean.\n  Having this as a simple Python library makes this easy in AI-related document\n  pipelines.\n\n- As a **drop-in replacement library for Python's default\n  [`textwrap`](https://docs.python.org/3/library/textwrap.html)** but with more options.\n  It simplifies and generalizes that library, offering better control over **initial and\n  subsequent indentation** and **when to split words and lines**, e.g. using a word\n  splitter that won't break lines within HTML tags.\n\nOther features:\n\n- Flowmark has the option to to use **semantic line breaks** (using a heuristic to break\n  lines on sentences sentences when that is reasonable), which is an underrated feature\n  that can **make diffs on GitHub much more readable**. The the change may seem subtle\n  but avoids having paragraphs reflow for very small edits, which does a lot to\n  **minimize merge conflicts**. An example of what sentence-guided wrapping looks like,\n  see the\n  [Markdown source](https://github.com/jlevy/flowmark/blob/main/README.md?plain=1) of\n  this readme file.)\n\n- Very simple and fast **regex-based sentence splitting**. It's just based on letters\n  and punctuation so isn't perfect but works well for these purposes (and is much faster\n  and simpler than a proper sentence parser like SpaCy).\n  It should work fine for English and many other latin/Cyrillic languages but hasn't\n  been tested on CJK.\n\nIt aims to be small and simple and have only a few dependencies, currently only\n[`marko`](https://github.com/frostming/marko),\n[`regex`](https://pypi.org/project/regex/), and\n[`strif`](https://github.com/jlevy/strif).\n\nBecause **YAML frontmatter** is common on Markdown files, the Markdown autoformat\npreserves all frontmatter (content between `---` delimiters at the front of a file).\n\n## Why a New Markdown Formatter?\n\nPreviously I'd implemented something very similar with\n[for Atom](https://github.com/jlevy/atom-flowmark).\nI found the Markdown formatting conventions enforced by the that plugin worked really\nwell for editing and publishing large or collaboratively edited documents.\n\nThis is new, pure Python implementation.\nThere are numerous needs for a tool like this on the command line and in Python.\n\nWith LLM tools now using Markdown everywhere, there are enormous advantages to having\nvery clean and well-formatted Markdown documents, since you can then cleanly see diffs\nor edits made by LLMs.\n\nIf you are in a workspace where you are editing lots of text, having them all be\nMarkdown with frontmatter, auto-formatted for every git commit makes for a *much* better\nexperience.\n\n## Usage\n\nFlowmark can be used as a library or as a CLI.\n\n```\n$ flowmark --help\nusage: flowmark [-h] [-o OUTPUT] [-w WIDTH] [-p] [-s] [-i] [--nobackup] [file]\n\nFlowmark: Better line wrapping and formatting for plaintext and Markdown\n\npositional arguments:\n  file                 Input file (use '-' for stdin)\n\noptions:\n  -h, --help           show this help message and exit\n  -o, --output OUTPUT  Output file (use '-' for stdout)\n  -w, --width WIDTH    Line width to wrap to\n  -p, --plaintext      Process as plaintext (no Markdown parsing)\n  -s, --semantic       Enable sentence-based line breaks (only applies to Markdown mode)\n  -i, --inplace        Edit the file in place (ignores --output)\n  --nobackup           Do not make a backup of the original file when using --inplace\n\nFlowmark provides enhanced text wrapping capabilities with special handling for\nMarkdown content. It can:\n\n- Format Markdown with proper line wrapping while preserving structure\n  and normalizing Markdown formatting\n\n- Optionally break lines at sentence boundaries for better diff readability\n\n- Process plaintext with HTML-aware word splitting\n\nIt is both a library and a command-line tool.\n\nCommand-line usage examples:\n\n  # Format a Markdown file to stdout\n  flowmark README.md\n\n  # Format a Markdown file and save to a new file\n  flowmark README.md -o README_formatted.md\n\n  # Edit a file in-place (with or without making a backup)\n  flowmark --inplace README.md\n  flowmark --inplace --nobackup README.md\n\n  # Process plaintext instead of Markdown\n  flowmark --plaintext text.txt\n\n  # Use sentences to guide line breaks (good for many purposes git history and diffs)\n  flowmark --semantic README.md\n\nFor more details, see: https://github.com/jlevy/flowmark\n```\n\nFor instructions on publishing to PyPI, see [publishing.md](publishing.md).\n\n* * *\n\n*This project was built from\n[simple-modern-uv](https://github.com/jlevy/simple-modern-uv).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fflowmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlevy%2Fflowmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fflowmark/lists"}