I bet above description haven't been very helpful in understanding what Chapman actually does, so let's see how to use it.
The following software needs to be installed before using Chapman. These installations need to be done just once so you can skip this section if you have the software already installed.
First is Node.js, so you can work with
npm, Node package manager. You can install it from pre-built installer or using Homebrew:
brew install node
Then install Gulp globally:
npm install -g gulp
First step is to install the package globally.
npm install -g chapman
Now that you have it installed, you can initialize new project.
chapman new project-namecd project-namenpm installchapman buildchapman run
Above commands will create project-name directory and copy project files there. Next,
cd to this newly created directory and run
npm install to install all dependencies, and start up the Gulp workflow using
chapman build and
chapman run. And yeah, that's it — you're ready to rock! 🤘
For reference, below is list of all commands that you can choose from.
# Generate new project.chapman new <project-name># This task will start the browser-sync server, watch for changes in files and recompile them as needed.chapman run# Recreate whole project.chapman build
During project creation, Chapman will create below structure of files in project directory.
.├── node_modules/├── src/│ ├── assets/│ │ ├── fonts/│ │ ├── icons/│ │ ├── images/│ ├── scripts/│ ├── styles/│ ├── templates/├── .editorconfig├── .gitignore├── .jshintrc├── .scss-lint.yml├── chapman.json├── index.html├── package.json└── README.md
I bet you already know what all the files in root directory do (yeah, just pre-configured files for linting, syntax formatting, etc.), so in the next section we'll focus on the contents of src directory.
Chapman src folder consists of four main directories (these have their equivalents as Gulp tasks.) Let's find out what kind of stuff can be put to each of them and what will happen if you do this.
HTML files compiled using Twig template engine. Thanks to Twig, templates can be divided into partials and later included in main HTML files. Partials (files with _ prefix in their name) will not be copied to compiled target. Chapman uses Twig.js which means you can use basically all the functionalities from its original PHP implementation. At the end, files are prettified with JS Prettify library to ensure consistency in the output.
Place for CSS, SCSS and Sass files. SCSS and Sass files are compiled to regular CSS files with node-sass. You can use wildcard to import all the files from given directory:
Each compiled file will be automatically minified and named with -min suffix.
Fonts and images used strictly for layout purposes. They will be copied to the root of the target directory.
Thanks to svg-sprite, you can combine multiple SVG files into one that can be later used to embed inline SVG shapes in your HTML. Just put your SVG icon files in
/assets/icons and set
true in your config and you're set.
During build process, all files inside this directory will be combined into one with the same name:
You can also choose to generate good ol' font files from your icons. All you need to do is to make sure your SVG icons are in the
/assets/icons directory and you have
svgIcons set to
false in your config file.
This will allow Hacker to generate iconfont.woff and iconfont.woff2 files in your assets as well as ready to use
_icons.scss in your
/styles/common directory that you can import in your main.scss file.
chapman.json file, created in your project directory is pre-configured but you can always modify it to change behavior of Chapman.
// chapman.json// Directory where all source files are stored."source": "src"// Version of the ECMAScript you'd want to use with your project"es": "6"// Choose whether you want to generate SVG icon sprite or not"svgIcons": true// List of all targets where Chapman will compile source files.// You can also specify which tasks will be invoked for each target."targets":// Target directory path"path": "dist"// Target task list"tasks":"assets""icons""scripts""styles""templates"
Array of directories to which source will be compiled.
path points to target directory,
tasks is array of performed tasks.
Chapman is open-sourced software licensed under the MIT license.