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.7.0

Added

• [package] Added package-lock.json for Node 8+.

• [package] Added browserslist to package.json with preseted browsers queries. See article for details.

• [package] Added tcomb and tcomb-validation for runtime type annotation and data validation. See #165 for details.

• [package] Added URI.js.

• [package][grunt] Added ability to pass command line argument from npm start and npm run build to grunt. For instance, this can be useful to build website in production mode with npm start -- --production

• [package][grunt][templates][data] Added ability to run Kotsu optionally with regular watch or hot reloading, on demand.

  As turned out, hot reloading doesn't work that well for non-SPA applications. But we thought, why would we force devs to chooses only certain approach?

  So, now devs can choose between launching fast JSPM watch with npm start, or use hot module reloading with npm run start-hmr.

  That easy!

• [grunt] Added grunt-responsive-images-extender task which automatically expands images src with srcset when there are same images available with different images sizes and prefixed with @. This will significantly reduce images-related payload on small devices. Note, that task doesn't watch for images changes. It will run only once during npm start and as part of npm run build, since it's more production-related optimization.

• [grunt] Added cache busting for images (.jpg, .jpeg, .gif, .png, .svg) with query string. This won't affect the final name of an image but will prevent that awkward situation, when your boss asks you why he still sees old image on production...

• [grunt] Added tiny debouncing delay for Browser Sync. It will prevent a huge amount of reloads when a lot of files changing in a row (for instance, after all, Nunjucks templates recompilation).

• [grunt] grayMatter task now uses urljoin() for URLs resolution to make path concatenation more reliable and no longer relies on Node URL resolver.

• [templates] Added AlternateUrls() Nunjucks component which encapsulates logic around generating alternate URLs meta tags in _base.nj.

  Well, not like you'd need to use that component anywhere on your own, but had to put a note about it somewhere... you know...

• [templates] Added ability to specify body class for specific pages with bodyClass Matter data, pageDefault.bodyClass in default data or {{ config('page.bodyClass', ...) }} within Nunjucks template.

• [templates] Added ability to specify page-specific viewport with viewport Matter data.

• [templates] Added to _base.nj layout blocks {% block imports %}, {% block fonts %}, {% block css %} and {% block js %} which encapsulates macros imports, fonts-related stylesheets, site stylesheets and <script> tags respectively.

  It allows to extend base layout and whenever needed to override font, CSS or JavaScript content on demand by calling block with desired content:

  {% block css %}
  <link rel='stylesheet' href='/myStyles.css'>
  {% endblock %}
  

  Or use {{ super() }} inside any block to invoke original _base.nj blocks content whenever page should use same stylesheets or scripts, but you need to add few additional files:

  {% block css %}
  {{ super() }}
  <link rel='stylesheet' href='/myOtherStyles.css'>
  {% endblock %}
  

  Since _base.nj contains only basic HTML wrapper and encapsulates mostly meta data-related features, those changes make it a good basement for all website pages, even unique ones, thus eliminating need to replicate _base.nj functionality for those pages.

• [templates] Added Open Graph locale:alternate meta tags based on SITE.locales data.

• [templates][data] Added ability to specify Open Graph and Twitter meta data for specific pages by porviding one of the following properties as Matter Data or PAGE_DEFAULTS in general data:

  ---
  og:
    type:
    site_name:
    url:
    title:
    description:
    image:
    locale:
    locale:alternate:
  
  twitter:
    card:
    site:
    creator:
    url:
    title:
    description:
    image:
    image:alt:
  

  If not provided, meta properties will fallback to page or site generic values, as before.

  Related to #219. Solves #175.

• [templates][data] Added ability to specify canonical urls for specific pages with Matter Data, using following structure:

  canonical:
    - test/page
    - https://othersite.com
  

• [templates][data] Added ability to specify alternate urls for specific pages with Matter Data, using following structure:

  alternate:
    - locale: mylocale
      url: test/page
    - locale: extlocale
      url: https://othersite.com
  

• [templates][data] Added PAGE.image Matter Data property, which allows specifying generic meta image for the page. It can be used by other pages (for instance, to generate a table of content with previews or for structured data markup) and also will specify an image for Open Graph and Twitter meta data, unless they have already specified images. Related to #219.

• [data][templates] Added SITE.logo data property for main site logo, which defaults to logo.svg and used in _main.nj layout.

• [templates] Added vocab='https://schema.org/' to top-level <html> of _base.nj. This means that you can use freely Schema vocabulary without specifying or prefixing it as typeof='ListItem' instead of vocab='https://schema.org/' typeof='ListItem' or typeof='schema:ListItem' whenever you extend base layout.

• [templates] Added ability to reference website's Organization structured data by stating resource='#this'.

• [templates] Added ability to reference website structured data by stating resource='#this-website'.

• [templates] Added structured data for blog posts according to Google guidlines.

• [templates] Added structured data for the website and preferred site name according to Google guidlines.

• [templates] Added structured data for Breadcrumb component according to Google guidlines.

• [templates] Added structured data for logo according to Google guidlines.

• [templates] Added structured data for social profiles according to Google guidlines.

• [templates] Whenever URL concatenation involved now used urljoin() instead of plain concatenation.

• [templates] Added manifest.json as Nunjucks template manifest.json.nj, which uses Kotsu data #270

• [modules][templates] Added URI.js as URI() Nunjucks function.

• [modules][templates] Added absoluteurl() Nunjucks function, which will resolve relative or absolute URLs to full URL, with site homepage, based on current page URL, while already full URLs, with protocols, will remain unaffected.

• [static][templates] Added more favicons variations to work better with modern browsers.

• [tests] Added tests for Nunjucks render() filter.

• [tests] Added validate() test utility which wraps tcomb-validate and print nice errors on fail.

• [tests] Added some handy tcomb refinements to make life easier and your data truthy:

  • False — to accept only false
  • Absoluteurl — to accept only absolute URLs, like https://wowsomuch.test
  • Imagepath — to accept only paths with images, like testme.png
  • Handle — to accept only handle, like @lotustm. Useful for Twitter-related data, you know.
  • Maxlength — to accept only strings, numbers or array (or anything with .length property) which doesn't exceed a specified length.
  • EqualKeyAndProp — to accept only objects, in which some properties are equal to key value. For instance, when you need to ensure that object key and id property are always equal.

• [tests][data] Added index.test.coffee the file which tests data index file with tcomb to ensure that Kotsu receives all required data with valid values. Wrong data, you shall not pass!

  Also, it serves as an example for writing project-specific data validation files.

• [tests] Added isActive() Nunjucks function tests.

• [images][templates] Hardly believable, but we have finally added Kotsu logo as logo.svg file and placed it in _main.nj layout. Now it serves as a placeholder for your beloved logo file.

Changed

• [package] Updated dependencies.

• [package] npm start will now run regular JSPM watch instead of hot reloading. For hot reloading use npm run start-hmr command.

• [package] Changed npm-run-all --parallel to shortcut run-p.

• [package] Moved check of clean workint tree with Git after grunt build into standalone postbuild script, which will automatically execute after npm run build.

  This will also allow to pass any options to grunt with npm run build -- --myOption.

  #193

• [misc] With update of Stylelint to 7.12.0 updated .stylelintrc.yml config accordingly. Note, that you might need to change selector-no-id, selector-no-universal and selector-no-type to selector-max-id, selector-max-universal and selector-max-type respectively, and don't forget about stylelint-disable directives.

• [conf] Replaced Stylelint rule at-rule-no-unknown with newly added stylelint-scss rule scss/at-rule-no-unknown.

• [conf] Enabled selector-max-attribute Stylelint rule and set to 0, so you might need to check your selectors.

• [conf] Enabled Stylelint at-rule-empty-line-before rule.

• [conf] Enabled Stylelint declaration-empty-line-before rule.

• [conf] declaration-colon-newline-after Stylelint rule set to always-multi-line, which forces to write list values on multiple lines for better readability.

• [ci] switched CI to latest node LTS release (v8.0.0).

• [templates] Moved Host and Sitemap directives in robots.txt under the User-agent directive, in accordance with guidelines.

• [templates] Replaced all occurrences of metaDesc Matter Data property with description. This will make it more unified with package.json, Open Graph and Twitter naming.

• [templates] Replaced all occurrences of shortDesc Matter Data property with more common excerpt.

• [data] All data properties are in upper case now. It effectively denotes global data from local, defined within specific template, and with their new constants-like appearance showing that it is better to be accurate when reconfiguring those properties internals or better not to touch them at all.

  As result of that change, all templates and other parts of Kotsu should now access following global properties:

  • PAGE instead of page
  • PATH instead of path
  • SITE instead of site
  • PAGE_DEFAULTS instead of pageDefaults
  • ENV instead of env

  See #258 for details.

• [data][templates] Declared in Nunjucks _base.nj layout SITE.placeholders are now part of source/data/index and declared within new global property PLACEHOLDERS, which contains all global placeholders for format() Nunjucks function.

  This means, that all format(SITE.placeholders) instanced should be changed to format(PLACEHOLDERS).

• [data][grunt] data.PAGE_DEFAULTS previously didn't became part of Matter Data and was injected only on _base.nj invocation. That made accessing this data in other instances problematic. Now, data.PAGE_DEFAULTS will be injected during grayMatter task instead.

• [date][templates] Replaced SITE.desc with more common description to be more consistent with package.json.

• [data][templates] Old social-related properties in SITE replaced with more verbose SOCIAL property, which encapsulates data about site's social presence following this scheme:

  SOCIAL:
    # Add any other social services following same pattern
    twitter:
      handle: pkg.twitter
      image: imagesPath + '/twitter.png'
      url: "https://twitter.com/#{pkg.twitter}"
    facebook:
      image: imagesPath + '/facebook.png'
      url: 'https://www.facebook.com/Lotus-TM-647393298791066/'
  

  This data can be later used to generate site social icons or for structured data.

• [data][templates] Default value for Open Graph and Twitter image meta data no longer hard coded to facebook.png and twitter.png, but instead part of data and exposed as SOCIAL.faceebook.image and SOCIAL.twitter.image properties.

• [templates] Open Graph and Twitter images properties now uses new absoluteurl() Nunjucks function to resolve the path to images. This means, that you can freely enter as a path to image remote URL, or local absolute, or local relative URL, and it will be properly resolved.

• [templates] Replaced redundant ternary operators in base layout and some components with simple or operator. Example: {{ PAGE.title if PAGE.title else SITE.name }} -> {{ PAGE.title or SITE.name }}.

• [templates] In Nav() component {% call(depth) Item('/') %}{% endcall %} changed to exact mode to not match inner routes due to introduced in isActive() fix.

• [templates] Link() component refactored and will no longer throw any warnings itself in case of document-relative URLs since it is handled by relied upon isActive(). It also will trim whitespace to reduce issues with inlined links.

• [modules] i18n-tools nunjucksExtensions method now pulls locales information from context SITE.locales and no longer requires locales, baseLocale and currentLocale parameters to be invoked.

  Yeap, it makes a bit obscure what exactly i18n-tools data require to work, but on other side provides much better flexibility, since now it will respond to context locales values changes.

• [modules] nunjucks-extensions module now too pulls locales information from context SITE.locales and no longer requires currentLocale, numberFormat, currencyFormat parameters to be invoked.

• [modules][templates] nunjucks-render and related Nunjucks render() filter now will correctly process input in form of String or Number Objects, which aren't primitives, including Nunjucks SafeString, without need to set isCaller parameter to true. Such situations could occur if render() filter was used directly on Nunjucks macro or its caller().

• [modules][templates] Refactored isActive() Nunjucks function to be slightly faster and less obscure.

• [modules][templates] getLocaleDir() and related Nunjucks counterpart localeDir() now returns / for base locale instead of hacky empty string.

  The old behavior was needed to ease concatenation with URLs, but since all that logic now handled by urljoin(), we can safely return / for a base locale to properly denote that it lives at the root.

• [modules][templates] getLocaleDir() and related Nunjucks counterpart localeDir() now returns locale path with always trailing /, unless url specified.

• [modules] getLocaleDir() no longer requires whole locale properties as input and instead has locales as first argument, which should be proper Kotsu locales object.

• [modules][templates] getLocaleDir() and related Nunjucks counterpart localeDir() now more tolerable to locales, which do not exist in locales object.

  It will now try to find URL of locale, otherwise, will return locale name as a path.

• [modules][templates] Certainly obscure header of _base.nj layout related to PAGE data retrieving has been encapsulated into initPage() Nunjucks function, which makes relatively the same thing, but now have documentation, which sheds some light on how things works.

  As of this change, following _base.nj header:

  {{ config('PAGE', { breadcrumb : PAGE.props.breadcrumb }) }}
  {{ config('PAGE', getPage(PAGE.breadcrumb).props|format(PLACEHOLDERS)) }}
  {{ config('PAGE', PAGE.props) }}
  

  has to be changed to

  {{ initPage() }}
  

  It will also make much easier loading of Matter data in your own custom layouts by invoking that function in the beginning of the layout and then observing how happiness and joy fill your life.

• [modules][templates] isActive() Nunjucks function now will throw TypeError in case of relative url.

• [modules][templates] currentLocale is no longer mandatory property for Nunjucks task, it will fallback to baseLocale if no locale specified.

• [modules][templates] Nunjucks urljoin function now uses instead of url-join more reliable URI.js.

  Note, that it is slightly modified:

  • When the first argument is absolute URL, all other segments will resolve against that absolute URL, instead of taking only its path.
  • If all urljoin arguments are slashes or empty strings, it will resolve to / if the first argument is /. See related issue medialize/URI.js/#341 and related tests.

  #176

• [modules] Changed sections comment-headers always be 80 chars long.

• [data] Reordered SITE properties to make it more consistent with the order of package.json.

• [styles] Updated Ekzo to version 2.5.2.

• [styles][grunt] Updated Sass files to use same comments headers as Ekzo 2.4.3 — 80 chars long.

• [styles] Update stylelint-disable to use changed Stylelint 7.12.0 rules.

• [styles][data] Changed data.themeColor to be background of website, and kotsu-theme-color() now uses that value. This will fit better for most websites.

• [styles] Due to changes in data.themeColor, it used now for $ekzo-colors.outer-space color instead of $ekzo-colors.primary, which no longer uses that value and should be declared manually. This is something site-specific and should be adjusted on demand.

• [grunt] Enabled Nunjucks cache. This will significantly reduce the re-rendering time for large projects.

• [grunt] Temporarily disabled watch for images with responsive_images task, since it doesn't work with grunt-newer. Resizing all images on each change will be too painful in large repositories. See #251.

• [grunt] Due to the removal of baseLocaleAsRoot setting from Nunjucks task, to achieve same functionality url: '/' should be used for the locale, which will be served at root:

  'en-US':
    locale: 'en-US'
  -  url: 'en'
  +  url: '/'
    rtl: false
    defaultForLanguage: true
    numberFormat: '0,0.[00]'
    currencyFormat: '$0,0.00'
  

• [grunt] Due to changes in locale path resolving method, it is recommended to use root-relative urls in url property of locale:

  'en-US':
    locale: 'uk-UA'
  -  url: 'uk'
  +  url: '/uk'
    rtl: false
    defaultForLanguage: true
    numberFormat: '0,0.[00]'
    currencyFormat: '$0,0.00'
  

  Otherwise, the locale will resolve relatively to current page URL.

• [static][templates] Replaced old boilerplate favicons with new Kotsu ones.

• [static][templates] Converted browserconfig.xml to be Nunjucks template browserconfig.xml.nj, to allow it use Kotsu data.

• [tests] Overgrown nunjucks-extensions.test.js testing file for Nunjucks extensions finally has been split into smaller files, each with its own mock context. Generic wrapping canvas around tests in those files has been refactored. Hundreds of kittens saved #252

• [grunt] Data changes will now trigger grayMatter task, since now it relies on part of data (PAGE_DEFAULTS).

• [tests] Nunjucks-related testing utility functions has been moved into standalone file /tests/utils/nunjucks.js which exports renderString method. It also now accepts a context as the second argument.

• [tests] Nunjucks testing utility function renderString no longer tries to parse rendered content with JSON.parse, unless third argument parse has been set to true.\

• [tests] .git, build and temp directories are now excluded from tests to make the launching of tests watch faster in large projects.

Removed

• [packages] Removed url-join in favor of URI.js.

• [grunt] PostCSS Autoprefixer's browser queries removed in favor of new browserslist property in package.json., so that queries could be used by other related tools. See article for details.

• [grunt] Removed grunt-cache-bust option algorithm: md5, since it's default value anyway.

• [grunt] Removed @config('baseLocale') calls from data-retriving functions in styles and data tasks, since @config('data')() with no argument will return base locale values anyway.

• [data] Removed not needed Grunt templating from index data file for paths and env variables.

• [data][templates] removed DATA.currentYear. As a computed value, it does not belong to data well and it is better to use moment().year() instead.

• [modules][grunt] Removed baseLocaleAsRoot argument from all i18n-related modules and its related settings in Nunjucks Grunt task.

  Use url: '/' in locale prop to achieve the same functionality.

  #276

• [modules] Nunjucks 1i8n-related extensions no longer require deprecated baseLocaleAsRoot value to invoke.

• [modules][templates] Removed isCaller from nunjuck-render method, since is is no longer needed to make adjustments to input based on whether it is macro's caller or no. This also means that Nunjucks render() filter no longer accepts this parameter too.

• [misc] Removed Stylelint rule at-rule-no-unknown in favor of scss/at-rule-no-unknown.

• [styles] Removed not needed $prefix: $ekzo-sprites-prefix from ekzo-sprites() include.

• [styles] Removed no longer needed ekzo-buttons-sizes() include inside Btn component, since from Ekzo 2.5.0 it is included by ekzo-for-each-breakpoint with $include-self option set to true.

Fixed

• [grunt] Fixed uncss not finding scripts because of running after scripts-related tasks.
• [data] Now env properties will not ocassionaly return empty string instead of boolean or undefined.
• [templates] Fixed Breadcrumb() being unordered list instead of ordered one <ol>. It's better suits its semantics, since it represents strickly ordered structure.
• [templates] Thanks to related to #219 changes, blog posts finally using proper Open Graph type of article. Solves #59.
• [templates] Fixed rootTitle in Breadcrumb component formatted with sprintf twice.
• [modules][templates] Fixed isActive() Nunjucks function and related Link() component wrongly returning false for isActive('/'), while it always should be true, unless set to exact mode.
• [modules][templates] Fixed warn() Nunjucks function taking url from wrong property.
• [modules][templates] Fixed getLocaleDir() and its Nunjucks countrepart localeDir() urlifying for no reason locale url. It should be urlified only if no url specified and locale used instead.
• [styles] Merged separate ekzo-theme() mixin call in generic/code file.