HTML Starter

A starter kit for HTML5 static website development with a congenial build process.

This repository could be used by anyone who's looking for a quick starter kit for static website development. This boilerplate uses Gulp for building and automating the workflow. Following are some key features we've included for you.

• Supports minification and concatination for production builds.
• The use of Sass: Syntactically Awesome Style Sheets over CSS.
• Ready to go build system using Gulp.
• Simplified development process with npm scripts.
• Ability to use your favorite bower packages.
• Organized easy to use folder structure for beginners.

Quick Links

Demo

Quick start

The generated project have dependencies that require node together with npm.

Make sure you have Node version >= 8.0 and npm >= 5 or Yarn.

# clone our repository
# --depth 1 removes all but one .git commit history
git clone --depth 1 https://github.com/brionmario/html-starter.git

# change the directory
cd html-starter

# install the dependencies
npm install

# start the development server
npm start

Once the dev server is fired up, it'll automatically open up a new tab. If not, navigate to http://0.0.0.0:3000 or http://localhost:3000 manually in your browser.

Table of Contents

• File Structure
• Getting Started
  • Prerequisites
  • Setting Up
  • Running the app
• Configuration
  • Add third-party dependencies
    • Bower
• Styling
• Deployment
  • Heroku
  • Netlify
• Built With
• Contributing
• Contributors
• License

File Structure

html-starter/
 ├── coverage/                      * unit test coverage reports
 ├── dev/                           * stores development build artifacts
 ├── dist                           * stores production build artifacts
 ├── docs/                          * contains documents and document resources
 ├── node_modules/                  * contains dependencies pulled from npm
 ├── src/                           * source folder
 │   ├── assets/                    * static assets such as images, icons, fonts goes here
 │   ├── bower_components/          * third party bower libraries will be copied here
 │   ├── sass/                      * styles folder
 │   │   ├── partials/              * place all the sass partial stylesheets in this folder
 │   │   └── styles.scss            * the main stylesheet for the project which gets compiled to CSS
 │   ├── scripts/                   * custom javascript script files
 │   └── index.html                 * entry HTML file.
 ├── .all-contributorsrc            * contains info ablout repo contributors
 ├── .babelrc                       * babel build config file
 ├── .bowerrc                       * bower config file
 ├── .buildpacks                    * contains heroku buildpacks
 ├── .dockerignore                  * contains files that are ignored from docker
 ├── .editorconfig                  * helps define and maintain consistent coding styles between different editors and IDEs
 ├── .eslintrc                      * ecmascript linting configuration file
 ├── .gitignore                     * contains files that are ignored from git
 ├── .netlify.toml                  * netlify config file
 ├── .npmrc                         * npm config file to house project wide custom configs
 ├── .nvmrc                         * node version manager config file
 ├── .pullapprove.yml               * pullapprove config file
 ├── .sass-lint.yml                 * sass linting configuration file
 ├── .travis.yml                    * travis ci configuration file
 ├── app.json                       * heroku manifest format for describing app
 ├── bower.json                     * contains bower dependencies
 ├── CONTRIBUTING.md                * project contributing guidelines
 ├── docker-compose.yml             * docker compose file
 ├── Dockerfile                     * docker config file
 ├── gulpfile.babel.js              * main buld configuration file. contains all the gulp tasks.
 ├── LICENSE.md                     * licensing information
 ├── package.json                   * contains all the npm scripts for building, running, deploying etc. and contains all the dependencies
 ├── Procfile                       * contains commands to be executed by heroku at app startup
 └── README.md                      * Readme file for the repository

Getting Started

Prerequisites

What you need to run this app:

• The generated project have dependencies that require Node.js together with npm.

Make sure you have Node.js and npm installed by running the following simple commands on the command line and see if you're running the latest stable versions.

• Node.js - Type node -v on the terminal.
• npm - Type npm -v on the terminal.

If you do not have them installed, click here and grab the latest stable version of node and npm will be automatically installed along with it. Or if you have brew already installed in your local machine, execute brew install node command to get node.

The project requires bower to install project scope dependencies such as bootstrap, jquery etc. but it is not required to install bower on your local machines since npm installs bower as a project dependency. Also bower install command is run automatically by npm as a post install script.

In addition we've created npm scripts to run gulp tasks and gulp is installed by npm as a project depency. So you don't have to install gulp or gulp cli manually on your working machine.

Setting Up

• clone the repository
• cd html-starter to change the directory
• npm install to install the dependencies with npm (installs bower dependencies as well using a post install script)

Running the app

After you have installed all dependencies you can now run the app. Run npm start to start a local server using gulp which will watch your stylesheets and javascript files for changes, compile, minify, build and reload the browser automatically using browser-sync library. The dev server will be opened in a new tab and usually on http://localhost:3000 and the Access URLs will be displayed on the terminal.

server

# development
npm start

# production
npm run server:prod

Configuration

The gulp tasks are defined inside the gulpfile.babel.js file found on the root of the application and you need to extend this file if you want to customize the application.

Add third-party dependencies

Bower

To use any third party bower libraries other than the included jquery-mobile, jquery and font-awesome libs, locate the package you want in the bower package repository and use the following command to add it to your project.

bower install $package --save

Take a look at the bellow example:

Lets say that you want to add moment.js to your project. Just run the command bellow.

bower install moment --save

NOTE: Some packages won't work as expected and you might have to do overrides in the bower.json file.

Styling

The styles.scss file inside the sass directory is the main stylesheet for the project and will be compiled and minified into an external .css and is embedded in the index.html file. If you want to add your own stylesheet, we recommend that you place it under the scss/partials folder and import it in the styles.scss file.

For example if you want to include the styles for a slider:

1. Create a _slider.scss partial file in the scss/partials directory.
2. In styles.scss add @import 'partials/slider.scss';

Testing

Execute the following command to run your unit tests. We use codecov package to generate test coverage reports and the generated reports can be found in the coverage folder.

npm run test

Linting

Execute the following commands to generate linting for styles and scripts.

# all
npm run lint

# javascript
npm run lint:scripts

# sass
npm run lint:styles

Deployment

Building the app

For Development

Execute the following command to build your files in the development mode. A new folder called dev will be created and the artifacts will be saved there.

npm run build:dev

For Production

Execute the following command to build your files in the production mode. A new folder called dist will be created and the artifacts will be saved there.

npm run build

Deploy to Heroku

Deploy to Heroku using this template with one single click. Heroku has an awesome free plan and it is extremely easy to use.

Click here to see the deployed app.

Deploy to Netlify

Deploy to Netlify using this template with one single click. It has an awesome free plan and a nifty CLI which makes the deployment process much easier.

Click here to see the deployed app.

Built With

              

Contributing

Please read CONTRIBUTING.md for contributing guidelines and to learn about our code of conduct.

Contributors

Thanks goes to these wonderful people (emoji key):

Brion Mario 💻 📖 🐛 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

License

This project is licensed under the MIT License - see the LICENSE.md file for details.