kotsu

Advanced Web Starter Kit

To boldly go where no man has gone before

---

How to use

1. Clone or download and unpack to desired location
2. Download and install latest version of node.js
3. Install grunt-cli globally: npm install -g grunt-cli
4. Install jspm globally: npm install -g jspm
5. Install GraphicsMagick (recommended) or ImageMagick for your OS. Note: it's mandatory to install one of them before running npm install
6. Set your environment variables [guide]
7. Install project dependencies: npm install
8. (optional) Add your repository to Travis for automatic tests
9. (optional) Set up Continuous Deployment with CircleCI or Werker Docker following our guide
10. Code live with: npm start or npm run start-hmr if you need hot module reloading
11. Build with: npm run build
12. Deploy and enjoy your life

What's inside?

• Reasonable structure for frontend projects
• Static pages generation
• Prepared configs for quick Continuous Deployment and automatic tests setup
• Grunt with pre-configured tasks
• Nunjucks, a full featured templating engine
• In-built Nunjucks globals and filters for formatting numbers, dates, getting current page url, locale, breadcrumb, etc.
• Human readable urls
• Boilerplate files based on best practices
• i18n with node-gettext and configured layouts to properly declare current locale and alternate urls
• Sass compiler with source maps generation, autoprefixing, optimization, minification and linting
• Ekzo Sass framework
• JSPM with ES6 support, managing and bundling JavaScript dependencies and optional hot module reloading or blazing fast watch
• standard for linting and automatic formatting JavaScript
• Live reload powered by Browser Sync
• Runtime type annotation and data validation with tcomb and tcomb-validation, built-in handy refinements.
• Preconfigured meta tags for Open Graph and Twitter Cards
• Commonly used by search providers structured data based on RDFa
• Automatic sitemap.xml generation with grunt-sitemap-xml
• Automatic sprites generation with Spritesmith
• Automatic images compression via TinyPNG
• Automatic responsive images generation with grunt-responsive-images
• Separate not optimized files in development, and
• Compiled and minified files for production

And a lot more under the hood. We just didn't have time to document all features. Yet.

Documentation

Work in progress

• Structure
• Set up environment variables
• Data
• Structured data
• Urls
• Continuous Delivery with Wercker Docker and CoreOS

Examples

Deployed version of Kotsu from master branch can be found here.

Note that Examples section so far features only least part of predefined elements and features.

Browsers support

JavaScript

IE	Edge	Chrome	Firefox	Safari	Opera	Opera Mobile	iOS Safari	Android
9+	12+	21+	28+	6.1+	12.1+	12.1+	7+	4+

To enable ES6 features in IE11 and below, uncomment import 'babel-polyfill' in main.js. See details here.

Default build shipped with jQuery 3.1.0+ which doesn't support IE8. Replace it with pre 3.0.0 version if you need support of IE8.

CSS

IE	Edge	Chrome	Firefox	Safari	Opera	Opera Mobile	iOS Safari	Android
10+	12+	21+	28+	6.1+	12.1+	12.1+	7.1+	4.4+

Refer to Ekzo Browsers Support section for details about graceful regression for IE9 and below, which included in Kotsu by default.

To disable graceful regressions for older IE, remove IE() macro call from base layout.

Outdated Browser message

In IE9 and below users will see banner before page content with message about outdated browser and link to Outdated Browser.

To disable Outdated Browser message, remove OutdatedBrowser() macro call from base layout.

License

Copyright 2014 LotusTM. Licensed under the Apache 2.0 license.

Changelog

1.9.0

Added

• [templates] Added ability to exclude certain pages from Breadcrumb() component with new Front Matter excludeFromBreadcrumb property set to true.

  It is useful for for landing or tag parent index-pages, which should never be listed in breadcrumb.

  Note, that it will also hide page from breadcrumb in search snippets.

• [templates] Added lastItemClass parameter for Breadcrumb() component, which allows to set specific class on last item of the breadcrumb.

• [modules] Added better error output for traverse and relied on it nunjucks-render and format.

  New error includes input, which failed rendering. For objects it will include currently rendered string of the leaf.

• [modules] Added error messages in case wrong values passed to getLocaleProps(), getLocaleDir() and related Nunjucks localeDir().

  This should clarify obscurity of vague and hard to debug internal errors when grunt.locales, Matter's SITE.locales or PAGE.locale are undefined or wrong.

• [conf] Added caching of node_modules for Travis.

• [tests] Added Breadcrumb() Nunjucks component tests.

Changed

• [grunt] Generated sitemap.xml will no longer have trailing slashes in URLs, which makes it uniform with trailing slash-less URLs in site navigation.

  To revert this change, remove from Grunt config sitemap_xml.options.trailingSlash: false option.

• [templates] Breadcrumb() component now will always print last item, regardless of displayLast option. However, when displayLast enabled, last item will be hidden visually and for screen readers with display: none.

  It required to confront requirements for BreadcrumbList structured data, dictated by Google. Breadcrumb should be full and include all tail.

• [templates] Breadcrumb() last item changed from <span>, which previously indicated inactive element, to fully working <a>.

  It's done to confront BreadcrumbList structured data requirements.

  If you still wish to keep last item inactive, use newly added lastItemClass option to set a specific class, like g-link--inherit, which will make anchor appear like a regular text, making it inactive for users, while still accessible for bots.

• [package][tests] Replaced NPM postbuild script, which checks clean working dir, with more reliable clean-workdir.js test.

  It will no longer occasionally pass wrongly test when grep is unavailable (like in Windows environment out of box).

• [conf] Both Travis and Circle CI will no use latest version of NPM to avoid issues with discrepancies regarding package-lock.json format.

  It is recommended to use for development latest NPM too:

  npm install -g npm@latest
  

• [conf] Enabled again package-lock.json updates on npm install for AppVeyor #289.

Fixed

• [grunt] Thanks to update of grunt-gray-matter to version 1.3.0 pages with Front Matter having syntax errors will no longer be silently ignored.

  Instead, detailed error message will be thrown.

  See #320.

• [conf] Fixed Travis ignoring failed tests and exit code 1 in postbuild phase.

  It is happened because when script runs in after_success phase exit codes 1 are ignored. See Travis docs.

  Thus, .travis.yml after_success changed to script which will properly react to exit code 1.

• [tests][package] Fixed Jest testPathIgnorePatterns which resulted in ignoring tests on some CI (like Travis).

  For instance, Travis builds into /home/travis/build/LotusTM/Kotsu, and specified /build/ in ignore patterns of Jest effectively ignored any path, which contained build. See jest#1057.

  <rootDir> has been added to ignore only contained in root build and temp directories.