Showing posts with label Gulp. Show all posts
Showing posts with label Gulp. Show all posts

Tuesday, January 30, 2018

Create static HTML website generator using Nunjucks and Gulp


In this article, we will learn how to create simple static website generator using Nunjucks and Gulp. Our implementation does not require any specific knowledge, just some basic JavaScript, and HTML. Of course, complexity depends on website functionality, but in our scenario, we will focus on the main idea of static website generation.

Tools

Project structure

|-- .editorconfig
|-- .gitattributes
|-- .gitignore
|-- src
    |-- build.sh
    |-- build.cmd
    |-- package.json
    |-- run.sh
    |-- run.cmd
    |-- gulpfile.js
    |-- build  // output directory for generated HTML
    |-- config // directory contains configuration for web server
    |-- css
    |-- img
    |-- pages // directory with web-site pages
        |-- 404.html
        |-- index.html
    |-- templates // nunjucks templates
        |-- macros
            |-- _header.html
        |-- parts
            |-- _footer.html
        |-- _globals.html
        |-- _layout.html

There are 3 files in the root of the project. .editorconfig is the interesting one. EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. More information about EditorConfig could be found using the following link http://editorconfig.org/.

Building common layout 

Nunjucks is templating engine with block inheritance, auto-escaping, macros, asynchronous control, and more. To build our website we will start with defining master page layout using nunjucks way of templating. Link to nunjucks templating documentation: https://mozilla.github.io/nunjucks/templating.html

_layout.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <link rel="stylesheet" href="/css/style.css" />
  {% block head %}
    <title>My site</title>
    <meta name="keywords" content="">
    <meta name="description" content="">
  {% endblock %}
</head>
<body>
  {% block header %} {% endblock %}
  <div class="main">
    {% block content %} {% endblock %}
  </div>
  {% include "parts/_footer.html" %}
  <!-- Common scripts placeholder. -->
  {% block scripts %}
  {% endblock %}
</body>
</html>

As you can see layout contains the reference to _footer.html. Nunjucks allows you to extract several parts of  HTML markup into reusable components.

_footer.html

{% import '_globals.html' as globals %}

<footer class="footer">
 Check out website <a href="{{globals.website_url}}">{{globals.website_url}}</a>
</footer>

Website shared settings

It is useful to have one common place where you can store global settings for your website. For such purposes, we will create the_globals.html file, where will store shared configuration. On previous code snippet, you can find an example how to use global settings.

_globals.html

{% set website_url = "http://www.maniuk.net" %}

Creating page

All pages go to pages directory. The page might extend any of specified base layouts. Following code example shows markup for a simple index page.

index.html

{% extends "_layout.html" %}
{% import 'macros/_header.html' as header %}

{% block head %}
  <title>My site</title>
  <meta name="keywords" content="">
  <meta name="description" content="">
{% endblock %}

{% block header %}
{{ header.renderHeader('index') }}
{% endblock %}

{% block content %}
Hello world!
{% endblock %}

We want current page to be highlighted in navigation menu so we will create nunjucks macro to achieve that.

_header.html

{% macro renderHeader(activePage='index') %}
<header class="header">
  <div class="logo">
    <a href="/">
      <img src="/img/logo.png" alt="logo" />
    </a>
  </div>
  <nav class="navigation">
    <ul class="navigation-list">
      <li class="navigation-list-item {%if activePage == 'index' %}current{% endif %}">
        <a href="/" class="navigation-list-link">Index</a>
      </li>
      <li class="navigation-list-item {%if activePage == '404' %}current{% endif %}">
        <a href="/404.html" class="navigation-list-link">404 Page</a>
      </li>
    </ul>
  </nav>
</header>
{% endmacro %}

Building project with gulp

First of all, we need to specify the list of dependencies we need for a successful build.

"devDependencies": {
    "browser-sync": "^2.18.13",
    "gulp": "^3.9.1",
    "gulp-autoprefixer": "^4.0.0",
    "gulp-clean-css": "^3.9.0",
    "gulp-concat": "^2.6.1",
    "gulp-htmlmin": "^3.0.0",
    "gulp-imagemin": "^3.3.0",
    "gulp-nunjucks-render": "^2.2.1",
    "gulp-sass": "^3.1.0",
    "gulp-uglify": "^3.0.0"
  },

End now it is time for a gulpfile.js file with build configuration.

gulpfile.js 

var gulp =            require('gulp'),
    browserSync =     require('browser-sync').create(),
    sass =            require('gulp-sass'),
    uglify =          require('gulp-uglify'),
    autoprefixer =    require('gulp-autoprefixer'),
    cleanCSS =        require('gulp-clean-css'),
    imagemin =        require('gulp-imagemin'),
    nunjucksRender =  require('gulp-nunjucks-render'),
    concat =          require('gulp-concat'),
    htmlmin =         require('gulp-htmlmin');

// Static Server + watching scss/html files.
gulp.task('serve', ['sass', 'nunjucks-html-watch'], function() {
    browserSync.init({
        server: './build'
    });

    gulp.watch('css/dev/*.scss', ['sass']);
    gulp.watch('./**/*.html', ['nunjucks-html-watch'])
});

gulp.task('sass', function() {
    return gulp.src('css/style.scss')
        .pipe(sass())
        .pipe(autoprefixer({
            browsers: ['last 2 versions'],
            cascade: false
        }))
        .pipe(cleanCSS())
        .pipe(gulp.dest('./build/css'))
        .pipe(browserSync.stream());
});

gulp.task('compressJs', function () {
    return gulp.src('js/*.js')
        .pipe(uglify())
        .pipe(gulp.dest('build/js'))
});

gulp.task('compressImage', function () {
    return gulp.src('img/**')
        .pipe(imagemin({
            progressive: true,
            optimizationLevel: 3
        }))
        .pipe(gulp.dest('build/img'))
});

gulp.task('nunjucks', function() {
  return gulp.src('pages/**/*.+(html|nunjucks)')
    .pipe(nunjucksRender({
      path: ['templates']
    }))
    .pipe(htmlmin(
      {
        collapseWhitespace: true,
        removeComments: true
      }))
    .pipe(gulp.dest('build'))
});

// Create a task that ensures the `nunjucks` task is complete before reloading browsers.
gulp.task('nunjucks-html-watch', ['nunjucks'], function () {
  browserSync.reload();
});

gulp.task('vendors-scripts', function() {
  return gulp.src([
      './node_modules/jquery/dist/jquery.min.js'])
    .pipe(concat('vendors.js'))
    .pipe(gulp.dest('build/js/'));
});

gulp.task('copy-files', function() {
  gulp.src([
    'config/web.config'
  ])
  .pipe(gulp.dest('build'));
});

// Compile project.
gulp.task('build-project',
  ['sass', 'compressImage', 'compressJs', 'nunjucks', 'vendors-scripts', 'copy-files']);

// Compile and start project.
gulp.task('default', ['build-project', 'serve']);

Local development

I find it handy to use gulp build-in HTTP server, developers can easily emulate a server on their machine. Following bash script runs simple HTTP server for local development.

run.sh 

#!/usr/bin/env bash
echo "Installing dependencies..."
npm install

echo "Running gulp"
./node_modules/.bin/gulp

Conclusion

Gulp and Nunjucks are great tools and it is possible to create static site generator using them. Full source code could be found on GitHub repo: https://github.com/aliakseimaniuk/blog-examples/tree/master/static-site-generator.
Posted by at
Labels: , , , , , , , ,

Wednesday, September 7, 2016

Setting up Visual Studio Code for TypeScript development


Install TypeScript compiler

To setup TypeScript on your computer, you need to setup node.js with npm. There is a good article, which will help you to do that, please find it using following link: Installing Node.js and updating npm. 
We just installed node.js and updated npm. So we are ready to install TypeScript on your computer. If you want you can install the latest build of TypeScript. To do that you have to run following command:

npm install -g typescript@next #install nightly build

Although you have the possibility to install nightly builds, I would recommend installing the latest stable version of the language. To do that type following command in cmd.exe and hit enter:

npm install -g typescript #install the latest stable version

Install Visual Studio Code with extensions


GulpTsLintVisual Studio Code

Visual Studio Code

Let's install Visual Studio Code first. You can download and install it from https://code.visualstudio.com.

TSLint

An extensible linter for the TypeScript language. TSLint supports:
  • custom lint rules
  • custom formatters (failure reporters)
  • inline disabling / enabling of rules
  • configuration presets (tslint:latest, tslint-react, etc.) & composition
For more info please use http://palantir.github.io/tslint/

To install TSLint extension: Open Visual Studio Code → Navigate to Extensions tab on left sidebar → Type 'TsLint' in search text-box → Install extension.


To make extension work you need to install tslint globally. To do that run in cmd.exe tool the command:

npm install -g tslint #installing tslint globally

Gulp Snippets

We are going to use Gulp to compile our TypeScript code, so let's install Visual Studio Code extension to help us with Gulp syntax.
Open Visual Studio Code → Navigate to Extensions tab on left sidebar → Type 'Gulp Snippets' in search text-box → Install extension.


Creating the project

First of all, you need to create the project folder. I will create mine with the name "TypeScriptBlog". Create the folder and open it in cmd.exe tool. Now we need to create package.json file. To do that run in cmd.exe command:

cd path/to/project
npm init

Open created folder in Visual Studio Code and check created file. It should contain something like this:

{
  "name": "typescriptblog",
  "version": "1.0.0",
  "description": "Blog engine written on TypeScript",
  "main": "main.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT"
}

We are now ready to install the third party dependencies:

npm install  --save-dev typescript
npm install  --save-dev tslint 
npm install  --save-dev gulp
npm install  --save-dev gulp-tslint
npm install  --save-dev gulp-typescript

Compiling the project

Create gulpfile.js in the project's  folder and copy following  content to it:

var gulp = require("gulp"),
    tslint = require("gulp-tslint"),
    tsc = require("gulp-typescript");

var tsProject = tsc.createProject("tsconfig.json");

gulp.task("build-app", function () {
    return gulp.src([
        "app/**/**.ts"
    ])
        .pipe(tsc(tsProject))
        .js.pipe(gulp.dest("app/"));
});

// Rebuild project on any ts file changed
gulp.task('watch', function() {
  gulp.watch("app/**/**.ts", ['build-app']);
});

Create tsconfig.json file and copy following content to it: 

{
    "compilerOptions": {
        "sourceMap":  true
    }
}

Now we can build our application. Press Ctrl + Shift + P in Visual Studio Code → Type "Run Task" → run "build-app" task. If you want to rebuild your code each time when any file changed, execute task with name "watch".


To test that the Gulp is working you can use following files. Create app folder in the root folder and add files to app folder.

greeter.ts


class Greeter {
    constructor(public greeting: string) { }
    greet() {
        return "<h1>" + this.greeting + "</h1>";
    }
};

var greeter = new Greeter("Hello, world!");
    
document.body.innerHTML = greeter.greet();

greeter.html


<!DOCTYPE html>
<html>
  <head><title> TypeScript Greeter </title></head>
  <body>
    <script src='greeter.js'></script>
  </body>
</html>

Project structure



Linting the project

Earlier we installed all necessary tools for linting. Now it is time to configure them. Open cmd.exe and execute command:

cd path/to/project
tslint --init

After that you can find that tslint.json file was added to the solution. This file contains default linting settings, if you would like to extend or change them, please use https://palantir.github.io/tslint/rules/ for more info.
One more thing what we can do. We want tslint be executed using Gulp, so open gulpfile.js file and add the following code to it: 

// Linting the project
gulp.task("lint", function () {
    return gulp.src([
        "app/**/**.ts"
    ])
        .pipe(tslint({
            formatter: "verbose"
        }))
        .pipe(tslint.report())
});

If 'lint' task does not appear in the task list, restart Visual Studio Code and try again.

Сonclusion

Now we know how to setup Visual Studio Code with TypeScript. With this article, I open a cycle of articles about TypeScript, in which we are going to create blog engine written on TypeScript. All the code you can find under repository https://github.com/aliakseimaniuk/TypescriptBlog. 
Posted by at
Labels: , , , , , ,
Subscribe to: Posts (Atom)