+
+
+ {% schema %}
+ {
+ "prop": []
+ }
+ {% endschema %}
+ `;
+
+ this.input = papyrus.mount(this.inputTarget, {
+ language: 'liquid',
+ input,
+ lineNumbers: true,
+ editor: true
+ });
+
+ this.input.update(input);
+ this.input.onupdate(this.update, this);
+
+ }
+
+ update (code: string, language: papyrus.Languages) {
+
+ if (this.rules.language !== language) {
+ esthetic.rules({ language });
+ }
+
+ m.render(this.outputTarget, this.table(code));
+
+ }
+
+ table (code: string) {
+
+ const data = esthetic.parse(code);
+
+ const isEven = (n: number) => n % 2 === 0 ? 'stripe' : '';
+
+ return [
+ m('table',
+ m('tr', [
+ m('td.pl-2.bold', 'Index'),
+ m('td.bold', 'Line No'),
+ m('td.bold', 'Begin'),
+ m('td.bold', 'Ender'),
+ m('td.bold', 'Lines'),
+ m('td.bold', 'Lexer'),
+ m('td.bold', 'Type'),
+ m('td.bold', 'Stack'),
+ m('td.bold', 'Token')
+ ]),
+ data.begin.map((_, i) => [
+ m('tr', {
+ class: isEven(i)
+ }, [
+ m('td.pl-2', `${i}`),
+ m('td', `${esthetic.lines[i]}`),
+ m('td', `${data.begin[i]}`),
+ m('td', `${data.ender[i]}`),
+ m('td', `${data.lines[i]}`),
+ m('td', `${data.lexer[i]}`),
+ m('td', `${data.types[i]}`),
+ m('td', `${data.stack[i]}`),
+ m('td', m('pre', m('code.fc-gray', data.token[i])))
+
+ ])
+ ]))
+ ];
+
+ }
+
+ /**
+ * Papyrus Input
+ */
+ input: papyrus.Model;
+
+ /**
+ * Input target
+ */
+ inputTarget: HTMLElement;
+
+ /**
+ * Output target to mount
+ */
+ outputTarget: HTMLElement;
+
+}
diff --git a/docs/src/app/components/playground.ts b/docs/src/app/components/playground.ts
index 210859a..0a0ab62 100644
--- a/docs/src/app/components/playground.ts
+++ b/docs/src/app/components/playground.ts
@@ -1,6 +1,5 @@
import type Moloko from 'moloko';
import { Controller } from '@hotwired/stimulus';
-import esthetic from 'esthetic'
export class Playground extends Controller {
@@ -23,12 +22,21 @@ export class Playground extends Controller {
loaded: Boolean
};
- moloko: typeof Moloko;
+ get moloko () {
+
+ return Playground.moloko;
+ }
+
+ get hash () {
+ return localStorage.getItem('moloko');
+ }
+
svg: Element;
timer: NodeJS.Timer;
async connect () {
+ if (this.hash) window.location.hash = this.hash;
if (Playground.loaded) return this.mount();
@@ -39,6 +47,12 @@ export class Playground extends Controller {
}
+ disconnect (): void {
+
+ localStorage.setItem('moloko', this.moloko.hash());
+
+ }
+
async module () {
const moloko = await import(this.moduleValue);
@@ -67,7 +81,7 @@ export class Playground extends Controller {
this.loading();
- }, 1200);
+ }, 500);
} else {
diff --git a/docs/src/app/components/scrollspy.ts b/docs/src/app/components/scrollspy.ts
index d505ea5..10baa5e 100644
--- a/docs/src/app/components/scrollspy.ts
+++ b/docs/src/app/components/scrollspy.ts
@@ -62,7 +62,7 @@ export class ScrollSpy extends Controller {
}
if (window.scrollY < 10) {
- this.anchorTargets[0].classList.add(this.activeClass);
+ this.anchorTargets[0]?.classList.add(this.activeClass);
} else {
this.onScroll();
}
diff --git a/docs/src/app/index.ts b/docs/src/app/index.ts
index 1e09610..af9abc9 100644
--- a/docs/src/app/index.ts
+++ b/docs/src/app/index.ts
@@ -6,6 +6,7 @@ import { Demo } from './components/demo';
import { Dropdown } from './components/dropdown';
import { ScrollSpy } from './components/scrollspy';
import { Playground } from './components/playground';
+import { Parser } from './components/parser';
import spx from 'spx';
spx.connect({
@@ -25,6 +26,7 @@ spx.connect({
stimulus.register('demo', Demo);
stimulus.register('scrollspy', ScrollSpy);
stimulus.register('playground', Playground);
+ stimulus.register('parser', Parser);
});
diff --git a/docs/src/assets/svg/process.svg b/docs/src/assets/svg/process.svg
new file mode 100644
index 0000000..e74476d
--- /dev/null
+++ b/docs/src/assets/svg/process.svg
@@ -0,0 +1,419 @@
+
+
diff --git a/docs/src/assets/svg/sparser.svg b/docs/src/assets/svg/sparser.svg
new file mode 100644
index 0000000..8b98a24
--- /dev/null
+++ b/docs/src/assets/svg/sparser.svg
@@ -0,0 +1,27 @@
+
+
+
diff --git a/docs/src/data/main.json b/docs/src/data/main.json
index f4f99cb..b816f38 100644
--- a/docs/src/data/main.json
+++ b/docs/src/data/main.json
@@ -2,7 +2,7 @@
"groups": [
"Introduction",
"Usage",
- "Parse",
+ "Parser",
"Integrate",
"Misc"
],
@@ -12,6 +12,16 @@
"title": "What is Æsthetic?",
"url": "/introduction/what-is-esthetic/"
},
+ {
+ "group": "introduction",
+ "title": "Motivation",
+ "url": "/introduction/motivation/"
+ },
+ {
+ "group": "introduction",
+ "title": "Language Support",
+ "url": "/introduction/language-support/"
+ },
{
"group": "introduction",
"title": "Installation",
@@ -35,8 +45,8 @@
},
{
"group": "usage",
- "title": "Formatting",
- "url": "/usage/formatting/"
+ "title": "Format",
+ "url": "/usage/format/"
},
{
"group": "usage",
@@ -46,7 +56,7 @@
{
"group": "usage",
"title": "Parse",
- "url": "/usage/parsing/"
+ "url": "/usage/parse/"
},
{
"group": "usage",
@@ -64,29 +74,29 @@
"url": "/usage/utilities/"
},
{
- "group": "parse",
+ "group": "parser",
"title": "Algorithm",
- "url": "/parse/algorithm/"
+ "url": "/parser/algorithm/"
},
{
- "group": "parse",
+ "group": "parser",
"title": "Tokens",
- "url": "/parse/tokens/"
+ "url": "/parser/tokens/"
},
{
- "group": "parse",
+ "group": "parser",
"title": "Lexers",
- "url": "/parse/lexers/"
+ "url": "/parser/lexers/"
},
{
- "group": "parse",
+ "group": "parser",
"title": "Error Handling",
- "url": "/parse/error-handling/"
+ "url": "/parser/error-handling/"
},
{
- "group": "parse",
+ "group": "parser",
"title": "Terminology",
- "url": "/parse/terminology/"
+ "url": "/parser/terminology/"
},
{
"group": "integrate",
diff --git a/docs/src/data/rules.json b/docs/src/data/rules.json
index cb4d042..966e7c5 100644
--- a/docs/src/data/rules.json
+++ b/docs/src/data/rules.json
@@ -48,11 +48,6 @@
"title": "preserveLine",
"url": "/rules/global/preserveLine/"
},
- {
- "group": "global",
- "title": "preset",
- "url": "/rules/global/preset/"
- },
{
"group": "global",
"title": "wrap",
@@ -237,11 +232,6 @@
"title": "classPadding",
"url": "/rules/style/classPadding/"
},
- {
- "group": "style",
- "title": "correct",
- "url": "/rules/style/correct/"
- },
{
"group": "style",
"title": "commentIndent",
diff --git a/docs/src/docs/integrate/text-editor.md b/docs/src/docs/integrate/text-editor.md
index 3060ab2..07d6045 100644
--- a/docs/src/docs/integrate/text-editor.md
+++ b/docs/src/docs/integrate/text-editor.md
@@ -4,4 +4,6 @@ layout: base
permalink: '/integrate/text-editor/index.html'
---
-# TODO
+# Text Editor
+
+Æsthetic is not yet available within text editors, but support is on the he roadmap. Though an official Æsthetic text editor extension/plugin is planned, Æsthetic is leverages within the [VSCode Liquid](#) extension.
diff --git a/docs/src/docs/introduction/installation.md b/docs/src/docs/introduction/installation.md
index 4d655b0..6a3564b 100644
--- a/docs/src/docs/introduction/installation.md
+++ b/docs/src/docs/introduction/installation.md
@@ -3,61 +3,86 @@ title: 'Installation'
layout: base
permalink: '/introduction/installation/index.html'
prev:
- label: 'What is Æsthetic'
- uri: '/introduction/what-is-esthetic'
+ label: 'Language Support'
+ uri: '/introduction/language-support'
next:
label: 'CLI'
uri: '/usage/cli'
anchors:
- Installation
+ - PNPM
- CDN
- Schema Store
- - Getting Started
- - CLI
- - API
---
# Installation
-Æsthetic can be consumed via the NPM registry and supports both ESM and CJS environments. It is recommended to avoid installing the project globally and instead install it as a dev-dependency.
+Æsthetic is available for consumption via the NPM registry and supports both ESM and CJS environments. For the best practice, it is recommended to install Æsthetic on a per-project basis rather than globally. While tree-shaking is not feasible with Æsthetic, developers can rest assured that the module remains relatively small, with a gzipped size of 57.5kb. Additionally, its import bundle is distributed as a single, concise file.
-##### PNPM
+###### PNPM
Æsthetic recommends developers choose [pnpm](https://pnpm.js.org/en/cli/install) as their package manager.
```bash
-$ pnpm add esthetic
+$ pnpm add esthetic --save-dev
```
-##### CDN
+###### NPM
-Use the [unpkg](https://unpkg.com/estheitc) CDN for quick usage in the web browser.
+```bash
+$ npm install esthetic --save-dev
+```
+
+###### Yarn
+```bash
+$ yarn add esthetic
```
+
+---
+
+# CDN Usage
+
+You may optionally prefer to use the [unpkg](https://unpkg.com/estheitc) CDN for quick usage in the web browser. Æsthetic will be exposed in `globalThis` scope when used in browser environments. You can access method via `window.esthetic` (or simply, `esthetic`) anywhere in your application.
+
+```bash
https://unpkg.com/esthetic
```
-# Schema Store
+> You can disable `globalThis` assignment from being applied via `esthetic.settings()` method. See the usage → [settings](/usage/settings) page for more information.
+
+---
-The module also provided JSON Schema Store reference for usage in JSON files via `$schema` properties or within text editors like [VSCode](https://code.visualstudio.com/) which support store digestion.
+# JSON Schema Store
-```
+Æsthetic provided JSON Schema Store references for usage in JSON files that contain a `$schema` property or within text editors like [VSCode](https://code.visualstudio.com/) which support external schema store association.
+
+```bash
https://unpkg.com/esthetic/schema.json
```
-You can provide the schema store reference a couple of different ways. For developers who use the **VSCode** text editor can either install the [Æsthetic Extension](#) or alternatively you can provide the schema store to your workspace settings:
+#### VSCode Usage
+You can provide the schema store reference a couple of different ways. Developers using the **VSCode** text editor, can either install the [Æsthetic Extension](#) or alternatively provide the schema store to your workspace settings:
+
+
```json
{
"json.schemas": [
{
"url": "https://unpkg.com/esthetic/schema.json",
- "fileMatch": ["package.json", ".esthetic.json", ".esthetic"]
+ "fileMatch": [
+ "package.json",
+ ".esthetic.json",
+ ".esthetic"
+ ]
}
]
}
```
+#### Direct Usage
+
You may optionally choose to provide the schema store directly within JSON configuration files.
```json
diff --git a/docs/src/docs/introduction/language-support.md b/docs/src/docs/introduction/language-support.md
index 68dcd94..34a13d1 100644
--- a/docs/src/docs/introduction/language-support.md
+++ b/docs/src/docs/introduction/language-support.md
@@ -2,32 +2,43 @@
title: 'Language Support'
layout: base
permalink: '/introduction/language-support/index.html'
+prev:
+ label: 'Motivation'
+ uri: '/introduction/motivation'
+next:
+ label: 'Installation'
+ uri: '/introduction/installation'
+anchors:
+ - Language Support
+ - Support List
---
# Language Support
-Below is a current support list of supported languages, their completion status and whether you can run Æsthetic for beautification. You can leverage on languages above 90% completion, anything below that is not yet ready for the big time. Languages with an above 80% completion status will work with basic structures, but may not be viable in some cases and can be problematic.
+Though Æsthetic uses the (language aware) Sparser algorithm, the majority of languages supported by Sparser are not supported in Æsthetic. Sparser's (and PrettyDiff) underlying parse approach in the adaptation to Æsthetic was heavily modified and the original language support list differs. Æsthetic (currently) aims to support only a small subset of languages, specifically those which pertain to front-end (client side) web development. Global language support is not something that Æsthetic aspires to provide currently as it's difficult to achieve both from a maintenance perspective but also from the performance level.
-## Usage Status
+# Support List
-| Language | Status | Usage | Operational |
-| ------------------- | ------------ | ------------------------------- | :---------: |
-| XML | 92% Complete | _Safe enough to use_ | ✓ |
-| HTML | 94% Complete | _Safe enough to use_ | ✓ |
-| Liquid + HTML | 92% Complete | _Safe enough to use_ | ✓ |
-| Liquid + CSS | 87% Complete | _Safe enough to use_ | ✓ |
-| Liquid + JSON | 80% Complete | _Use with caution_ | ✓ |
-| Liquid + JavaScript | 80% Complete | _Use with caution_ | ✓ |
-| JSON | 88% Complete | _Safe enough to use_ | ✓ |
-| CSS | 92% Complete | _Safe enough to use_ | ✓ |
-| SCSS | 82% Complete | _Use with caution_ | ✓ |
-| JavaScript | 78% Complete | _Use with caution_ | 𐄂 |
-| TypeScript | 70% Complete | _Avoid using, many defects_ | 𐄂 |
-| JSX | 70% Complete | _Avoid using, many defects_ | 𐄂 |
-| LESS | 60% Complete | _Avoid using, many defects_ | 𐄂 |
-| TSX | 40% Complete | _Avoid using, many defects_ | 𐄂 |
-| YAML | 50% Complete | _Do not use, not yet supported_ | 𐄂 |
+Below is the current list of supported languages, along with their completion status and whether Æsthetic can be used for beautification. For languages with a completion status above 90%, you can confidently run Æsthetic for optimal code formatting. However, for languages below that threshold, they may not be fully ready for prime time. Languages with an above 80% completion status can handle basic structures, but they may encounter some limitations and potential issues in certain cases.
-## Support Goals
+> Exercising caution and testing thoroughly is advisable to ensure a smooth beautification process for languages below **90%** completions and languages below **80%** should be avoided for now.
-TODO
+| Language | Status | Information | |
+| :---------------------- | ------------ | ------------------------------------------- | --- |
+| **XML** | 92% Complete | _Safe enough to use in projects_ | ✓ |
+| **HTML** | 94% Complete | _Safe enough to use in projects_ | ✓ |
+| **Liquid + HTML** | 92% Complete | _Safe enough to use in projects_ | ✓ |
+| **Liquid + CSS** | 87% Complete | _Safe enough to use in projects_ | ✓ |
+| **Liquid + JSON** | 80% Complete | _Use with caution, some structural defects_ | ✓ |
+| **Liquid + JavaScript** | 79% Complete | _Use with caution, some structural defects_ | ✓ |
+| **JSON** | 88% Complete | _Safe enough to use in projects_ | ✓ |
+| **CSS** | 92% Complete | _Safe enough to use in projects_ | ✓ |
+| **SCSS** | 72% Complete | _Avoid using, unexpected results_ | ✓ |
+| **JavaScript** | 78% Complete | _Use with caution, some structural defects_ | 𐄂 |
+| **TypeScript** | 70% Complete | _Avoid using, too many defects_ | 𐄂 |
+| **JSX** | 70% Complete | _Avoid using, too many defects_ | 𐄂 |
+| **LESS** | 60% Complete | _Avoid using, too many defects_ | 𐄂 |
+| **TSX** | 40% Complete | _Avoid using, too many defects_ | 𐄂 |
+| **YAML** | 50% Complete | _Do not use, not yet supported_ | 𐄂 |
+
+> Please keep in mind that Æsthetic is still in its infancy, updates are frequent, patches and fixes are incurred as the tool progresses.
diff --git a/docs/src/docs/introduction/motivation.md b/docs/src/docs/introduction/motivation.md
index 6485ff5..34e992e 100644
--- a/docs/src/docs/introduction/motivation.md
+++ b/docs/src/docs/introduction/motivation.md
@@ -2,32 +2,38 @@
title: 'Motivation'
layout: base
permalink: '/introduction/motivation/index.html'
+prev:
+ label: 'What is Æsthetic'
+ uri: '/introduction/what-is-esthetic'
+next:
+ label: 'Language Support'
+ uri: '/introduction/language-support'
+anchors:
+ - Motivation
+ - The Evolution of Open Source
+ - Balancing Consistency
---
# Motivation
-Æsthetic was originally developed to handle chaotic and unpredictable Liquid + HTML markup structures. Before creating Æsthetic, there was no solution or tool available which supported Liquid infused syntax and developers working on projects using the template language were unable to leverage beautifiers. This became the accepted status-quo until [Austin Cheney](https://github.com/prettydiff) support for Liquid beautification in Sparser and PrettyDiff.
+Æsthetic was born out of the necessity to support Liquid + HTML markup formatting. Prior to the development of Æsthetic, there were no available solutions or tools capable of handling Liquid-infused syntax, leaving developers working on projects using this template language without the ability to leverage beautifiers. This limitation was accepted as the status quo until [Austin Cheney](https://github.com/prettydiff) introduced Liquid beautification support in Sparser and PrettyDiff.
-The scale of the Sparser project and its parse algorithm was always an ambitious undertaking and before its retirement in 2019, [Austin](https://github.com/prettydiff) was overseeing support for over **40** different languages. Focusing attention to edge-cases pertaining to a template language is rightfully not the most pressing of tasks in a project of that size.
+Austin's tools became the go-to solution for Liquid beautification until their (unofficial) retirement in late 2019. At the time of their sunset, [Sparser](https://github.com/Unibeautify/sparser) and its sister tool [PrettyDiff](https://github.com/prettydiff/prettydiff) supported diffing, beautification, and minification for over **40+** different languages. Despite their abandonment, these tools continue to be used in production by thousands of projects, which is an ode to their exceptional reliability and enduring impact on the developer community.
-## The Evolution of Open Source
+# The Evolution of Open Source
-become apparent that a more focused and fluid solution was required but both these tools had been abandoned and as of 2019 were no longer being _actively_ maintained. Having grown fond and accustomed to the generated output of PrettyDiff I began sifting through the codebase to fix a couple defects but quickly became fascinated with the overall architecture of these tools and their parse algorithm written by [Austin Cheney](https://github.com/prettydiff).
+Prior to their retirement, Sparser and PrettyDiff played a crucial role in supporting the [VSCode Liquid](https://github.com/panoply/vscode-liquid) extension. However, when maintenance ceased, it became imperative to confront the arising issues and defects. This was essential to ensure the seamless continuity of formatting capabilities in the VSCode Liquid extension, and to meet the needs of over 100k developers who relied on beautification features.
-Minor refactors, turned into major refactors and several months later the projects had morphed into Æsthetic.
+In order to sustain and enhance Liquid formatting support in VSCode, the existing codebase of Sparser/PrettyDiff was hard-forked and refinements were carried out. Navigating through the Sparser and PrettyDiff repositories posed challenges, given the lack of comments and limited guidance. Since Austin had been the sole maintainer of these projects for a significant period, the code reflected his specific style and acclimatization was difficult.
-## Opinions are Oppression
+The process of delving into the code architecture proved otherwise fascinating, particularly the lexing approach crafted for language awareness and data structures. The parse algorithm itself served as a valuable source of inspiration and motivation during this process. Initially, efforts focused on fixing bugs and defects, but over time, minor refactors turned into substantial ones. The codebase and usage purpose began to shift, and though the original parse approach persists (serving as the foundation) the projects evolved into what we now know as Æsthetic.
-Æsthetic uses the developers intent and refines its result in accordance. This approach allows developers to determine what works best for a project at hand.
+# Balancing Consistency
-### Sparser and PrettyDiff
+In the world of code beautification, opinionated tooling has been the norm, often leaving developers with limited customization options. However, Æsthetic was conceived with a different motivation—to empower developers with a tool that offers both consistency and customization, bridging the gap between rigid formatters and flexible linting solutions.
-TODO
+In projects where flexibility and customization are paramount, strict formatters can pose challenges. While they excel in providing a standardized style, they may not always align with a developer's preferred code expression. This can lead to a sense of constraint, especially for developers who value their unique coding style and preferences. The goal of Æsthetic is to embrace these nuances with grace and flexibility, ensuring that developers have the freedom to shape their code while preserving readability and structure.
-# Motivation
-
-Æsthetic was originally developed to handle chaotic and unpredictable Liquid + HTML markup structures. Before creating Æsthetic, there was no solution or tool available which supported Liquid infused syntax and developers working on projects using the template language were unable to leverage beautifiers. This became the accepted status-quo until [Austin Cheney](https://github.com/prettydiff) support for Liquid beautification in Sparser and PrettyDiff.
-
-Before their (unofficial) retirement in late 2019 both [Sparser](https://github.com/Unibeautify/sparser) and its sister tool [PrettyDiff](https://github.com/prettydiff/prettydiff) supported diffing, beautification and minification for over **40+** different languages. Having grown fond and accustomed to the generated output of PrettyDiff I began sifting through the codebase to fix a couple defects and quickly became fascinated with the overall architecture of these tools.
+Finding the right balance between maintaining code consistency and allowing room for individual expression is a key challenge that Æsthetic addresses. By providing a granular set of formatting rules, Æsthetic empowers developers to fine-tune the code expression while retaining the essential details that might be lost with a strict approach. While recognizing the value of opinionated formatters with small surface APIs, Æsthetic also acknowledges that they may not cover all the intricacies and nuances of a complex codebase. With a more extensive and adaptable set of formatting options, Æsthetic allows developers to craft code that remains visually appealing and true to their original intent.
-The formatting style and overall approaches of these tools were different from others and by focusing attention to edge-cases pertaining to a template language like Liquid.
+In conclusion, Æsthetic stands as a powerful ally for developers, offering a balanced approach that respects coding preferences while promoting consistency and maintainability. Developers can embrace Æsthetic as a tool to enhance their coding journey, creating codebases that reflect their unique artistry without having to involve a linter.
diff --git a/docs/src/docs/introduction/quickstart.md b/docs/src/docs/introduction/quickstart.md
deleted file mode 100644
index 48e826f..0000000
--- a/docs/src/docs/introduction/quickstart.md
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: 'Getting Started'
-layout: base
-permalink: '/introduction/quickstart/index.html'
-anchors:
- - Getting Started
- - CLI
- - API
----
-
-# Getting Started
-
-Below we will describe how to work with the Æsthetic [CLI](/usage/cli/) and [API](/usage/api/). CLI usage requires a [config file](/usage/config-file/) or `esthetic` reference in your projects `package.json`. In most cases, developers may prefer to use the VSCode [extension](#) which provides auto-formatting capabilities.
-
-### CLI
-
-After installing Æsthetic, you will need to define formatting [Rules](/usage/rules/). Æsthetic will assume rules are defined within your projects root `package.json` file on a `esthetic` property.
-
-```js
-{
- "esthetic": {
- "wrap": 100,
- "preserveLine": 2,
- "liquid": {
- "delimiterTrims": "never"
- },
- "html": {
- "forceAttribute": true
- }
- }
-}
-```
-
-Above we have provided both [global](/rules/global/wrap/), [html](/rules/html/forceAttribute/) and [liquid](/rules/liquid/delimiterTrims/) formatting rules within a `package.json` file. We can now leverage Æsthetic to beautify documents. The CLI **requires** a path/pattern to files be provided, so for the sake of brevity lets assume we want to format all files contained root directory.
-
-Open up your terminal and run:
-
-```
-$ esthetic . --html
-```
-
-The above command will apply formatting to all files using a `.html` extension and print the beautified result to `stdout` in your terminal. This is just a **basic** example and for advanced usage with the CLI, take a look at [CLI](/usage/cli/) documentation.
-
-### API
-
-Developers who are implementing Æsthetic into their apps or projects can use the API which exposes most of the core features. Unlike the CLI, you do not need to provide formatting rules in a `package.json` file and instead you can pass them directly via methods or as arguments.
-
-
-```js
-import esthetic from 'esthetic';
-
-const input = `
-
-{%- if condition -%} Hello World
-{%- endif -%}
-
-`;
-
-const output = esthetic.format(input, {
- language: 'liquid',
- wrap: 100,
- preserveLine: 2,
- liquid: {
- delimiterTrims: 'never'
- },
- markup: {
- forceAttribute: true
- }
-});
-
-
-console.log(output)
-
-```
-
-In the above example, the `output` result holds the beautified code.
diff --git a/docs/src/docs/introduction/what-is-esthetic.md b/docs/src/docs/introduction/what-is-esthetic.md
index 2a8f88d..8d5426d 100644
--- a/docs/src/docs/introduction/what-is-esthetic.md
+++ b/docs/src/docs/introduction/what-is-esthetic.md
@@ -6,43 +6,39 @@ prev:
label: 'What is Æsthetic'
uri: '/introduction/what-is-esthetic'
next:
- label: 'Installation'
- uri: '/introduction/installation'
+ label: 'Motivation'
+ uri: '/introduction/motivation'
anchors:
- What is Æsthetic?
- Why Æsthetic?
- Æsthetic vs. Prettier
+ - Æsthetic vs. JSBeautify
---
# What is Æsthetic?
-Æsthetic is a lightweight, fast and extensible code beautification tool that provides formatting support for front-end orientated (client side) languages and exists as an alternative to [Prettier](https://prettier.io/) and [JS Beautify](https://beautifier.io/). Æsthetic implements a variation of the universal [Sparser](https://sparser.io/docs-html/tech-documentation.xhtml#universal-parse-model) lexing algorithm and has been adapted from the distributed source of [PrettyDiff](https://github.com/prettydiff/prettydiff/blob/master/options.md).
-
-Æsthetic supports parse, format and language detection capabilities for the following languages:
-
-- [Liquid](https://shopify.github.io/liquid/)
-- [HTML](https://en.wikipedia.org/wiki/HTML)
-- [XML](https://developer.mozilla.org/en-US/docs/Web/XML/XML_introduction)
-- [CSS](https://en.wikipedia.org/wiki/CSS)
-- [SCSS](https://sass-lang.com)
-- [JSON](https://en.wikipedia.org/wiki/JSON)
-- [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Language_overview)
-- [TypeScript](https://www.typescriptlang.org/)
-- [JSX](https://facebook.github.io/jsx/)
-- [TSX](https://www.typescriptlang.org/docs/handbook/jsx.html)
+Æsthetic is a lightweight, fast, and extensible code beautification tool that offers comprehensive formatting support for front-end oriented (client-side) languages. It presents itself as a viable alternative to [Prettier](https://prettier.io/) and [JS Beautify](https://beautifier.io/), providing developers with a powerful and flexible option for code formatting. Based on a variation of the universal [Sparser](https://sparser.io/docs-html/tech-documentation.xhtml#universal-parse-model) lexing algorithm, Æsthetic has been thoughtfully adapted from the distributed source of [PrettyDiff](https://github.com/prettydiff/prettydiff/blob/master/options.md).
# Why Æsthetic?
-The usage proposition for Æsthetic is mostly a matter of preference but there are several notable differences that separate it from alternative solutions available in the beautification nexus. The approach of Æsthetic involves formatting code in accordance with the **implied** structures of the provided input. It takes a preservationist approach with progressive adaptation.
+The adoption of Æsthetic as a code beautification tool largely comes down to personal preference. However, several key differentiators set it apart from alternative solutions in the realm of code formatting. Æsthetic's unique approach involves formatting code in alignment with the **implied** structures of the provided input. It takes a preservationist approach while incorporating progressive adaptation to ensure the most natural and intuitive formatting results.
+
+At the core of Æsthetic is a commitment to maintaining the original intent of the code. It achieves this through a uniformed data structure known as the parse table, which enables progressive customizations, incremental updates, and extensible control during traversal operations. The parse table itself provides a concise lexical context of the code input, streamlining the formatting process.
-Adhering to intent is at the core of Æsthetic. The uniformed data structure (parse table) that Æsthetic produces and works with during traversal operations allows for progressive customizations, incremental updates and extensible control. The parse table alone provides concise lexical context of code input. The parse and format operations execute in a modest 2 cycle process without needing to bend, augment or reach for additional resources. The tool exposes a granular set of formatting rules which allow developers to produce results that do not impede on preferred code style tastes.
+Æsthetic boasts a remarkably efficient two-cycle process for parse and format operations, eliminating the need for additional resources. It exposes a granular set of formatting rules, empowering developers to produce results that align with their preferred code style while retaining readability and consistency.
# Æsthetic vs. Prettier
-Æsthetic does not want to replace tools like Prettier. Prettier is a fantastic tool and even the Æsthetic project leverages it to format markdown files. The usage proposition for choosing Æsthetic over Prettier is a matter of code expression. When working with languages comprised of complex patterns the opinionated conventions of Prettier tend to impede upon structural intent and this can become problematic in programming languages where flexibility is a matter of necessity.
+Æsthetic does not seek to replace tools like Prettier; in fact, Prettier remains a fantastic tool, and the Æsthetic project itself utilizes it to format markdown files. The decision to choose Æsthetic over Prettier revolves around code expression and the nature of the programming languages at hand.
+
+Prettier is an opinionated tool with defined conventions, which can be excellent for many scenarios. However, when dealing with languages consisting of intricate patterns and complex structures, Prettier's opinionated approach may inadvertently hinder the intended code structure. This becomes especially relevant in programming languages where flexibility is of utmost importance.
+
+Æsthetic has the capability to produce the same formatting results as Prettier, but it employs a different overall architecture and approach. By offering a more adaptable and customizable formatting experience, Æsthetic caters to scenarios where maintaining the structural intent and code flexibility are crucial. This distinction makes Æsthetic a preferred choice for projects that necessitate fine-tuned control over code expression.
+
+# Æsthetic vs. JS Beautify
-Æsthetic can replicate the same results as Prettier but the overall architecture and approaches employed differ.
+Æsthetic and JS Beautify are both powerful code beautification tools, each offering distinct approaches to code formatting that cater to different preferences and requirements. JSBeautify, is known for its well-established conventions, is an excellent choice for developers seeking a straightforward and opinionated code formatting solution. It excels at automatically applying consistent formatting to JavaScript code, making it easy to achieve a uniform and standardized style.
-# Æsthetic vs. JSBeautify
+On the other hand, Æsthetic takes a more adaptable and customizable approach to code beautification. It prioritizes preserving the structural intent of the code while providing developers with a granular set of formatting rules. This allows for fine-tuned control over the code expression, making it ideal for projects with complex patterns and nuanced structures.
-TODO
+Ultimately, the decision between Æsthetic and JS Beautify will depend on the specific needs and preferences of the developer and the nature of the project at hand. Both tools have their merits, providing valuable formatting solutions for JavaScript codebase with different degrees of complexity and expression requirements.
diff --git a/docs/src/docs/misc/acknowledgements.md b/docs/src/docs/misc/acknowledgements.md
index 4f9a911..42d3d0e 100644
--- a/docs/src/docs/misc/acknowledgements.md
+++ b/docs/src/docs/misc/acknowledgements.md
@@ -3,3 +3,33 @@ title: 'Acknowledgements'
layout: base
permalink: '/misc/acknowledgements/index.html'
---
+
+# Acknowledgements
+
+Æsthetic owes its existence to [Sparser](https://sparser.io/) and [PrettyDiff](https://prettydiff.com/). This project has been adapted from these 2 brilliant tools and while largely refactored + overhauled the original parse architecture remains intact. Building a code beautification tool is not easy, there are many hurdles and paradigms to overcome, many tests cases to execute against and problems that occur. Development on Æsthetic began in 2022 and despite having Sparser and PrettyDiff lay the foundation, a lot of time has gone into it's reapplication. Some acknowledgements are owed to several individuals who have helped make Æsthetic a reality by contributing their time, thoughts and suggestions.
+
+### [Austin Cheney](https://github.com/prettydiff)
+
+Austin is the original author of PrettyDiff and Sparser. He has since created [Shared File Systems](https://github.com/prettydiff/share-file-systems) which is a privacy first point-to-point communication tool. Please check it out and also have a read of
+[wisdom](https://github.com/prettydiff/wisdom) which personally helped me become a better developer.
+
+### [David Warrington](#)
+
+Dave is a senior software engineer working with Shopify. Dave is behind a lot of the developer facing logic in Æsthetic, especially Liquid and Markup related handling and control vectors. Check out his [blog](https://ellodave.dev).
+
+### [Mansedan](#)
+
+Mansedan has been leveraging Æsthetic since its conception. His insights, suggestions and real-world usage has allowed for Æsthetic to reach stability. Mansedan runs a Discord server for Shopify Developers and acts on behalf of internationally recognized brands in the e-commerce nexus.
+
+### [Max Design](#)
+
+Max was able to provide Æsthetic with fundamental suggestions and without his thoughts and contributions, a lot of rules would not exist. Max has vigorously tested Æsthetic and allowed edge cases to be handled gracefully by providing complex structures during the alpha and beta releases.
+
+###
+
+### [PrettyDiff](https://github.com/prettydiff/prettydiff) and [Sparser](https://github.com/unibeautify/sparser)
+
+Æsthetic is made possible because of the [Austin Cheney](https://github.com/prettydiff) who is the original author of [Sparser](https://github.com/unibeautify/sparser) and [PrettyDiff](https://github.com/prettydiff/prettydiff). Austin is one of the great minds in JavaScript and I want to thank him for open sourcing these tools.
+
+Both PrettyDiff and Sparser were retired in 2019 after a nearly a decade of production. Austin has since created [Shared File Systems](https://github.com/prettydiff/share-file-systems) which is a privacy first point-to-point communication tool. Please check it out and also have a read of
+[wisdom](https://github.com/prettydiff/wisdom) which personally helped me become a better developer.
diff --git a/docs/src/docs/misc/documentation.md b/docs/src/docs/misc/documentation.md
new file mode 100644
index 0000000..6f01c17
--- /dev/null
+++ b/docs/src/docs/misc/documentation.md
@@ -0,0 +1,50 @@
+---
+title: 'Documentation'
+layout: base
+permalink: '/misc/documentation/index.html'
+---
+
+# Documentation
+
+The Æsthetic documentation uses several different Open Source modules under the hood. Some considerable time went into producing documentation and developers are free to use the internal tools in their own projects. Below is brief breakdown and of third-parties leveraged and their appropriation.
+
+> Take a peek at the [source code](#) in the Æsthetic Github repository.
+
+### 11ty
+
+Æsthetic docs are developed using the [11ty](#) static site generator. Æsthetic compiles markdown files and uses certain structures to determine how output should be written. The [.eleventy.js](#) file is where you will find all bundling logic.
+
+### SPX + Stimulus
+
+Under the hood, the Æsthetic docs are using [SPX](#) which is an OTW (over the wire) module that intercepts navigation and maintains a snapshot cache engine in DOM state. SPX is used together with [Stimulus](#) to perform per-page interactivity and handling.
+
+**SPX**
+
+- [Repository](#)
+- [Documentation](#)
+
+**Stimulus**
+
+- [Repository](#)
+- [Documentation](#)
+
+### Papyrus
+
+The Æsthetic rule examples are made possible with [Papyrus](#) which was developed for usage in the documentation. Papyrus provides editable (lightweight) embedded text regions with [PrismJS](#) grammars.
+
+- [Repository](#)
+- [Documentation](#)
+
+### Moloko
+
+The Æsthetic playground is made possible with [Moloko](#) which provides a wrapped around the [Monaco Editor](#). Moloko leverages [Mithril](#) to virtually render Monaco and exposes some custom DX capabilities for specific usage in Æsthetic.
+
+**Moloko**
+
+- [Repository](#)
+- [Documentation](#)
+
+**Monaco**
+
+- [Repository](#)
+- [Documentation](#)
diff --git a/docs/src/docs/misc/limitations.md b/docs/src/docs/misc/limitations.md
index 7a5a8e5..b9ddf7c 100644
--- a/docs/src/docs/misc/limitations.md
+++ b/docs/src/docs/misc/limitations.md
@@ -6,7 +6,7 @@ permalink: '/misc/limitations/index.html'
# Limitations
-Æsthetic is comparatively _recluse_ in terms of PnP integrations/extensibility. Depending on your stack and development preferences you may wish to use Æsthetic together with additional tools like [eslint](https://eslint.org/), [stylelint](https://stylelint.io/) or even [Prettier](https://prettier.io/). There are a few notable caveats you should be aware before running Æsthetic, most of which are trivial.
+Æsthetic is comparatively _recluse_ in terms of PnP (plug and play) integrations/extensibility. Depending on your stack and development preferences you may wish to use Æsthetic together with additional tools like [eslint](https://eslint.org/), [stylelint](https://stylelint.io/) or even [Prettier](https://prettier.io/). There are a few notable caveats you should be aware before running Æsthetic, most of which are trivial.
## Æsthetic and Prettier
diff --git a/docs/src/docs/parse/algorithm.md b/docs/src/docs/parse/algorithm.md
deleted file mode 100644
index c231d59..0000000
--- a/docs/src/docs/parse/algorithm.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: 'Parse Architecture'
-layout: base
-permalink: '/parse/algorithm/index.html'
-anchors:
- - 'Algorithm'
- - 'Parse Table'
----
-
-# Algorithm
-
-The lexing algorithm and parse approach used by Æsthetic is an original strategic concept created by [Austin Cheney](https://github.com/prettydiff) and was first introduced in his project [Sparser](https://sparser.io/). The parse table produced by Sparser provides a simple data format that can accurately describe any language. Before sparser's re-application into Æsthetic, it was used by the language aware diffing and beautification tool [PrettyDiff](https://prettydiff.com/).
-
-While most parsers typically produce an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (abstract syntax tree) this is not the case with Æsthetic. Its implementation of Sparser will produce a uniformed table like structure and though many different algorithms can be made to achieve the same result they all come with tradeoffs relative to one another. Most parse tools in the nexus seem to be using some variant of [ANTLR](https://en.wikipedia.org/wiki/ANTLR), [PEG](https://en.wikipedia.org/wiki/Parsing_expression_grammar) or leverage the brilliant incremental [Tree Sitter](https://tree-sitter.github.io).
-
-Generators like ANTLR and Tree Sitter require grammars and leave users at the behest of steep learning curves whereas PEG parsers have less ambiguity than LR parsers but may produce worse error messages and consume more memory. When we look at hand-rolled recursive-descent parsers, these may be slower than the ones produced by generators but are unambiguous overall. Because the task of Æsthetic more often than not involves making sense of combined language formations the data structure (i.e: parse table) is flexible, easy to reason with and extensible.
-
-# Parse Table
-
-Consider the following code sample. The HTML (markup) consists of Liquid, CSS, JavaScript and JSON. All languages in the sample are encapsulated within the appropriate regional based denominated tags but more importantly, Liquid token expressions exist within the CSS, JavaScript and HTML.
-
-
-```liquid
-
-
-
-
-
-
- {% for item in arr %}
-
{{ item }}
- {% endfor %}
-
-
-
-{% schema %}
- {
- "prop": []
- }
-{% endschema %}
-```
-
-There is no "right way" or consensus on how a parser should make sense of this lexical anomaly and achieving lexical context and nor it seem to have been studied much in academia given the edge case realm it exists within The originality of the Sparser language parsing algorithm allows for these otherwise complex structures to be traversed and interpreted for handling without having to bend, augmented or reach for additional resourced to address weaknesses.
diff --git a/docs/src/docs/parser/algorithm.md b/docs/src/docs/parser/algorithm.md
new file mode 100644
index 0000000..70270f1
--- /dev/null
+++ b/docs/src/docs/parser/algorithm.md
@@ -0,0 +1,55 @@
+---
+title: 'Parse Algorithm'
+layout: base
+permalink: '/parser/algorithm/index.html'
+anchors:
+ - 'Algorithm'
+ - 'Parse Table'
+---
+
+# Parse Algorithm
+
+The lexing algorithm and parse approach employed by Æsthetic stem from an original strategic concept crafted by [Austin Cheney](https://github.com/prettydiff) and first introduced in his project [Sparser](https://sparser.io/). Notably, the parse table produced by Sparser offers a simple yet powerful data format capable of precisely describing any language. Before its integration into Æsthetic, Sparser played a crucial role in the language-aware diffing and beautification tool [PrettyDiff](https://prettydiff.com/).
+
+Unlike many parsers that typically generate an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree), Æsthetic follows a distinct path. Its implementation of Sparser results in a uniform table-like structure. While various algorithms can achieve similar outcomes, each approach comes with its own set of tradeoffs. Several parse tools in the development ecosystem rely on technologies like [ANTLR](https://en.wikipedia.org/wiki/ANTLR), [PEG](https://en.wikipedia.org/wiki/Parsing_expression_grammar), or the impressive incremental [Tree Sitter](https://tree-sitter.github.io).
+
+Generators such as ANTLR and Tree Sitter demand grammars and may impose steep learning curves on users. On the other hand, PEG parsers exhibit less ambiguity than LR parsers but might produce less effective error messages and consume more memory. Alternatively, hand-rolled recursive-descent parsers, while potentially slower than those generated by parsers, offer an unambiguous approach overall.
+
+Given Æsthetic's primary task of making sense of combined language formations, the chosen data structure (i.e., parse table) stands out for its flexibility, ease of reasoning, and extensibility. This enables Æsthetic to tackle the intricacies of code formatting across different languages, providing a reliable and adaptable solution to developers worldwide.
+
+# Parse Table
+
+Let's take a moment to analyze the following code sample—a combination of HTML (markup) with embedded Liquid, CSS, JavaScript, and JSON. Each language is encapsulated within the appropriate regional-based denominated tags. Notably, Liquid token expressions are found within CSS, JavaScript, and HTML.
+
+#### Code Example
+
+
+```liquid
+
+
+
+
+
+
+ {% for item in arr %}
+
{{ item }}
+ {% endfor %}
+
+
+
+{% schema %}
+{
+ "prop": []
+}
+{% endschema %}
+```
+
+#### Lexical Interpretation
+
+The complexity arises when we encounter such a lexical anomaly, as there is no definitive "right way" or consensus on how a parser should interpret this mixture of languages. This edge case realm poses unique challenges, and the study of achieving lexical context in such scenarios has not been extensively explored in academia.
+
+However, with the originality of the Sparser language parsing algorithm, Æsthetic shines as a solution to traverse and interpret these otherwise complex structures without the need to make compromises or resort to additional resources to address weaknesses. The powerful capabilities of Æsthetic's parse table allow for seamless handling of these intricate combinations, providing developers with a reliable and flexible tool to navigate the complexities of a multi-language codebase.
diff --git a/docs/src/docs/parse/error-handling.md b/docs/src/docs/parser/error-handling.md
similarity index 97%
rename from docs/src/docs/parse/error-handling.md
rename to docs/src/docs/parser/error-handling.md
index 9a6f7ba..c65bb8b 100644
--- a/docs/src/docs/parse/error-handling.md
+++ b/docs/src/docs/parser/error-handling.md
@@ -1,7 +1,7 @@
---
title: 'Parse Errors'
layout: base
-permalink: '/parse/error-handling/index.html'
+permalink: '/parser/error-handling/index.html'
anchors:
- 'Parse Errors'
- 'Error Exception'
diff --git a/docs/src/docs/parse/lexers.md b/docs/src/docs/parser/lexers.md
similarity index 80%
rename from docs/src/docs/parse/lexers.md
rename to docs/src/docs/parser/lexers.md
index c91cf93..e5ece7a 100644
--- a/docs/src/docs/parse/lexers.md
+++ b/docs/src/docs/parser/lexers.md
@@ -1,7 +1,7 @@
---
title: 'Lexers'
layout: base
-permalink: '/parse/lexers/index.html'
+permalink: '/parser/lexers/index.html'
order: 4
anchors:
- 'Markup'
diff --git a/docs/src/docs/parse/data-structure.md b/docs/src/docs/parser/parse-table.md
similarity index 89%
rename from docs/src/docs/parse/data-structure.md
rename to docs/src/docs/parser/parse-table.md
index e15d69b..0006402 100644
--- a/docs/src/docs/parse/data-structure.md
+++ b/docs/src/docs/parser/parse-table.md
@@ -1,7 +1,7 @@
---
-title: 'Data Structure'
+title: 'Parse Table'
layout: base
-permalink: '/parse/data-structure/index.html'
+permalink: '/parser/parse-table/index.html'
anchors:
- 'Algorithm'
- 'Parse Table'
diff --git a/docs/src/docs/parse/terminology.md b/docs/src/docs/parser/terminology.md
similarity index 53%
rename from docs/src/docs/parse/terminology.md
rename to docs/src/docs/parser/terminology.md
index 1547da5..cb37c3e 100644
--- a/docs/src/docs/parse/terminology.md
+++ b/docs/src/docs/parser/terminology.md
@@ -1,7 +1,7 @@
---
title: 'Terminology'
layout: base
-permalink: '/parse/terminology/index.html'
+permalink: '/parser/terminology/index.html'
---
# TODO
diff --git a/docs/src/docs/parse/tokens.md b/docs/src/docs/parser/tokens.md
similarity index 91%
rename from docs/src/docs/parse/tokens.md
rename to docs/src/docs/parser/tokens.md
index a94d26c..799219c 100644
--- a/docs/src/docs/parse/tokens.md
+++ b/docs/src/docs/parser/tokens.md
@@ -1,7 +1,7 @@
---
title: 'Tokens'
layout: base
-permalink: '/parse/tokens/index.html'
+permalink: '/parser/tokens/index.html'
anchors:
- 'Tokens'
- 'Parse Table'
diff --git a/docs/src/docs/usage/cli.md b/docs/src/docs/usage/cli.md
index 40c63ba..6a94d03 100644
--- a/docs/src/docs/usage/cli.md
+++ b/docs/src/docs/usage/cli.md
@@ -19,7 +19,7 @@ anchors:
# CLI
-Æsthetic provides basic CLI support via the `esthetic` command and assumes configuration is defined within a projects `package.json` file via an `esthetic` key property. CLI usage requires a path/pattern match be passed and will resolve files for from the location provided. Æsthetic will print formatted code to `stdout` and requires an `-f` or `--format` flag for file overwrites.
+Æsthetic provides basic CLI support via the `esthetic` command and assumes configuration is defined within a projects `package.json` file via an `esthetic` key property. CLI usage requires a path/pattern match be passed and will resolve files for from the location provided. Æsthetic will print formatted code to **stdout** and requires an `-f` or `--format` flag for file overwrites.
> The `-` or `--format` flag will overwrite files matching the path pattern provided. If you'd like to have Æsthetic output files to a different location then use the `-o` or `--output` flag.
diff --git a/docs/src/docs/usage/config-file.md b/docs/src/docs/usage/config-file.md
index 4307386..2ce784c 100644
--- a/docs/src/docs/usage/config-file.md
+++ b/docs/src/docs/usage/config-file.md
@@ -2,21 +2,23 @@
title: 'Config File'
layout: base
permalink: '/usage/config-files/index.html'
+prev:
+ label: 'CLI'
+ uri: '/usage/cli'
+next:
+ label: 'Rules'
+ uri: '/usage/rules'
anchors:
- Config Files
- Supported Files
- Ignoring Files
- Configuration
- - package.json
- - .esthetic.json
---
# Config Files
Æsthetic supports configuration files for defining formatting rules, settings and other options. By default, Æsthetic assumes that configuration is provided within a `package.json` file.
-> Despite the package name shipping under the U.S spelt variation the naming convention of files supports both U.S or U.K variations.
-
# Supported Files
You may prefer to keep formatting rules in an external file opposed using the default `package.json` method. Æsthetic provides support for the following external config files.
@@ -24,7 +26,7 @@ You may prefer to keep formatting rules in an external file opposed using the de
- `.esthetic`
- `.esthetic.json`
-> You can also use the CLI `-c` or `--config` flag to provide a custom config file and/or path location reference.
+> You can also use the CLI `-c` or `--config` flag to provide a custom configuration file and/or path location reference.
# Ignoring Files
diff --git a/docs/src/docs/usage/format.md b/docs/src/docs/usage/format.md
new file mode 100644
index 0000000..d47f261
--- /dev/null
+++ b/docs/src/docs/usage/format.md
@@ -0,0 +1,88 @@
+---
+title: 'Format'
+layout: base
+permalink: '/usage/format/index.html'
+anchors:
+ - Format
+ - Language Specific
+ - HTML
+ - Liquid
+ - XML
+ - CSS
+ - JSON
+ - JavaScript
+prev:
+ label: 'Rules'
+ uri: '/usage/rules'
+next:
+ label: 'Inline Control'
+ uri: '/usage/inline-control'
+---
+
+# Format
+
+Using Æsthetic in your project is straightforward: simply use the `format` method to beautify code. This method takes a `string` or `Buffer` type argument as its first parameter. You also have the option to provide an additional `rules` argument, which allows you to customize the beautification process using the passed ruleset. When you provide rules, the beautification ruleset is updated, and code will be parsed and formatted accordingly.
+
+> Rules apply immutable merges. The `esthetic.rules()` method can be used if executing consecutive formats with a ruleset that is identical for each run.
+
+#### Basic Usage
+
+
+```js
+import esthetic from "esthetic";
+
+const input = `.class { font-size: 0.95rem; background-color: pink; }`
+
+try {
+
+ const output = esthetic.format(input, {
+ language: 'css',
+ style: {
+ noLeadZero: true
+ }
+ })
+
+ console.log(output)
+
+} catch(e) {
+
+ console.error(e)
+
+}
+```
+
+## Using Language Specifics
+
+Language specific formatting methods work the same as `esthetic.format` but are refined to operate on a language specific level. These methods accept only relative rules as a second parameter as the `language` option is inferred. Language specific format methods are perfect in cases where you are performing beautification to single language.
+
+> Currently, only stable language specific methods are made available. Use the `esthetic.format` method to apply beautification on unstable languages and pass the `language` identifier via `rules`.
+
+#### Examples
+
+```js
+import esthetic from "esthetic";
+
+ // HTML Formatting
+esthetic.html('..'): string;
+
+// Liquid Formatting
+esthetic.liquid('..'): string;
+
+// XML Formatting
+esthetic.xml('..'): string;
+
+// CSS Formatting
+esthetic.css('..'): string;
+
+// JSON Formatting
+esthetic.json('..'): string;
+
+// JavaScript Formatting
+esthetic.js('..'): string;
+```
+
+## The Format Process
+
+The formatting process in Æsthetic is **synchronous** and executed in a modest two-cycle process. The first cycle involves the parse operation, this is where Æsthetic generates a data structure based on the provided code input. This first cycle can also be generated using the `esthetic.parse()` method, if cases where you only require the parse table (see [parsing](/usage/parsing)). In the second cycle, beautification takes place, this is where Æsthetic traverses the data structure generated in the first cycle to produce the final formatted output.
+
+The 2 cycle process is a fast operation and subsequent calls apply incremental traversal and updates. Æsthetic analyzes code in a performant manner because the parse table is a uniform array that uses an index based approach. There is no circular references, so re-parsing input with minimal diffs incurred will conclude 20x faster than that of an initial run.
diff --git a/docs/src/docs/usage/formatting.md b/docs/src/docs/usage/formatting.md
deleted file mode 100644
index a4fe1e3..0000000
--- a/docs/src/docs/usage/formatting.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: 'Formatting'
-layout: base
-permalink: '/usage/formatting/index.html'
-anchors:
- - Formatting
- - Language Specific
- - HTML
- - Liquid
- - XML
- - CSS
- - JSON
- - JavaScript
----
-
-# Formatting
-
-When using Æsthetic in your project, the `format` method is how you beautify code. The method accepts either a string or buffer type argument and an optional `rules` parameter can also be passed for setting beautification options.
-
-
-```js
-import esthetic from "esthetic";
-
-const input = `.class { font-size: 0.95rem; background-color: pink; }`
-
-try {
-
- const output = esthetic.format(input, {
- language: 'css',
- style: {
- noLeadZero: true
- }
- })
-
- console.log(output)
-
-} catch(e) {
-
- console.error(e)
-
-}
-```
-
-# Language Specific
-
-Language specific formatting methods work the same as `esthetic.format` but are refined to operate on a language specific level. These methods accept only relative rules as a second parameter as the `language` option is inferred.
-
-> Currently, only stable language specific methods are made available.
-
-### HTML
-
-```js
-import esthetic from "esthetic";
-
-esthetic.html('..'): string;
-
-```
-
-### Liquid
-
-```js
-import esthetic from "esthetic";
-
-// Liquid
-//
-esthetic.liquid('..'): string;
-
-```
-
-### XML
-
-```js
-import esthetic from "esthetic";
-
-// XML
-//
-esthetic.xml('..'): string;
-
-
-```
-
-### CSS
-
-```js
-import esthetic from "esthetic";
-
-// Liquid
-//
-esthetic.css('..'): string;
-
-
-```
-
-### JSON
-
-```js
-import esthetic from "esthetic";
-
-// JSON
-//
-esthetic.json('..'): string;
-
-```
-
-### JavaScript
-
-```js
-import esthetic from "esthetic";
-
-// JavaScript
-//
-esthetic.js('..'): string;
-
-```
diff --git a/docs/src/docs/usage/inline-control.md b/docs/src/docs/usage/inline-control.md
index 0611f54..790e0ec 100644
--- a/docs/src/docs/usage/inline-control.md
+++ b/docs/src/docs/usage/inline-control.md
@@ -2,6 +2,58 @@
title: 'Inline Control'
layout: base
permalink: '/usage/inline-control/index.html'
+prev:
+ label: 'Format'
+ uri: '/usage/format'
+next:
+ label: 'Parse'
+ uri: '/usage/parse'
---
-# TODO
+# Inline Control
+
+Æsthetic provides inline control options for developers using comments.
+
+### Ignore File
+
+
+```html
+
+
+
+
+
File will not be formatted
+
+
+```
+
+### Ignore Next
+
+
+```html
+
+
+
+This token will not be formatted
+
+
+
+
This will format
+
+```
+
+### Ignore Region
+
+
+```html
+
+
+
+This token will not be formatted
+
+
+
+
+
This will format
+
+```
diff --git a/docs/src/docs/usage/method-chains.md b/docs/src/docs/usage/method-chains.md
new file mode 100644
index 0000000..38cc3fd
--- /dev/null
+++ b/docs/src/docs/usage/method-chains.md
@@ -0,0 +1,40 @@
+---
+title: 'Usage - Method Chains'
+layout: base
+permalink: '/usage/method-chaining/index.html'
+---
+
+# Method Chains
+
+---
+
+## Rules
+
+## Settings
+
+The `settings` method supports chaining.
+
+
+```js
+import esthetic from 'esthetic';
+
+// We will disable stat reporting and then define some formatting rules
+// Below we deconstruct the format method, but this can also be chained
+//
+const { format } = esthetic
+.settings({ reportStats: false })
+.grammar({ html: { voids: ['singleton'] }})
+.rules({ markup: { forceIndent: true } })
+
+try {
+
+ const input = `
Hello World!
`;
+ const output = format(, { language: 'html' });
+
+ console.log(output);
+
+} catch(e) {
+ console.error(e);
+}
+
+```
diff --git a/docs/src/docs/usage/parse.md b/docs/src/docs/usage/parse.md
new file mode 100644
index 0000000..65af36b
--- /dev/null
+++ b/docs/src/docs/usage/parse.md
@@ -0,0 +1,39 @@
+---
+title: 'Parse'
+layout: base
+permalink: '/usage/parse/index.html'
+prev:
+ label: 'Inline Control'
+ uri: '/usage/inline-control'
+next:
+ label: 'Settings'
+ uri: '/usage/settings'
+anchors:
+ - Parse
+ - Basic Usage
+---
+
+# Parse
+
+The `parse` method can returns a uniform parse table data structure. Unlike many parsers that typically generate an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree), Æsthetic follows a distinct path. Its implementation of Sparser results in a uniform table-like structure.
+
+### Basic Usage
+
+
+```js
+import esthetic from "esthetic";
+
+const input = `
{% if x %}Hello World{% endif %}
`;
+
+try {
+
+ const data = esthetic.parse(sample)
+ console.log(data)
+
+} catch(e) {
+
+ console.error(e)
+
+}
+
+```
diff --git a/docs/src/docs/usage/parsing.md b/docs/src/docs/usage/parsing.md
deleted file mode 100644
index fe20943..0000000
--- a/docs/src/docs/usage/parsing.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: 'Parsing'
-layout: base
-permalink: '/usage/parsing/index.html'
-anchors:
- - Parsing
----
-
-# Parsing
-
-The `parse` method can be used to inspect the data structures that Æsthetic constructs.
-
-
-```js
-import esthetic from "esthetic";
-
-const sample = `
-
-
-
-{% if x %} Hello World {% endif %}
-
-
-
-`;
-
-try {
-
- const data = esthetic.parse(sample)
-
- console.log(data)
-
-} catch(e) {
-
- console.error(e)
-
-}
-
-```
diff --git a/docs/src/docs/usage/rules.md b/docs/src/docs/usage/rules.md
index 0348589..8fb8199 100644
--- a/docs/src/docs/usage/rules.md
+++ b/docs/src/docs/usage/rules.md
@@ -2,20 +2,35 @@
title: 'Rules'
layout: base
permalink: '/usage/rules/index.html'
+prev:
+ label: 'Config Files'
+ uri: '/usage/config-files'
+next:
+ label: 'Inline Control'
+ uri: '/usage/inline-control'
anchors:
- Rules
- -
+ - Basic Usage
+ - Read Usage
+ - Using Preset Style Guides
+ - Presets
+ - Options
---
# Rules
-The `rules` methods will augment formatting options (rules). Formatting options are persisted so when you apply changes they are used for every beautification process thereafter. This method can be used to define rules and preset the configuration logic to be used for every call you invoke relating to beautification or parsing.
+The `rules` method within Æsthetic can be used to perform immutable merges to formatting options and define customized rules for code beautification and parsing. Once applied, these formatting options are persisted, ensuring that the defined rules are consistently used for all subsequent beautification processes, until changed or session ends.
+
+> You can enable/disable rule persistence behavior using the [settings](/usage/settings/) method. When **disabled** Æsthetic will use defaults for each beautification execution.
+
+By utilizing the rules method, you can preset the configuration logic, which will be automatically employed every time a beautification or parsing operation is invoked. This enables seamless and consistent code formatting across multiple calls. In essence, the rules method empowers developers to tailor the behavior of Æsthetic according to their specific project requirements and coding preferences.
+
+#### Basic Usage
```js
import esthetic from 'esthetic';
-// Define rules to be used when formatting
esthetic.rules({
language: 'html',
indentSize: 4,
@@ -34,22 +49,154 @@ esthetic.rules({
// etc etc
}
});
+```
+
+#### Read Usage
+
+
+```js
+import esthetic from 'esthetic';
+
+esthetic.rules() // Returns the current ruleset
+
+```
+
+---
+
+# Using Preset Style Guides
+
+Æsthetic comes equipped with a useful feature called **Rule Presets**. These pre-defined style guides serve as default settings, carefully curated to assist users in achieving polished output without having to understand how each rule works. By choosing the [global](/rules#global) → [preset](/rules/global/preset) option, users can conveniently apply one of the available presets as the runtime rule defaults. This simplifies the creative process and ensures consistent, aesthetically pleasing results without introducing any unnecessary complexities or learning curves.
+
+### Presets
+
+Currently, there are **6** different presets available, each offering unique beautified output, with some presets being more extensive than others. These options provide users with a range of stylistic choices that can be used a starting point from which, you can progressively tailor and customizing to your specific tastes.
+
+
+
+### Options
+
+Below is list of available style guide preset options. Refer to the [preset](/rules/global/preset) page for comparison samples and applied definitions. In cases where the `preset` rule is `undefined`, Æsthetic will automatically default to using `default` as the base ruleset.
+
+::: rule 👍
+
+#### default
+
+:::
+
+By default, Æsthetic will use the `default` preset, which features the least obtrusive ruleset. The formatting employs a preservation-based technique, ensuring a subtle and non-intrusive approach to enhancing the output.
+
+- [Example](#)
+- [Ruleset](#)
+
+```json
+{
+ "preset": "default"
+}
+```
+
+---
+
+::: rule 👍
+
+#### recommended
-try {
+:::
- // When calling format, the rules will be used.
- const output = esthetic.format('
etc etc
')
+The `recommended` style guide preset is well-suited for most projects. Formatting will adhere to common standards and generate exceptional-based output. It shares some similarities with Prettier but takes a less aggressive approach, providing a balanced and refined way to beautify the code.
- console.log(output)
+- [Example](#)
+- [Ruleset](#)
-} catch(e) {
+```json
+{
+ "preset": "recommended"
+}
+```
+
+---
+
+::: rule 🤌
- console.error(e)
+#### warrington
+:::
+
+The `warrington` style guide preset is specifically tailored for developers, particularly teams working with Shopify themes and markup. This carefully curated preset was crafted by [David Warrington](https://ellodave.dev/), making it an excellent choice for those in the Shopify ecosystem.
+
+- [Example](#)
+- [Ruleset](#)
+
+```json
+{
+ "preset": "warrington"
}
+```
+---
+
+::: rule 🙌
+
+#### strict
+
+:::
+
+The `strict` style guide preset is curated by the author of Æsthetic, [Panoply](https://github.com/panoply). This choice embodies a refined and acquired taste. Based on existing feedback, the generated output is not for everybody as it has a focus on expressionism. However, for those who embrace it, the output when using `strict` perfectly exemplifies the very essence of why Æsthetic was created.
+
+- [Example](#)
+- [Ruleset](#)
+
+```json
+{
+ "preset": "strict"
+}
```
-# Defaults
+---
-Æsthetic provides a granular set of beautification options (rules). The projects [Typings](https://github.com/panoply/Æsthetic/tree/pre-release/types/rules) explains in good detail the effect each available rule has on code. You can also checkout the [Playground](https://liquify.dev/Æsthetic) to get a better idea of how code will be beautified.
+::: rule 🤡
+
+#### prettier
+
+:::
+
+The `prettier` style guide preset offers a replication of the Prettier style of formatting. For those working with Æsthetic in Liquid (Shopify) projects and who have grown accustomed to the Shopify Liquid Prettier Plugin, using this preset will result in a familiar output.
+
+- [Example](#)
+- [Ruleset](#)
+
+```json
+{
+ "preset": "prettier"
+}
+```
+
+---
+
+::: rule 🧐
+
+#### blanklob
+
+:::
+
+The `blanklob` preset style guide, is curated by ([Blanklob](https://github.com/blanklob)). This choice reflects a particular style that may not appeal to everyone, but is a great starting point for developers.
+
+- [Example](#)
+- [Ruleset](#)
+
+```json
+{
+ "preset": "blanklob"
+}
+```
diff --git a/docs/src/docs/usage/settings.md b/docs/src/docs/usage/settings.md
index eaf97a3..04d820f 100644
--- a/docs/src/docs/usage/settings.md
+++ b/docs/src/docs/usage/settings.md
@@ -1,9 +1,116 @@
---
-title: 'Parsing'
+title: 'Usage - Settings'
layout: base
permalink: '/usage/settings/index.html'
+prev:
+ label: 'Parse'
+ uri: '/usage/parse'
+next:
+ label: 'Events'
+ uri: '/usage/events'
anchors:
- Settings
+ - Basic Usage
+ - editorConfig
+ - globalThis
+ - reportStats
+ - throwErrors
+ - persistRules
+ - logLevel
+ - logColors
+ - resolveConfig
---
-# TODO
+# Settings
+
+Æsthetic exposes core configuration control via the `esthetic.settings()` method. The settings method can be used to configure the execution preferences of Æsthetic in Node and Browser environments. Calling the `esthetic.settings` methods with parameters omitted will return the current setting configurations being used by Æsthetic, plus some additional information such as the version number, environment and current working directory.
+
+#### Basic Usage
+
+
+```js
+import esthetic from 'esthetic';
+
+esthetic.settings({
+ editorConfig: false,
+ globalThis: true,
+ reportStats: true,
+ throwErrors: true,
+ persistRules: true,
+ logLevel: 2,
+ logColors: true,
+ resolveConfig: 'package.json'
+});
+
+```
+
+#### Read Usage
+
+
+```js
+import esthetic from 'esthetic';
+
+const settings = esthetic.settings();
+
+console.log(settings)
+
+
+```
+
+---
+
+# Available Options
+
+All settings are **optional** and changes will be persisted, similar to [rules](/usage/rules). The settings method returns `this` scope and can be chained. It's generally recommended that you provide setting customizations before invocation.
+
+##### editorConfig
+
+Whether or not Æsthetic should inherit and use options defined in `.editorconfig` files. When an `.editorconfig` file is detected in your projects root directory, Æsthetic will keep track and use inheritable options.
+
+**Default:** `false`
+
+##### globalThis
+
+Whether of not Æsthetic should be made available to global scope when used in Browser environments. This defaults to `true` resulting in Æsthetic being accessible via `window`.
+
+**Default:** `true`
+
+##### reportStats
+
+Whether or not Æsthetic should track execution statistics. When disabled, Æsthetic will skip reporting on formatting execution timing of beautification / parse operations.
+
+**Default:** `true`
+
+##### throwErrors
+
+Whether or not Æsthetic should throw exceptions when encountering a parse error. When disabled (`false`) then errors will fail quietly. Use the `esthetic.on('error', (e) => {})` event or check the `esthetic.error` to take control of parse errors when this is disabled.
+
+**Default:** `true`
+
+##### persistRules
+
+Whether or not Æsthetic should persist defined rules. By default, Æsthetic maintains a persisted reference of formatting rules. Setting this to `false` will result in Æsthetic merging rules with defaults (or `preset`) each time the `esthetic.format()`, `esthetic.parse()` or `esthetic.rules()` is invoked.
+
+**Default:** `true`
+
+##### logLevel
+
+Control the log level when using the CLI. The following levels are available:
+
+- `1` - Disables logs, only parse errors will show.
+- `2` - Standard logs, this is the default. Operations, errors and warnings.
+- `3` - Detailed logs, various information is printed throughout execution cycles
+
+**Default:** `2`
+
+##### logColors
+
+By default, operations which involve printing to console, as such, errors will apply ansi coloring. Set this to `false` to prevent highlights being applied.
+
+**Default:** `true`
+
+##### resolveConfig
+
+Use an external configuration approach for defined rules. Æsthetic supports `package.json` files containing an `esthetic` key, an `.esthetic` or `.esthetic.json` files. You can provide a uri reference to a specific file containing rules.
+
+**Default:** `package.json`
diff --git a/docs/src/rules/global/language.md b/docs/src/rules/global/language.md
index 8b661af..123cfb2 100644
--- a/docs/src/rules/global/language.md
+++ b/docs/src/rules/global/language.md
@@ -20,27 +20,17 @@ options:
- tsx
---
+::: grid col-8 p-100
+
# Language
The `language` rule is used to inform Æsthetic on the type of input that has been provided. By default, Æsthetic will attempt to detect the language of content provided. It is discouraged to omit this rule and rely upon the automatic detection of languages based on input because the internal detection logic may not always be correct.
-::: note
-
-The language reference is used to determine the lexical process operation code is to be handled.
+> The language reference is used to determine the lexical process operation code is to be handled.
:::
-# Rule Options
-
-The `language` rule is a global setting.
-
-::: rule
-#### auto
-
-:::
-
-The `auto` option is used by default and will attempt to automatically detect the language.
---
@@ -108,7 +98,8 @@ The `liquid` option refers to the **[Liquid Template Language](https://shopify.g
@@ -138,7 +129,8 @@ The `html` option refers to the **[Hyper Text Markup Language](https://en.wikipe
"forceFilter": 3
},
"markup": {
- "forceAttribute": 3
+ "forceAttribute": 3,
+ "forceIndent": true
}
}
```
diff --git a/docs/src/rules/liquid/delimiterTrims.md b/docs/src/rules/liquid/delimiterTrims.md
index aac766c..819d531 100644
--- a/docs/src/rules/liquid/delimiterTrims.md
+++ b/docs/src/rules/liquid/delimiterTrims.md
@@ -208,8 +208,10 @@ When the `delimiterTrims` rule is set to `multiline` trims will be applied to ta
```json:rules
{
"language": "liquid",
- "wrap": 40,
+ "wrap": 0,
+ "wrapFraction": 30,
"liquid": {
+ "lineBreakSeparator": "after",
"delimiterTrims": "multiline"
}
}
diff --git a/docs/src/rules/liquid/forceArgument.md b/docs/src/rules/liquid/forceArgument.md
index 6cbdf62..b5d0f1f 100644
--- a/docs/src/rules/liquid/forceArgument.md
+++ b/docs/src/rules/liquid/forceArgument.md
@@ -65,7 +65,10 @@ By default, this rule uses a value of `0` which infers forcing to apply at a len
{{ object.prop | filter_1: 'value' | filter_2: 'xxx' }}
-{% render 'snippet', param_1: true, param_2: 1000, param_3: 'string', param_4: nil %}
+{% render 'snippet',
+param_1: true, param_2: 1000,
+param_3: 'string', param_4: nil %}
+
@@ -125,14 +128,22 @@ This is an example of the `forceFilter` using a value of `3` which will result i
```liquid
{{ object.prop | filter_1: 'value' | filter_2: 'xxx' }}
-{% render 'snippet', param_1: true, param_2: 1000, param_3: 'string', param_4: nil %}
+
+{% render 'snippet',
+param_1: true, param_2: 1000,
+param_3: 'string', param_4: nil %}
{% assign x = settings.logo
| image_url: width: 500
- | image_tag: class: 'header__heading-logo motion-reduce', widths: '50, 100, 150, 200, 250, 300, 400, 500', height: logo_height, width: settings.logo_width, alt: logo_alt
+ | image_tag:
+ class: 'header__heading-logo motion-reduce'
+ , widths: '50, 100, 150, 200, 250, 300, 400, 500',
+ height: logo_height, width: settings.logo_width
+ ,
+ alt: logo_alt
| replace: ',' , 'foo'
| font_family: 'bold', '300', 'exec'
| image_url: width: 500 %}
diff --git a/docs/src/rules/liquid/forceFilter.md b/docs/src/rules/liquid/forceFilter.md
index f7457ec..a8a12c5 100644
--- a/docs/src/rules/liquid/forceFilter.md
+++ b/docs/src/rules/liquid/forceFilter.md
@@ -103,13 +103,16 @@ This is an example of the `forceFilter` using a value of `3` which will result i
```liquid
{% # No forcing will be applied as only 2 filters exist %}
-{{ object.prop | filter_1: 'value' | filter_2: 'xxx' }}
+{{ object.prop
+| filter_1: 'value'
+| filter_2: 'xxx' }}
{% # Forcing is applied because there are 3 filters %}
-{{ object.prop | filter_1: 'value' | filter_2: 'xxx' | filter_3: 'foo' }}
+{{ object.prop | filter_1: 'value' | filter_2: 'x' | filter_3: 'foo' }}
{% # No forcing will be applied as only 1 filter exists %}
-{{ object.prop | filter_1: 'value' }}
+{{ object.prop
+| filter_1: 'value' }}
```
---
diff --git a/docs/src/rules/liquid/lineBreakSeparator.md b/docs/src/rules/liquid/lineBreakSeparator.md
index d39c040..444ec26 100644
--- a/docs/src/rules/liquid/lineBreakSeparator.md
+++ b/docs/src/rules/liquid/lineBreakSeparator.md
@@ -97,7 +97,7 @@ Below is an example of how this rule works if set to `default` which is the **de
```liquid
-{% # All argument comma separators will be placed at before expression %}
+{% # Comma separated args will be placed before expression %}
{% render 'snippet',
param_1: true,
param_2: 1000,
@@ -106,16 +106,15 @@ Below is an example of how this rule works if set to `default` which is the **de
{% if condition == assertion %}
-
+{% # Comma separated args will be placed before expression %}
{{
object.prop
- | param_1: true
- | param_2: 1000
- | param_3: arg_1
- , arg_2: 2000
- , arg_3: false
- , arg_4: nil
- | param_4: 'xxxx'
+ | filter:
+ arg_1: 'foo',
+ arg_2: 2000,
+ arg_3: false,
+ arg_4: nil
+ | append: 'xxx'
}}
{% endif %}
diff --git a/docs/src/rules/liquid/quoteConvert.md b/docs/src/rules/liquid/quoteConvert.md
index 6828723..08f2189 100644
--- a/docs/src/rules/liquid/quoteConvert.md
+++ b/docs/src/rules/liquid/quoteConvert.md
@@ -29,7 +29,7 @@ How quotation characters of markup attributes and Liquid tokens should be handle
:::
-Below is an example of how this rule works if set to `none` which is the **default** setting. No conversion of quotations is applied when using `none` as per the **before** and **after** examples
+Below is an example of how this rule works if set to `none` which is the **default** setting. No conversion of quotations is applied when using `none` and one should consider setting a specific value.
```json:rules
{
diff --git a/docs/src/rules/markup/attributeSort.md b/docs/src/rules/markup/attributeSort.md
index db026b4..7a46b5f 100644
--- a/docs/src/rules/markup/attributeSort.md
+++ b/docs/src/rules/markup/attributeSort.md
@@ -19,9 +19,17 @@ Provides sorting of HTML and XML Attributes. When **enabled** (`true`) it will s
:::
----
+
+
+---
::: rule 🙌
@@ -51,6 +59,8 @@ Take the following tag with several attributes defined in no specific order. Whe
data-a="foo">
```
+---
+
::: rule 👍
#### true
@@ -80,23 +90,15 @@ Take the following tag with several attributes defined in no specific order. Whe
id="x">
```
+---
+
::: rule 🙌
#### string[]
:::
-Below is an example of how this rule works and you've defined the following attribute sorting structure
-
-```js
-{
- markup: {
- attributeSort: ['id', 'class', 'data-b', 'data-z'];
- }
-}
-```
-
-Using the above example options, let's consider the following attributes contained on a tag. Notice how each attribute is expressed in a no specific order. This will change **after** formatting as per the **after** example.
+In addition to alphabetical sorting using boolean `true`, developers may prefer to control the sorting behavior of Æsthetic. The `attributeSort` rule accepts a string list of attribute names. When provided, markup attributes will be sorted according to the list entries and then alphabetically. Custom sorting will sort in the same order passed. Click the **rules** tab to inspect the sorting logic being used in the below sample.
```json:rules
{
diff --git a/docs/src/rules/markup/delimiterTerminus.md b/docs/src/rules/markup/delimiterTerminus.md
index 180b8fc..049bcd5 100644
--- a/docs/src/rules/markup/delimiterTerminus.md
+++ b/docs/src/rules/markup/delimiterTerminus.md
@@ -20,24 +20,134 @@ Whether or not ending HTML tag delimiters should be forced onto a newline. This
---
-#### 👍 Disabled
+::: rule 🤌
-_Below is the default, which does not force ending delimiters `>` onto newlines in tags containing attributes._
+#### inline
+:::
+
+The `delimiterTerminus` rule is set to use an `inline` terminus by default. The behavior of delimiter terminus using `inline` results in the last `>` delimiter character occurrence being inlined.
+
+```json:rules
+{
+ "language": "html",
+ "preserveLine":0,
+ "markup": {
+ "forceAttribute": 2,
+ "delimiterTerminus": "inline"
+ }
+}
+```
+
+
+```html
+
+
+
+
+
+
+```
+
+---
+
+::: rule 🤡
+
+#### force
+
+:::
+
+When the `delimiterTerminus` rule is set to use `force` then formatting behavior will replicate that of Prettier. Æsthetic will use forced terminus in accordance with the [`forceAttribute`](/rules/markup/forceAttribute) defined rule and only apply forcing when structures adhere. In the below code sample, toggle the **Rules** tab and inspect the ruleset.
+
+```json:rules
+{
+ "language": "html",
+ "preserveLine": 1,
+ "markup": {
+ "forceAttribute": 3,
+ "delimiterTerminus": "force"
+ }
+}
+```
+
+
```html
-
-
+
+
+
+
+
+
+
+
+
+
+
+
```
---
-#### 👎 Enabled
+::: rule 👍
-_Below is an example of how this rule works if it's enabled, ie: `true`. Notice how the ending delimiters are forced onto newlines._
+#### adapt
+:::
+
+When the `delimiterTerminus` rule is set to use `adapt` delimiter terminus will be determined based on structures. Æsthetic will apply the terminus based on several factors and take into consideration markup rules such a [`lineBreakValue`](/rules/markup/lineBreakValue). Terminus is not guaranteed when set to `adapt` but is generally the preferred option to use.
+
+```json:rules
+{
+ "language": "html",
+ "preserveLine": 1,
+ "markup": {
+ "forceAttribute": 3,
+ "delimiterTerminus": "adapt"
+ }
+}
+```
+
+
```html
-
-
+
+
+
+
+
+
+
+
+
+
+
+
```
diff --git a/docs/src/rules/markup/preserveComment.md b/docs/src/rules/markup/preserveComment.md
index 4eeff53..fd4fcb1 100644
--- a/docs/src/rules/markup/preserveComment.md
+++ b/docs/src/rules/markup/preserveComment.md
@@ -10,29 +10,39 @@ options:
- true
---
+::: grid col-9 p-100
+
# Preserve Comment
Preserve the inner contents of HTML comments. When this rule is enabled (i.e: `true`) it will ignore formatting HTML comments and override `commentIndent` and `commentNewline` rule definitions.
-# Rule Options
+### Rule Options
The `preserveComment` rule is disabled (`false`) by default. The **recommended** setting to use is `false` unless you have extensive context contained within comments.
-##### Example
+### Example
In the below example we have enabled comment preservation. Both the `commentIndent` and `commentNewline` rules will no longer have effect on output as the the `preserveComment` rule takes precedence.
-```js
+:::
+
+::: grid col-7
+
+```json
{
"language": "html",
"liquid": {
"commentNewline": false, // This setting will be ignored
- "commentIndent": true, // This setting will be ignored
- "preserveComment": true // When enabled, this rule takes precedence
+ "commentIndent": true, // This setting will be ignored
+ "preserveComment": true // When enabled, this rule takes precedence
}
}
```
+:::
+
+---
+
::: rule 🙌
#### false
@@ -43,9 +53,9 @@ This `preserveComment` rule is set to `false` by default. In the example below,
```json:rules
{
- "language": "liquid",
+ "language": "html",
"preserveLine": 2,
- "liquid": {
+ "markup": {
"commentNewline": true,
"commentIndent": true,
"preserveComment": false
@@ -54,7 +64,7 @@ This `preserveComment` rule is set to `false` by default. In the example below,
```
-```liquid
+```html
-```liquid
+```html
Hello
diff --git a/docs/src/rules/markup/quoteConvert.md b/docs/src/rules/markup/quoteConvert.md
index d426fe8..994851c 100644
--- a/docs/src/rules/markup/quoteConvert.md
+++ b/docs/src/rules/markup/quoteConvert.md
@@ -11,54 +11,119 @@ options:
- single
---
-#### Quote Convert
+::: grid col-9 p-100
-How quotation characters of markup attributes and Liquid tokens should be handled. Allows for conversion to single quotes or double quotes. Markup tag attributes should always use double quotations, it's the standard in languages like HTML.
+# Quote Convert
-#### Tip
+How quotation characters of markup attribute values should be handled. Allows for conversion to single quotes or double quotes. Markup tag attributes should always use double quotations, it's the standard in languages like HTML.
-When working with Liquid, use `single` quotes for strings and always infer `double` in the markup.
-
-#
+:::
---
-#### 👍 `none`
+
+
+::: rule 🤡
+
+#### none
+
+:::
-_Below is an example of how this rule works if set to `none` which is the **default** setting. No conversion of quotations is applied when using `none` as per the **before** and **after** examples_
+Below is an example of how this rule works if set to `none` which is the **default** setting. No conversion of quotations is applied when using `none`. Notice how we have expressed a combination of both double and single quotes.
-```liquid
-
-
+```json:rules
+{
+ "language": "html",
+ "markup": {
+ "quoteConvert": "none"
+ }
+}
+```
+
+
+```html
+
+
+
+ Hello World!
+
+
+
-
-
```
---
-#### 👍 👍 `double`
+::: rule 🤌
+
+#### double
+
+:::
-_Below is an example of how this rule works if set to `double` which will go about converting and ensuring all markup quotations and using doubles._
+Below is an example of how this rule works if set to `double` which will go about converting and ensuring all markup quotations are using double quotations.
-```liquid
-
-
+```json:rules
+{
+ "language": "html",
+ "markup": {
+ "quoteConvert": "double"
+ }
+}
+```
+
+
+```html
+
+
+
+ Quotes will convert to doubles
+
-
-
+
```
---
-#### 👎 `single`
-_Below is an example of how this rule works if set to `single` which will go about converting and ensuring all markup quotations and using singles._
+::: rule 😳
+
+#### single
+
+:::
+
-```liquid
-
-
+Below is an example of how this rule works if set to `single` which will go about converting and ensuring all markup quotations are using singles. This is typically discourage in HTML and other markup languages.
-
-
+
+```json:rules
+{
+ "language": "html",
+ "markup": {
+ "quoteConvert": "single"
+ }
+}
+```
+
+
+```html
+
+
+
+ Quotes will convert to singles
+
+
+
```
+
diff --git a/docs/src/rules/markup/stripAttributeLines.md b/docs/src/rules/markup/stripAttributeLines.md
index 72d9f17..e7b8824 100644
--- a/docs/src/rules/markup/stripAttributeLines.md
+++ b/docs/src/rules/markup/stripAttributeLines.md
@@ -11,121 +11,95 @@ options:
- true
---
+::: grid col-9 p-100
+
# Strip Attribute Lines
Whether or not newlines contained within tag attributes should be preserved. This rule is used along side the `forceAttribute` rule. When enabled (`true`) then Æsthetic will strip _empty_ newline occurrences within HTML tags attributes. When disabled (`false`) then newlines occurrences will be preserved in accordance with the **global** `preserveLine` limit defined.
-# Related Rules
+### Related Rules
This rule wil only take effect when `forceAttribute` is enabled (ie: `true`) or a defined `forceAttribute` limit has been exceeded. The rule will also take effect if attribute forcing is being applied according to **global** `wrap` limits.
- [forceAttribute](/rules/markup/forceAttribute/)
- [preserveLine](/rules/global/preserveLine/)
-# Rule Options
-
-Below is an example of how this rule works using the following rule sets:
+:::
-```js
-{
- "preserveLine": 2, // Line preservations will respected this value
- "markup": {
- "forceAttribute": 2, // Can also be set to true but must not be false.
- "stripAttributeLines": true // This defaults to false
- }
-}
-```
+---
::: rule 👍
-#### `false`
+#### false
:::
Below is the default, wherein the attributes preserve the newlines contained within, Notice how **before** formatting there is `4` lines present but **after** formatting only `2` are preserved as per the global `preserveLine` rule value.
-
-```liquid
-
+```json:rules
+{
+ "language": "html",
+ "preserveLine": 2,
+ "markup": {
+ "stripAttributeLines": false
+ }
+}
+```
-
+
+```html
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
```
---
-::: rule 👎
+::: rule 🙌
-#### `true`
+#### true
:::
-Below is an example of how this rule works if it's enabled, ie: `true`. This will strip out empty new lines contained in markup tag attributes.
+Below is an example of how this rule works if it's enabled, ie: `true`. This will strip out empty new lines contained in markup tag attributes in accordance with `preserveLine` defined limit.
-
-```liquid
+```json:rules
+{
+ "language": "html",
+ "preserveLine": 3,
+ "markup": {
+ "stripAttributeLines": true
+ }
+}
+```
-
+
+```html
-
-
-
-
-
-
-
-
-
-
+
-
-
-
```
diff --git a/docs/src/rules/strap.md b/docs/src/rules/strap.md
index a58a7a6..9d679fa 100644
--- a/docs/src/rules/strap.md
+++ b/docs/src/rules/strap.md
@@ -26,11 +26,15 @@ This is a LANGUAGE_NAME specific formatting rule which defaults to using `preser
diff --git a/docs/src/rules/style/atRuleSpace.md b/docs/src/rules/style/atRuleSpace.md
index e69de29..e994044 100644
--- a/docs/src/rules/style/atRuleSpace.md
+++ b/docs/src/rules/style/atRuleSpace.md
@@ -0,0 +1,110 @@
+---
+title: 'Style - At Rule Space'
+layout: base
+permalink: '/rules/style/atRuleSpace/index.html'
+describe:
+ - Delimiter Trims
+ - Rule Options
+options:
+ - preserve
+ - tags
+ - outputs
+ - never
+ - always
+ - multiline
+---
+
+::: grid col-9 p-100
+
+# At Rule Space
+
+Insert or strip whitespace of `@` at rules prefixed CSS rules and their starting parenthesis.
+:::
+
+
+
+---
+
+::: rule 👍
+
+#### true
+
+:::
+
+The `atRuleSpace` style rule is enabled (i.e: `true`) by default. The rule will ensure the `@` at rules will use a single whitespace occurrences before the starting parenthesis.
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "atRuleSpace": true
+ }
+}
+```
+
+
+```css
+
+@media(min-width: 1200px) {
+ .some-selector {
+ font-size: 1.5rem;
+ background-color: whitesmoke;
+ }
+}
+
+@media(prefers-reduced-motion: reduce) {
+ .foo {
+ color: black;
+ width: 200px;
+ height: 200px;
+ }
+}
+
+```
+
+---
+
+::: rule 🤡
+
+#### false
+
+:::
+
+The `atRuleSpace` style rule is disabled (i.e: `false`) then `@` rule occurrences will have white stripped between the rule name and the starting parenthesis.
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "atRuleSpace": false
+ }
+}
+```
+
+
+```css
+
+@media(min-width: 1200px) {
+ .some-selector {
+ font-size: 1.5rem;
+ background-color: whitesmoke;
+ }
+}
+
+@media(prefers-reduced-motion: reduce) {
+ .foo {
+ color: black;
+ width: 200px;
+ height: 200px;
+ }
+}
+
+```
diff --git a/docs/src/rules/style/classPadding.md b/docs/src/rules/style/classPadding.md
index e69de29..0d90a37 100644
--- a/docs/src/rules/style/classPadding.md
+++ b/docs/src/rules/style/classPadding.md
@@ -0,0 +1,95 @@
+---
+title: 'Style - Class Padding'
+layout: base
+permalink: '/rules/style/classPadding/index.html'
+anchors:
+ - ''
+---
+
+::: grid col-9 p-100
+
+# Class Padding
+
+The `classPadding` rule will insert a newline **before** and **after** the starting and ending structure of class selectors properties.
+
+---
+
+:::
+
+
+
+::: rule 🙌
+
+#### false
+
+:::
+
+Lorem Ipsum
+
+
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "classPadding": false
+ }
+}
+```
+
+
+```css
+.class-a {
+ width: 100px;
+}
+.class-b {
+ width: 100px;
+}
+.class-c {
+ width: 100px;
+}
+.class-d {
+ width: 100px;
+}
+```
+
+---
+
+::: rule 👍
+
+#### true
+
+:::
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "classPadding": true
+ }
+}
+```
+
+
+```css
+.class-a {
+ width: 100px;
+}
+.class-b {
+ width: 100px;
+}
+.class-c {
+ width: 100px;
+}
+.class-d {
+ width: 100px;
+}
+```
diff --git a/docs/src/rules/style/commentIndent.md b/docs/src/rules/style/commentIndent.md
index e69de29..b3c00df 100644
--- a/docs/src/rules/style/commentIndent.md
+++ b/docs/src/rules/style/commentIndent.md
@@ -0,0 +1,122 @@
+---
+title: 'Style - Comment Indent'
+layout: base
+permalink: '/rules/style/commentIndent/index.html'
+describe:
+ - Comment Indent
+ - Rule Options
+options:
+ - false
+ - true
+---
+
+::: grid col-9 p-100
+
+# Comment Indent
+
+Applies single indentation to containing content of style (block) comments which span multiple lines. This is a style specific formatting rule which will be applied to CSS and SCSS Languages. It will **default** to using `false` when no option has been specified and the **recommended** option to use is `true`.
+
+---
+
+::: rule 👎
+
+#### false
+
+:::
+
+The `commentIndent` rule is **disabled** by default, so style block comments do not apply indentation. Style block comment contents will have indentation removed in the sample when formatting.
+
+
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "commentIndent": false,
+ "commentNewline": false
+ }
+}
+```
+
+
+```css
+.class-0 {
+ width: 100%;
+ height: 100%;
+ /*
+ *some comment
+ */
+ padding: 1em 3.8em;
+ overflow: auto;
+}
+/*
+* some comment
+*/
+.class-1 {
+ position: absolute;
+ z-index: 100;
+ width: 100%;
+ height: 100%;
+ /*
+ *some comment
+ */
+ margin: 0;
+ /*
+ *some comment
+ */
+ padding: 1em 3.8em;
+ overflow: auto;
+ inset: 0;
+}
+```
+
+---
+
+::: rule 🙌
+
+#### true
+
+:::
+
+Below is an example of how this rule works if it's enabled (`true`). Notice how after formatting when this rule is enabled that the inner contents of the Style block comments are indented.
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "commentIndent": true
+ }
+}
+```
+
+
+```css
+.class-0 {
+ width: 100%;
+ height: 100%;
+ /*
+ *some comment
+ */
+ padding: 1em 3.8em;
+ overflow: auto;
+}
+/*
+*some comment
+*/
+.class-1 {
+ position: absolute;
+ z-index: 100;
+ width: 100%;
+ height: 100%;
+ /*
+ * some comment
+ */
+ margin: 0;
+ /*
+ *some comment
+ */
+ padding: 1em 3.8em;
+ overflow: auto;
+ inset: 0;
+}
+```
diff --git a/docs/src/rules/style/commentNewline.md b/docs/src/rules/style/commentNewline.md
index e69de29..8392fb7 100644
--- a/docs/src/rules/style/commentNewline.md
+++ b/docs/src/rules/style/commentNewline.md
@@ -0,0 +1,113 @@
+---
+title: 'Style - Comment Newline'
+layout: base
+permalink: '/rules/style/commentNewline/index.html'
+describe:
+ - Comment Newline
+ - Rule Options
+options:
+ - false
+ - true
+---
+
+::: grid col-9 p-100
+
+# Comment Newline
+
+Inserts a new line above comment tags. When enabled the rule will add a newline even if `preserveLine` is set to `0`. The rule will not inject new lines when the previous expression is determined to already contain a new line.
+
+
+
+:::
+
+---
+
+::: rule 👎
+
+#### false
+
+:::
+
+The `commentNewline` rule is **disabled** by default. HTML comments will not insert a newline above comments.
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "commentNewline": false
+ }
+}
+```
+
+```css
+.class-0 {
+ width: 100%;
+ height: 100%;
+ /* some comment */
+ padding: 1em 3.8em;
+ overflow: auto;
+}
+/* some comment */
+.class-1 {
+ position: absolute;
+ z-index: 100;
+ width: 100%;
+ height: 100%;
+ /* some comment */
+ margin: 0;
+ /* some comment */
+ padding: 1em 3.8em;
+ overflow: auto;
+ inset: 0;
+}
+```
+
+---
+
+::: rule 🙌
+
+#### true
+
+:::
+
+When the style `commentNewline` rule is enabled (i.e: `true`) then newlines will be inserted above the comments. The first comment in the example below will have a newline inserted. The second comment will remain intact as a newline already exists.
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "commentNewline": true
+ }
+}
+```
+
+```css
+.class-0 {
+ width: 100%;
+ height: 100%;
+ /* some comment */
+ padding: 1em 3.8em;
+ overflow: auto;
+}
+/* some comment */
+.class-1 {
+ position: absolute;
+ z-index: 100;
+ width: 100%;
+ height: 100%;
+ /* some comment */
+ margin: 0;
+ /* some comment */
+ padding: 1em 3.8em;
+ overflow: auto;
+ inset: 0;
+}
+```
diff --git a/docs/src/rules/style/noLeadZero.md b/docs/src/rules/style/noLeadZero.md
index e69de29..b2017ef 100644
--- a/docs/src/rules/style/noLeadZero.md
+++ b/docs/src/rules/style/noLeadZero.md
@@ -0,0 +1,81 @@
+---
+title: 'Style - No Lead Zero'
+layout: base
+permalink: '/rules/style/noLeadZero/index.html'
+anchors:
+ - ''
+---
+
+# No Lead Zero
+
+The `noLeadZero` rule will eliminate leading zeros from numbers expressed within values.
+
+---
+
+
+
+::: rule 👍
+
+#### false
+
+:::
+
+Lorem Ipsum
+
+
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "noLeadZero": false
+ }
+}
+```
+
+
+```css
+.class-a {
+ width: 0.5px;
+ height: 0.05rem;
+ left: 0.1em;
+ right: 0.50cm;
+ top: 0.3ch;
+}
+```
+
+---
+
+::: rule 👍
+
+#### true
+
+:::
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "noLeadZero": true
+ }
+}
+```
+
+
+```css
+.class-a {
+ width: 0.5px;
+ height: 0.05rem;
+ left: 0.1em;
+ right: 0.50cm;
+ top: 0.3ch;
+}
+```
diff --git a/docs/src/rules/style/preserveComment.md b/docs/src/rules/style/preserveComment.md
index e69de29..9e32383 100644
--- a/docs/src/rules/style/preserveComment.md
+++ b/docs/src/rules/style/preserveComment.md
@@ -0,0 +1,143 @@
+---
+title: 'Style - Preserve Comment'
+layout: base
+permalink: '/rules/style/preserveComment/index.html'
+describe:
+ - Comment Newline
+ - Rule Options
+options:
+ - false
+ - true
+---
+
+::: grid col-9 p-100
+
+# Preserve Comment
+
+Preserve the inner contents of style language comments. When this rule is enabled (i.e: `true`) it will ignore formatting style comments and override `commentIndent` and `commentNewline` rule definitions.
+
+### Rule Options
+
+The `preserveComment` rule is disabled (`false`) by default. The **recommended** setting to use is `false` unless you have extensive context contained within comments.
+
+### Example
+
+In the below example we have enabled comment preservation. Both the `commentIndent` and `commentNewline` rules will no longer have effect on output as the the `preserveComment` rule takes precedence.
+
+:::
+
+::: grid col-7
+
+```json
+{
+ "language": "css",
+ "liquid": {
+ "commentNewline": false, // This setting will be ignored
+ "commentIndent": true, // This setting will be ignored
+ "preserveComment": true // When enabled, this rule takes precedence
+ }
+}
+```
+
+:::
+
+---
+
+::: rule 🙌
+
+#### false
+
+:::
+
+This `preserveComment` rule is set to `false` by default. In the example below, the Liquid comment will be formatted.
+
+```json:rules
+{
+ "language": "css",
+ "preserveLine": 2,
+ "style": {
+ "commentNewline": true,
+ "commentIndent": true,
+ "preserveComment": false
+ }
+}
+```
+
+
+```css
+/*
+
+ This comment will be preserved
+ Even though we have set both the
+ "commentNewline" and "commentIndent"
+ rules to true.
+
+ The comment tag will will align
+ itself to the li node above
+ but the content will not be touched.
+
+ This is nice when you need to provide detailed
+ descriptions or code examples within comments.
+ */
+
+code[class*="language-"] {
+ position: absolute;
+ z-index: 100;
+ width: 100%;
+ height: 100%;
+ margin: 0;
+ padding: 1em 3.8em;
+ overflow: auto;
+ inset: 0;
+}
+```
+
+---
+
+::: rule 🧐
+
+#### true
+
+:::
+
+When the `preserveComment` rule is enabled (`true`) then the contents of block comments will be excluded from formatting. As aforementioned, when set to `true` the rule will override `commentNewline` and `commentIndent` settings.
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "commentNewline": true,
+ "commentIndent": true,
+ "preserveComment": true
+ }
+}
+```
+
+
+```css
+/*
+ *
+ * This comment will be preserved
+ * Even though we have set both the
+ * "commentNewline" and "commentIndent"
+ * rules to true.
+ * The comment tag will will align
+ * itself to the li node above
+ * but the content will not be touched.
+ * This is nice when you need to provide detailed
+ * descriptions or code examples within comments.
+ */
+
+code[class*="language-"] {
+ position: absolute;
+ z-index: 100;
+ width: 100%;
+ height: 100%;
+ margin: 0;
+ padding: 1em 3.8em;
+ overflow: auto;
+ inset: 0;
+}
+```
+
+---
diff --git a/docs/src/rules/style/quoteConvert.md b/docs/src/rules/style/quoteConvert.md
index e69de29..51928eb 100644
--- a/docs/src/rules/style/quoteConvert.md
+++ b/docs/src/rules/style/quoteConvert.md
@@ -0,0 +1,123 @@
+---
+title: 'Style - Quote Convert'
+layout: base
+permalink: '/rules/style/quoteConvert/index.html'
+describe:
+ - Quote Convert
+ - Rule Options
+options:
+ - none
+ - double
+ - single
+---
+
+::: grid col-9 p-100
+
+# Quote Convert
+
+How quotation characters of style languages should be handled. Allows for conversion to single quotes or double quotes.
+
+:::
+
+---
+
+
+
+::: rule 🤡
+
+#### none
+
+:::
+
+Below is an example of how this rule works if set to `none` which is the **default** setting. No conversion of quotations is applied when using `none`, notice how both single quotes and double are expressed.
+
+
+```json:rules
+{
+ "language": "css",
+ "markup": {
+ "quoteConvert": "none"
+ }
+}
+```
+
+
+```css
+.class-1 {
+ background-image: url('./some/image/file.jpg');
+ content: url('http://www.example.com/test.png');
+ content: image-set("image1x.png" 1x, 'image2x.png' 2x);
+}
+```
+
+---
+
+::: rule 🤌
+
+#### double
+
+:::
+
+Below is an example of how this rule works if set to `double` which will go about converting and ensuring all quotations are using doubles.
+
+```json:rules
+{
+ "language": "html",
+ "markup": {
+ "quoteConvert": "double"
+ }
+}
+```
+
+
+```css
+.class-1 {
+ background-image: url('./some/image/file.jpg');
+ content: url('http://www.example.com/test.png');
+ content: image-set('image1x.png' 1x, 'image2x.png' 2x);
+}
+```
+
+---
+
+
+::: rule 😳
+
+#### single
+
+:::
+
+
+Below is an example of how this rule works if set to `single` which will go about converting and ensuring all markup quotations are using singles. This is typically discourage in HTML and other markup languages.
+
+
+```json:rules
+{
+ "language": "html",
+ "markup": {
+ "quoteConvert": "single"
+ }
+}
+```
+
+
+```css
+.class-1 {
+ background-image: url("./some/image/file.jpg");
+ content: url("http://www.example.com/test.png");
+ content: image-set("image1x.png" 1x, "image2x.png" 2x);
+}
+```
+
diff --git a/docs/src/rules/style/sortProperties.md b/docs/src/rules/style/sortProperties.md
index e69de29..8bb8ae1 100644
--- a/docs/src/rules/style/sortProperties.md
+++ b/docs/src/rules/style/sortProperties.md
@@ -0,0 +1,115 @@
+---
+title: 'Style - Sort Properties'
+layout: base
+permalink: '/rules/style/sortProperties/index.html'
+anchors:
+ - ''
+---
+
+# Sort Properties
+
+The `sortProperties` rule will apply alphabetical sorting to style class selector properties..
+
+---
+
+
+
+::: rule 🙌
+
+#### true
+
+:::
+
+Lorem Ipsum
+
+
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "sortProperties": true
+ }
+}
+```
+
+
+```css
+.class {
+ z-index: 999;
+ color: #fff;
+ width: 200px;
+ background-repeat: no-repeat;
+ background-position: top;
+ background-attachment: fixed;
+ font-weight: 100;
+ font-style: bold;
+ margin-top: 100px;
+ display: flex;
+ position: absolute;
+ float: right;
+ margin-left: 100px;
+ padding-right: 25px;
+ transition: ease-in;
+ visibility: visible;
+ padding-bottom: 40px;
+ font-weight: 100;
+ font-style: bold;
+ padding-left: 25px;
+ visibility: collapse;
+ min-inline-size: inherit;
+}
+```
+
+---
+
+::: rule 👍
+
+#### false
+
+:::
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "sortProperties": false
+ }
+}
+```
+
+
+```css
+.class {
+ z-index: 999;
+ color: #fff;
+ width: 200px;
+ background-repeat: no-repeat;
+ background-position: top;
+ background-attachment: fixed;
+ font-weight: 100;
+ font-style: bold;
+ margin-top: 100px;
+ display: flex;
+ position: absolute;
+ float: right;
+ margin-left: 100px;
+ padding-right: 25px;
+ transition: ease-in;
+ visibility: visible;
+ padding-bottom: 40px;
+ font-weight: 100;
+ font-style: bold;
+ padding-left: 25px;
+ visibility: collapse;
+ min-inline-size: inherit;
+}
+```
diff --git a/docs/src/rules/style/sortSelectors.md b/docs/src/rules/style/sortSelectors.md
index e69de29..5e46359 100644
--- a/docs/src/rules/style/sortSelectors.md
+++ b/docs/src/rules/style/sortSelectors.md
@@ -0,0 +1,103 @@
+---
+title: 'Style - Sort Selectors'
+layout: base
+permalink: '/rules/style/sortSelectors/index.html'
+anchors:
+ - ''
+---
+
+# Sort Selectors
+
+The `sortSelectors` rule will apply alphabetical sorting to style language class name selectors.
+
+---
+
+
+
+::: rule 👍
+
+#### false
+
+:::
+
+Lorem Ipsum
+
+
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "sortSelectors": false
+ }
+}
+```
+
+
+```css
+.v,
+.z,
+.y,
+.a,
+.x > .a > .b,
+.x > .c > .d,
+.c > .d > .x,
+.r,
+.t > .v > .x,
+.w,
+.b,
+.o {
+ background-position: right top;
+ background-attachment: fixed;
+ font-weight: 100;
+ font-style: bold;
+ margin-top: 100px;
+}
+```
+
+---
+
+::: rule 👍
+
+#### true
+
+:::
+
+```json:rules
+{
+ "language": "css",
+ "style": {
+ "sortSelectors": true
+ }
+}
+```
+
+
+```css
+.v,
+.z,
+.y,
+.a,
+.x > .a > .b,
+.x > .c > .d,
+.c > .d > .x,
+.r,
+.t > .v > .x,
+.w,
+.b,
+.o {
+ background-position: right top;
+ background-attachment: fixed;
+ font-weight: 100;
+ font-style: bold;
+ margin-top: 100px;
+}
+```
diff --git a/docs/src/sass/styles/overwrites.scss b/docs/src/sass/styles/overwrites.scss
index 40e97fa..1c7da74 100644
--- a/docs/src/sass/styles/overwrites.scss
+++ b/docs/src/sass/styles/overwrites.scss
@@ -34,6 +34,16 @@ h6 {
}
}
+pre + h4 {
+ margin-top: 40px;
+}
+
+h5 {
+ margin-top: 40px;
+ margin-bottom: 20px;
+ font-family: $font-family-other;
+}
+
.rule-title {
h4 {
font-family: $font-family-other;
@@ -126,7 +136,16 @@ blockquote {
ul {
margin-bottom: 20px;
}
+p {
+ a {
+ color: #6eb2d3;
+ font-weight: 500;
+ &:hover {
+ color: $white;
+ }
+ }
+}
.content-rules {
p {
width: 50%;
@@ -153,7 +172,7 @@ table {
margin: 30px 0;
tr {
- border-bottom: $border-width solid $gray-300;
+ border-bottom: $border-width solid #3d4956;
line-height: 2.2;
}
}
@@ -242,3 +261,11 @@ table {
}
}
}
+
+.icon-process {
+ width: 100%;
+ height: 450px;
+ margin: 0 auto;
+ text-align: center;
+ margin: 40px 20px 40px 0;
+}
diff --git a/docs/src/sass/styles/parser.scss b/docs/src/sass/styles/parser.scss
new file mode 100644
index 0000000..e2a56ce
--- /dev/null
+++ b/docs/src/sass/styles/parser.scss
@@ -0,0 +1,44 @@
+.parser {
+ .papyrus {
+ background-color: #12161d;
+ border-top-right-radius: 0;
+ border-bottom-right-radius: 0;
+ }
+
+ &-table {
+ background-color: #12161d;
+
+ tr {
+ border-bottom: $border-width solid $border-color;
+
+ &:hover {
+ background-color: rgba(
+ var(--papyrus-line-highlight-bg),
+ var(--papyrus-line-highlight-alpha)
+ );
+ }
+
+ &.stripe {
+ background-color: #151a22;
+ }
+
+ td {
+ font-size: $font-size-sm;
+
+ &.number {
+ width: 3em;
+ }
+
+ pre {
+ margin: 0 !important;
+ background-color: transparent;
+
+ code {
+ padding: 0;
+ font-size: $font-size-sm;
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/docs/src/sass/stylesheet.scss b/docs/src/sass/stylesheet.scss
index 055cad6..f0c3b29 100644
--- a/docs/src/sass/stylesheet.scss
+++ b/docs/src/sass/stylesheet.scss
@@ -78,6 +78,7 @@
@import 'styles/svg';
@import 'styles/demo';
@import 'styles/overwrites';
+@import 'styles/parser';
@import 'styles/navbar';
@import 'styles/breadcrumb';
@import 'styles/code';
diff --git a/docs/src/sass/variables.scss b/docs/src/sass/variables.scss
index 4f8814a..c1d052f 100644
--- a/docs/src/sass/variables.scss
+++ b/docs/src/sass/variables.scss
@@ -23,7 +23,7 @@ $enable-rfs: true;
/* PALETTE */
/* -------------------------------------------- */
-$white: rgb(240, 240, 240);
+$white: #f0f0f0;
$black: #1c1e21;
$blue: #0d6efd;
$indigo: #6610f2;
@@ -135,7 +135,7 @@ $body-bg: #0f1215; // $black; //#282a36; // $gray-100;
$body-color: $white; //$gray-900;
$code-bg: #181b20; //$black; // #282a36;
$code-inline-bg: #23262d; // #efefef;
-$link-color: $white;
+$link-color: $gray-400;
$letter-spacing-base: 1rem;
$letter-spacing-heading: 0.04rem;
@@ -177,10 +177,10 @@ $font-family-code: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono',
/* FONT SIZES */
/* -------------------------------------------- */
-$font-size-base: 0.925rem;
+$font-size-base: 1rem;
$font-size-xs: $font-size-base * 0.595;
-$font-size-sm: $font-size-base * 0.725;
+$font-size-sm: $font-size-base * 0.825;
$font-size-md: $font-size-base * 0.975;
$font-size-lg: $font-size-base * 1.25;
$font-size-xl: $font-size-base * 1.75;
@@ -280,7 +280,7 @@ $papyrus-code-padding-x: 0.5em;
$papyrus-code-border-radius: 0.5em;
$papyrus-code-color: #fafafa;
-$papyrus-code-bg: #181b20;
+$papyrus-code-bg: #12161d;
$papyrus-code-inline-bg: #eeebeb;
$papyrus-code-caret-color: #ffffff;
diff --git a/docs/src/views/include/anchors.liquid b/docs/src/views/include/anchors.liquid
index e132c1f..e15d9d8 100644
--- a/docs/src/views/include/anchors.liquid
+++ b/docs/src/views/include/anchors.liquid
@@ -4,7 +4,61 @@
data-sticky-offset-value="20">
{% for link in collections.all %}
- {% if link.url == page.url %}
+
+ {% if page.url == '/rules/' %}
+
+
diff --git a/docs/src/views/include/navigators.liquid b/docs/src/views/include/navigators.liquid
index 42fbcf3..64e365c 100644
--- a/docs/src/views/include/navigators.liquid
+++ b/docs/src/views/include/navigators.liquid
@@ -1,13 +1,13 @@
{% for link in collections.all %}
{% if link.url == page.url and link.data.prev and link.data.next %}
-
@@ -28,22 +28,16 @@
class="accordion mb-2 bx-0"
data-controller="accordion">
+ {% for link in rules.data %}
-
- {%- for link in rules.data %}
-
- {% assign base = link.title
- | slugify
- | prepend: '/' %}
+ {% assign base = link.title | slugify | prepend: '/' %}
{% assign url = link.links
- | first
- | slugify
- | prepend: '/'
- | prepend: base
- | append: '/' %}
-
-
+ | first
+ | slugify
+ | prepend: '/'
+ | prepend: base
+ | append: '/' %}
-
+
\ No newline at end of file
diff --git a/docs/src/views/include/sidebar.liquid b/docs/src/views/include/sidebar.liquid
index 499bfc2..b23dcba 100644
--- a/docs/src/views/include/sidebar.liquid
+++ b/docs/src/views/include/sidebar.liquid
@@ -31,7 +31,8 @@