ch4o5/locomotive-boilerplate
Template
1
0
Fork 0
mirror of https://github.com/locomotivemtl/locomotive-boilerplate.git synced 2026-01-15 00:55:08 +08:00
Code Issues Projects Releases Wiki Activity

Update README and documentation

Browse Source 
Changed:
- Features, Installation, and Development sections in README.
- Introduction, Configuration, and Tasks in Development.
- Heading levels in Technologies.

Fixed:
- Anchors to option sections in Development.
This commit is contained in:
Chauncey McAskill
2022-03-24 13:57:28 -04:00
parent 97d9f1ec00
commit 9a01c0f17f
3 changed files with 84 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@@ -8,13 +8,13 @@
## Features ## Features
* Uses a custom, easily configured, wrapper [asset handler](docs/development.md). * Uses a custom [task runner](docs/development.md) for handling assets.
* Uses [Sass] for a feature rich extension of CSS. * Uses [BrowserSync] for fast development and testing in browsers.
* Uses [ESBuild] for extremely fast processing of JS/ES6. * Uses [Sass] for a feature rich superset of CSS.
* Uses [ESBuild] for extremely fast processing of JS/ES modules.
* Uses [SVG Mixer] for processing SVG files and generating spritesheets. * Uses [SVG Mixer] for processing SVG files and generating spritesheets.
* Uses [ITCSS] for a sane and scalable CSS architecture. * Uses [ITCSS] for a sane and scalable CSS architecture.
* Uses [Locomotive Scroll] for smooth scrolling with parallax effects. * Uses [Locomotive Scroll] for smooth scrolling with parallax effects.
* Uses [BrowserSync] for fast development and testing in browsers.
Learn more about [languages and technologies](docs/technologies.md). Learn more about [languages and technologies](docs/technologies.md).
@@ -61,6 +61,9 @@ Then update the following files to suit your project:
## Installation ## Installation
```sh ```sh
# Switch to recommended Node version from .nvmrc
nvm use
# Install dependencies from package.json # Install dependencies from package.json
npm install npm install
``` ```
@@ -68,7 +71,7 @@ npm install
## Development ## Development
```sh ```sh
# Watch for file changes and compile assets # Start development server, watch for changes, and compile assets
npm start npm start
# Compile and minify assets # Compile and minify assets
@@ -82,14 +85,14 @@ Learn more about [development and building](docs/development.md).
* [Development and building](docs/development.md) * [Development and building](docs/development.md)
* [Languages and technologies](docs/technologies.md) * [Languages and technologies](docs/technologies.md)
[BrowserSync]: https://browsersync.io/ [BrowserSync]: https://npmjs.com/package/browser-sync
[ESBuild]: https://esbuild.github.io/ [ESBuild]: https://npmjs.com/package/esbuild
[ITCSS]: https://itcss.io/ [ITCSS]: https://itcss.io/
[Locomotive Scroll]: https://github.com/locomotivemtl/locomotive-scroll [Locomotive Scroll]: https://npmjs.com/package/locomotive-scroll
[modularJS]: https://github.com/modularorg/modularjs [modularJS]: https://npmjs.com/package/modujs
[modularLoad]: https://github.com/modularorg/modularload [modularLoad]: https://npmjs.com/package/modularload
[Sass]: https://sass-lang.com/ [Sass]: https://sass-lang.com/
[SVG Mixer]: https://github.com/JetBrains/svg-mixer [SVG Mixer]: https://npmjs.com/package/svg-mixer
[Node]: https://nodejs.org/ [Node]: https://nodejs.org/
[NPM]: https://npmjs.com/ [NPM]: https://npmjs.com/
[NVM]: https://github.com/nvm-sh/nvm [NVM]: https://github.com/nvm-sh/nvm

82
docs/development.md
View File

@@ -1,24 +1,13 @@
# Development # Development
Essentially, the boilerplate uses:
* [esbuild] for processing JS,
* [node-sass] for processing CSS,
* [svg-mixer] for processing SVG,
* [browsersync] for testing in browsers.
See [technologies](./technologies.md) for details.
---
* [Installation](#installation) * [Installation](#installation)
* [Usage](#usage) * [Usage](#usage)
* [Configuration](#configuration) * [Configuration](#configuration)
* [Environment Configuration](#environment-configuration) * [Environment Configuration](#environment-configuration)
* [Development Configuration](#development-configuration) * [Development Configuration](#development-configuration)
* [`paths` option](#paths-option) * [`paths` option](#paths-option)
* [`paths.url` option](#paths.url-option) * [`paths.url` option](#pathsurl-option)
* [`paths.dest` option](#paths.dest-option) * [`paths.dest` option](#pathsdest-option)
* [`tasks` option](#tasks-option) * [`tasks` option](#tasks-option)
* [`server` option](#server-option) * [`server` option](#server-option)
* [Tasks](#tasks) * [Tasks](#tasks)
@@ -27,9 +16,24 @@ See [technologies](./technologies.md) for details.
* [`styles`](#styles) * [`styles`](#styles)
* [`svgs`](#svgs) * [`svgs`](#svgs)
---
The boilerplate provides a custom, easily configured, and very simple,
task runner for [Node] to process assets and test quickly in browsers.
Learn more about the boilerplate's [tasks](#tasks) below.
## Installation ## Installation
Make sure you have the following installed:
* [Node] — at least 14.17, the latest LTS is recommended.
* [NPM] — at least 6.0, the latest LTS is recommended.
```sh ```sh
# Switch to recommended Node version from .nvmrc
nvm use
# Install dependencies from package.json # Install dependencies from package.json
npm install npm install
``` ```
@@ -63,7 +67,7 @@ In fresh copy of the boilerplate, the root directory of your project
will contain a [`loconfig.example.json`](../loconfig.example.json) file. will contain a [`loconfig.example.json`](../loconfig.example.json) file.
> 💡 The boilerplate's default example customizes the development server > 💡 The boilerplate's default example customizes the development server
> with a custom SSL certificate. > to use a custom SSL certificate.
That file can be copied to `loconfig.local.json` and customized to suit That file can be copied to `loconfig.local.json` and customized to suit
your local environment. your local environment.
@@ -81,8 +85,10 @@ behaviour for processing front-end assets.
#### `paths` option #### `paths` option
The `paths` setting is primarily used for template tags to reference The `paths` option defines URIs and file paths.
any configuration properties, such as file paths, to reduce repetition.
It is primarily used for template tags to reference any configuration
properties to reduce repetition.
Template tags are specified using `{% %}` delimiters. They will be Template tags are specified using `{% %}` delimiters. They will be
automatically expanded when tasks process paths. automatically expanded when tasks process paths.
@@ -98,8 +104,8 @@ automatically expanded when tasks process paths.
"tasks": { "tasks": {
"styles": [ "styles": [
{ {
"infile": "{% paths.styles.src %}/main.scss", // ./assets/styles/main.scss "infile": "{% paths.styles.src %}/main.scss", // → ./assets/styles/main.scss
"outfile": "{% paths.styles.dest %}/main.css" // ./www/assets/styles/main.css "outfile": "{% paths.styles.dest %}/main.css" // → ./www/assets/styles/main.css
} }
] ]
} }
@@ -109,6 +115,7 @@ automatically expanded when tasks process paths.
#### `paths.url` option #### `paths.url` option
The `paths.url` option defines the base URI of the project. The `paths.url` option defines the base URI of the project.
By default, it is used by the development server as a proxy By default, it is used by the development server as a proxy
for an existing virtual host. for an existing virtual host.
@@ -123,8 +130,9 @@ for an existing virtual host.
#### `paths.dest` option #### `paths.dest` option
The `paths.dest` option defines the public web directory of the project. The `paths.dest` option defines the public web directory of the project.
By default, it is used by the development server as the base directory By default, it is used by the development server as the base directory
to serve the website from. to serve the website from if a proxy URI is not provided.
```json ```json
{ {
@@ -137,7 +145,7 @@ to serve the website from.
#### `tasks` option #### `tasks` option
Which assets and how they should be processed can be configured via Which assets and how they should be processed can be configured via
the `tasks` setting: the `tasks` option:
```json ```json
{ {
@@ -165,7 +173,7 @@ See [tasks](#tasks) section, below, for details.
#### `server` option #### `server` option
The development server (BrowserSync) can be configured via The development server (BrowserSync) can be configured via
the `server` setting: the `server` option:
```json ```json
{ {
@@ -184,12 +192,14 @@ for all options.
## Tasks ## Tasks
The boilerplate provides a handful of "tasks" for handling The boilerplate provides a handful of tasks for handling
the most commonly processed assets. the most commonly processed assets.
### `concats` ### `concats`
For concatenating multiple files. A wrapper around [concat] (with optional support for globbing) for concatenating multiple files.
By default, [tiny-glob] is installed with the boilerplate.
Example: Example:
@@ -223,7 +233,7 @@ See [`concats.js`](../build/tasks/concats.js) for details.
### `scripts` ### `scripts`
For bundling and minifying modern JS/ES6 modules. A wrapper around [esbuild] for bundling and minifying modern JS/ES modules.
Example: Example:
@@ -252,7 +262,10 @@ See [`scripts.js`](../build/tasks/scripts.js) for details.
### `styles` ### `styles`
For compiling and minifying Sass into CSS. A wrapper around [node-sass] (and optionally [Autoprefixer] via [PostCSS])
for compiling and minifying Sass into CSS.
By default, [PostCSS] and [Autoprefixer] are installed with the boilerplate.
Example: Example:
@@ -287,7 +300,8 @@ See [`styles.js`](../build/tasks/styles.js) for details.
### `svgs` ### `svgs`
For transforming and minifying SVG files and generating spritesheets. A wrapper around [SVG Mixer] for transforming and minifying SVG files
and generating spritesheets.
Example: Example:
@@ -314,7 +328,15 @@ Example:
See [`svgs.js`](../build/tasks/svgs.js) for details. See [`svgs.js`](../build/tasks/svgs.js) for details.
[browsersync]: https://browsersync.io/ [Autoprefixer]: https://npmjs.com/package/autoprefixer
[esbuild]: https://esbuild.github.io/ [BrowserSync]: https://npmjs.com/package/browser-sync
[node-sass]: https://github.com/sass/node-sass [concat]: https://npmjs.com/package/concat
[svg-mixer]: https://github.com/JetBrains/svg-mixer [esbuild]: https://npmjs.com/package/esbuild
[fast-glob]: https://npmjs.com/package/fast-glob
[glob]: https://npmjs.com/package/glob
[globby]: https://npmjs.com/package/globby
[Node]: https://nodejs.org/
[node-sass]: https://npmjs.com/package/node-sass
[PostCSS]: https://npmjs.com/package/postcss
[SVG Mixer]: https://npmjs.com/package/svg-mixer
[tiny-glob]: https://npmjs.com/package/tiny-glob

36
docs/technologies.md
View File

@@ -22,7 +22,7 @@ We use [node-sass] (LibSass) for processing and minifying SCSS into CSS.
We also use [PostCSS] and [Autoprefixer] to parse our CSS and add We also use [PostCSS] and [Autoprefixer] to parse our CSS and add
vendor prefixes for experimental features. vendor prefixes for experimental features.
#### CSS Architecture ### CSS Architecture
The boilerplate's CSS architecture is based on [Inuit CSS][inuitcss] and [ITCSS]. The boilerplate's CSS architecture is based on [Inuit CSS][inuitcss] and [ITCSS].
@@ -37,7 +37,7 @@ The boilerplate's CSS architecture is based on [Inuit CSS][inuitcss] and [ITCSS]
Learn more about [Inuit CSS](https://github.com/inuitcss/inuitcss#css-directory-structure). Learn more about [Inuit CSS](https://github.com/inuitcss/inuitcss#css-directory-structure).
#### CSS Naming Convention ### CSS Naming Convention
We use a simplified [BEM] (Block, Element, Modifier) syntax: We use a simplified [BEM] (Block, Element, Modifier) syntax:
@@ -45,7 +45,7 @@ We use a simplified [BEM] (Block, Element, Modifier) syntax:
* `.block_element` * `.block_element`
* `.-modifier` * `.-modifier`
#### CSS Namespacing ### CSS Namespacing
We namespace our classes for more UI transparency: We namespace our classes for more UI transparency:
@@ -57,7 +57,7 @@ We namespace our classes for more UI transparency:
Learn about [namespacing](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/). Learn about [namespacing](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/).
#### Example \#1 ### Example \#1
```html ```html
<div class="c-block -large"> <div class="c-block -large">
@@ -90,7 +90,7 @@ Learn about [namespacing](https://csswizardry.com/2015/03/more-transparent-ui-co
## Scripts ## Scripts
We use [esbuild] for bundling and minifying JavaScript/ES6. We use [esbuild] for bundling and minifying JavaScript/ES modules.
[modularJS] is a small framework we use on top of ES modules. [modularJS] is a small framework we use on top of ES modules.
@@ -99,9 +99,9 @@ We use [esbuild] for bundling and minifying JavaScript/ES6.
* Quickly set scoped events with delegation. * Quickly set scoped events with delegation.
* Simply select DOM elements scoped in their module. * Simply select DOM elements scoped in their module.
[_source_](https://github.com/modularorg/modularjs#why) [_source_](https://npmjs.com/package/modujs#why)
#### Example \#2 ### Example \#2
```html ```html
<div data-module-example> <div data-module-example>
@@ -138,7 +138,7 @@ Learn more about [modularJS].
[modularLoad] is used for page transitions and lazy loading. [modularLoad] is used for page transitions and lazy loading.
#### Example \#3 ### Example \#3
```html ```html
<nav> <nav>
@@ -169,7 +169,7 @@ Learn more about [modularLoad].
[Locomotive Scroll][locomotive-scroll] is used for elements in viewport [Locomotive Scroll][locomotive-scroll] is used for elements in viewport
detection and smooth scrolling with parallax. detection and smooth scrolling with parallax.
#### Example \#4 ### Example \#4
```html ```html
<div data-module-scroll> <div data-module-scroll>
@@ -189,19 +189,19 @@ this.scroll = new LocomotiveScroll({
Learn more about [Locomotive Scroll][locomotive-scroll]. Learn more about [Locomotive Scroll][locomotive-scroll].
[Autoprefixer]: https://autoprefixer.github.io/ [Autoprefixer]: https://npmjs.com/package/autoprefixer
[BEM]: https://bem.info/ [BEM]: https://bem.info/
[BrowserSync]: https://browsersync.io/ [BrowserSync]: https://npmjs.com/package/browser-sync
[esbuild]: https://esbuild.github.io/ [esbuild]: https://npmjs.com/package/esbuild
[inuitcss]: https://github.com/inuitcss/inuitcss [inuitcss]: https://github.com/inuitcss/inuitcss
[ITCSS]: https://itcss.io/ [ITCSS]: https://itcss.io/
[locomotive-scroll]: https://github.com/locomotivemtl/locomotive-scroll [locomotive-scroll]: https://npmjs.com/package/locomotive-scroll
[modularJS]: https://github.com/modularorg/modularjs [modularJS]: https://npmjs.com/package/modujs
[modularLoad]: https://github.com/modularorg/modularload [modularLoad]: https://npmjs.com/package/modularload
[node-sass]: https://github.com/sass/node-sass [node-sass]: https://npmjs.com/package/node-sass
[PostCSS]: https://postcss.org/ [PostCSS]: https://npmjs.com/package/postcss
[Sass]: https://sass-lang.com/ [Sass]: https://sass-lang.com/
[svg-mixer]: https://github.com/JetBrains/svg-mixer [svg-mixer]: https://npmjs.com/package/svg-mixer
[Node]: https://nodejs.org/ [Node]: https://nodejs.org/
[NPM]: https://npmjs.com/ [NPM]: https://npmjs.com/
[NVM]: https://github.com/nvm-sh/nvm [NVM]: https://github.com/nvm-sh/nvm