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.
You need to run following steps only once, to setup the LiveReload using gulp.
Step 1: Install NodeJS and Yarn¶
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 will create
node_modules folder in the root.
gulp command in the root of the elegant repository.
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.
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.
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.
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
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.
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.