build: Use prettier for markdown

Stop ignoring .md files in prettier and fix existing issues.
This commit is contained in:
Ralph Hopman
2024-12-18 17:09:22 +01:00
committed by Adam Saghy
parent 5d3271dec7
commit e3fbf8b81d
21 changed files with 269 additions and 197 deletions
+27 -24
View File
@@ -3,11 +3,11 @@
[Sass](http://sass-lang.com) is a superset of CSS, which brings a lot of developer candy to help scaling CSS in large
projects and keeping it maintainable.
The main benefits of using Sass over plain CSS are *variables*, *nesting* and *mixins*, see the
The main benefits of using Sass over plain CSS are _variables_, _nesting_ and _mixins_, see the
[basics guide](http://sass-lang.com/guide) for more details.
> Note that this project use the newer, CSS-compatible **SCSS** syntax over the old
[indented syntax](http://sass-lang.com/documentation/file.INDENTED_SYNTAX.html).
> [indented syntax](http://sass-lang.com/documentation/file.INDENTED_SYNTAX.html).
## Naming conventions
@@ -18,6 +18,7 @@ The main benefits of using Sass over plain CSS are *variables*, *nesting* and *m
- Use single quotes `'` for strings
- Use this general nesting hierarchy when constructing your styles:
```scss
// The base component class acts as the namespace, to avoid naming and style collisions
.my-component {
@@ -28,16 +29,17 @@ The main benefits of using Sass over plain CSS are *variables*, *nesting* and *m
}
}
```
Note that with
[Angular view encapsulation](https://angular.io/docs/ts/latest/guide/component-styles.html#!#view-encapsulation),
the first "namespace" level of nesting is not necessary as Angular takes care of the scoping for avoid collisions.
> As a side note, we are aware of the [BEM naming approach](https://en.bem.info/tools/bem/bem-naming/), but we found
it impractical for large projects. The nesting approach has drawbacks such as increased specificity, but it helps
keeping everything nicely organized, and more importantly, *scoped*.
> it impractical for large projects. The nesting approach has drawbacks such as increased specificity, but it helps
> keeping everything nicely organized, and more importantly, _scoped_.
Also keep in mind this general rules:
- Always use **class selectors**, never use ID selectors and avoid element selectors whenever possible
- No more than **3 levels** of nesting
- No more than **3 qualifiers**
@@ -45,43 +47,44 @@ Also keep in mind this general rules:
## Best practices
- Use object-oriented CSS (OOCSS):
* Factorize common code in base class, and extend it, for example:
- Factorize common code in base class, and extend it, for example:
```scss
// Base button class
.btn { ... }
// Color variation
.btn-warning { ... }
// Size variation
.btn-small { ... }
```
* Try to name class by semantic, not style nor function for better reusability:
- Try to name class by semantic, not style nor function for better reusability:
Use `.btn-warning`, not `btn-orange` nor `btn-cancel`
* Avoid undoing style, refactor using common base classes and extensions
- Avoid undoing style, refactor using common base classes and extensions
- Keep your style scoped
* Clearly separate **global** (think *framework*) and **components** style
* Global style should only go in `src/theme/`, never in components
* Avoid style interactions between components, if some style may need to be shared, refactor it as a framework
- Clearly separate **global** (think _framework_) and **components** style
- Global style should only go in `src/theme/`, never in components
- Avoid style interactions between components, if some style may need to be shared, refactor it as a framework
component in put it in your global theme.
* Avoid using wider selectors than needed: always use classes if you can!
- Avoid using wider selectors than needed: always use classes if you can!
- Avoid rules multiplication
* The less CSS the better, factorize rules whenever it's possible
* CSS is code, and like any code frequent refactoring is healthy
- The less CSS the better, factorize rules whenever it's possible
- CSS is code, and like any code frequent refactoring is healthy
- When ugly hacks cannot be avoided, create an explicit `src/hacks.scss` file and put it in:
* These ugly hacks should only be **temporary**
* Each hack should be documented with the author name, the problem and hack reason
* Limit this file to a reasonable length (~100 lines) and refactor hacks with proper solutions when the limit is
- These ugly hacks should only be **temporary**
- Each hack should be documented with the author name, the problem and hack reason
- Limit this file to a reasonable length (~100 lines) and refactor hacks with proper solutions when the limit is
reached.
## Pitfalls
- Never use the `!important` keyword. Ever.
- Never use **inline** style in html, even *just for debugging* (because we **KNOW** it will end up in your commit)
- Never use **inline** style in html, even _just for debugging_ (because we **KNOW** it will end up in your commit)
## Browser compatibility
You should never use browser-specific prefixes in your code, as [autoprefixer](https://github.com/postcss/autoprefixer)