@upstatement/twix-linux-x64 0.1.3 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
-# Twix
+# Twix 🌱🍫
 
-A formatter for Twig templates with HTML.
+An opinionated formatter for [Twig](https://twig.symfony.com/) templating engine. **Entirely coded with Claude.**
 
 ## Installation
 
@@ -8,28 +8,154 @@ A formatter for Twig templates with HTML.
 npm install --save-dev @upstatement/twix
 ```
 
+Or download the binary directly from [GitHub Releases](https://github.com/Upstatement/twix/releases).
+
 ## Usage
 
 ```bash
 # Format a file (in-place)
-npx twix path/to/file.twig
+twix path/to/file.twig
 
 # Format multiple files
-npx twix "src/**/*.twig"
+twix "src/**/*.twig"
 
 # Check if files are formatted (exit 1 if not)
-npx twix --check path/to/file.twig
+twix --check path/to/file.twig
 
 # Format from stdin
-cat file.twig | npx twix --stdin
+cat file.twig | twix --stdin
+```
+
+## Configuration
+
+Create a `.twixrc.json` or `twix.config.json` file in your project root:
+
+```json
+{
+  "indentSize": 2,
+  "indentStyle": "space",
+  "printWidth": 80,
+  "customTags": {
+    "block": ["if"],
+    "inline": ["set"],
+    "intermediate": ["else"]
+  }
+}
 ```
 
+### Options
+
+| Option                    | Type     | Default   | Description                                                               |
+| ------------------------- | -------- | --------- | ------------------------------------------------------------------------- |
+| `indentSize`              | number   | `2`       | Number of spaces or tabs per indentation level                            |
+| `indentStyle`             | string   | `"space"` | Use `"space"` or `"tab"` for indentation                                  |
+| `printWidth`              | number   | `80`      | Maximum line width before wrapping attributes                             |
+| `customTags.block`        | string[] | `[]`      | Custom Twig block tags (tags with bodies, e.g., `{% if %}...{% endif %}`) |
+| `customTags.inline`       | string[] | `[]`      | Custom Twig inline tags (self-closing, e.g., `{% set = ... %}`)           |
+| `customTags.intermediate` | string[] | `[]`      | Custom intermediate tags (like `{% else %}` or `{% case %}`)              |
+
+### Built-in Tag Support
+
+**Block tags** (have a body and `{% end* %}` tag):
+
+- Standard Twig: `if`, `for`, `block`, `set`, `apply`, `autoescape`, `embed`, `filter`, `macro`, `sandbox`, `verbatim`, `with`
+- Craft CMS: `switch`, `cache`, `js`, `css`, `nav`, `paginate`, `tag`
+
+**Inline tags** (self-closing):
+
+- Standard Twig: `extends`, `include`, `use`, `import`, `from`, `do`, `flush`, `deprecated`
+- Craft CMS: `exit`, `header`, `redirect`, `requireLogin`, `requireAdmin`, `requireGuest`, `requirePermission`
+
+**Intermediate tags** (appear within blocks):
+
+- `else`, `elseif`, `case`, `default`
+
 ## Features
 
-- **AST-based formatting** - Accurate formatting that understands Twig and HTML structure
-- **Twig inside attributes** - Properly handles `{{ expressions }}` and `{% if %}` blocks in HTML attributes
-- **Whitespace control** - Preserves `{%- -%}` and `{{- -}}` modifiers
-- **Ignore blocks** - Use `{# twix:ignore-start #}` / `{# twix:ignore-end #}` to skip formatting
+### HTML Formatting
+
+- Proper indentation of nested elements
+- Block elements (`div`, `p`, `section`, etc.) get their own lines
+- Inline elements (`span`, `a`, `strong`, etc.) stay on the same line when possible
+- Void elements (`meta`, `link`, `input`, etc.) are self-closing
+- Multi-line attribute formatting when attributes exceed `printWidth`
+
+### Twig Formatting
+
+- Block tags are indented with their content
+- Expressions (`{{ }}`) preserve their content
+- Whitespace control modifiers (`{%- -%}`, `{{- -}}`) are preserved
+- Comments (`{# #}`) are preserved
+
+### Twig Inside HTML Attributes
+
+Twix properly handles Twig embedded in HTML attribute values:
+
+```twig
+<!-- Expressions in attributes -->
+<div class="container {{ dynamicClass }}">
+
+<!-- Conditional classes -->
+<div class="item {% if active %}is-active{% endif %}">
+
+<!-- Conditional attributes -->
+<button {% if disabled %}disabled{% endif %}>
+```
+
+### Ignore Blocks
+
+Skip formatting for specific sections using ignore directives:
+
+```twig
+{# twix:ignore-start #}
+<div   class="preserve"   data-value="exactly as-is"  >
+  This content will not be formatted
+</div>
+{# twix:ignore-end #}
+```
+
+### Blank Line Handling
+
+- Multiple consecutive blank lines are collapsed to a single blank line
+- Blank lines immediately after opening block tags (`{% if %}`, `{% for %}`, etc.) are removed
+- Intentional blank lines between statements are preserved
+
+## Limitations & Known Issues
+
+### Not Supported
+
+- **Twig expressions are not parsed** - Content inside `{{ }}` and `{% %}` is preserved as-is, not reformatted
+- **No HTML entity handling** - Entities like `&nbsp;` are passed through unchanged
+- **No CSS/JS formatting** - Content inside `<style>` and `<script>` tags is not formatted
+- **Windows line endings** - Output uses Unix line endings (`\n`)
+
+## Editor Integration
+
+### Pre-commit Hook
+
+Using [husky](https://typicode.github.io/husky/) and [lint-staged](https://github.com/okonet/lint-staged):
+
+```json
+// package.json
+{
+  "lint-staged": {
+    "*.twig": "twix"
+  }
+}
+```
+
+## Development
+
+```bash
+# Build
+go build
+
+# Run tests
+go test ./...
+
+# Build for all platforms
+./scripts/build.sh 0.1.0
+```
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@upstatement/twix-linux-x64",
-  "version": "0.1.3",
-  "description": "A formatter for Twig templates with HTML",
+  "version": "0.1.4",
+  "description": "An opinionated formatter for Twig templating engine",
   "bin": {
     "twix": "bin/twix"
   },