Elegant has setup gulp.js and BrowserSync for LiveReload feature to its developers and documentation writers. This is a better alternative to the Python LiveReload solution that Pelican offers by default.

Prerequisites

You need to run following steps only once, to setup the LiveReload using gulp.

Step 1: Install NodeJS and Yarn

Install Node.js and Yarn on your system.

If you are on Windows then try installing them with scoop.sh. It saves time and makes update easier.

Step 2: Install gulp

Run this command from your command line terminal.

yarn global add gulp-cli

Step 3: Install Dependencies

In the root of the Elegant repository, run

yarn install

yarn will create node_modules folder in the root.

Use LiveReload

Run gulp command in the root of the elegant repository.

gulp

It will launch the browser and open the home page. Now when you edit the templates, CSS rules, JavaScript files, Markdown, or reStructuredText files, all opened tabs will automatically reload and reflect the change.

It is set to serve the documentation at http://localhost:9001.

Why BrowserSync is better than Python-LiveReload

BrowserSync supports pretty URLs, which Python-LiveReload doesn’t.

BrowserSync has number of additional powerful features.

Interaction Sync

This is an extremely powerful and useful feature.

Your scroll, click, refresh and form actions are mirrored between browsers while you test.

What it means is when you have URL open in more than one tabs or browsers. If you scroll in one tab, other tabs mirror the scroll movement.

You can use this feature to test your website in desktop and mobile widths simultaneously. Open a link in one tab normally, and in other tab in responsive mode.

Browser Based UI

BrowserSync offers and easy to use UI. To access it, run gulp, open http://localhost:9002/ in your browser.

Debug CSS

You can add simple and depth CSS outlines to elements, or overlay CSS grid using BrowserSync. Open http://localhost:9002/remote-debug in your browser.

Network Throttle

You can test website on a slower network connection. To access open http://localhost:9002/network-throttle

Is gulp.js necessary to use?

We have plans to use gulp.js to utilize tools like PostCSS and Autoprefixer, in future. Currently we use gulp.js to watch for file changes.

Pelican helper scripts does not watch for file changes. BrowserSync only watches the files that it servers, i.e. HTML, CSS and JS files. This means you need an external tool like gulp.js to watch Markdown and Jinja2 files.

Can I avoid using gulp.js?

No. You shouldn’t. Because the alternate is not nice.

We tried to use BrowserSync without gulp.js but due to limitation in Pelican helper scripts, it didn’t pan out.

We installed BrowserSync. Then on one terminal, from documentation folder, we ran

invoke regenerate

In other terminal, from documentation folder, we ran

browser-sync start --server output --files output

regenerate task compiles Markdown files to HTML. BrowserSync automatically picks the changed HTML files and reload the URLs.

Unfortunately, regenerate keeps “regenerating” even if no file has changed. As a result, BrowserSync keeps reloading the URL every second. It becomes useless because you cannot inspect HTML elements, view console or change CSS rules from the browser, because the URL is constantly overloading.

This forced us to resort to gulp.js for file watching.

Like this post? Share on: TwitterFacebookEmail


Talha Mansoor Avatar Talha Mansoor is the creator and lead developer of Elegant theme.

Published

Category

Contributing

Stay in Touch

Get New Release Alert