/gl-style-package-spec

Best practice for storing "GL Styles" in a repo / directory / zip package

Primary LanguageJavaScript

"GL Style Package" specification

Best practice for storing complete "GL style" for a map in a GitHub repo, gist, directory or a zip package.

Map style preview

After following steps you will get free preview of your map on github.io pages like OSM Bright GL style preview.

Requirements

  • GitHub repository
  • Style saved as a style.json in root
  • Icons used in style saved as SVG files inside icons/

Installation

Warning: Following steps will automatically create/rewrite content of you gh-pages branch on every push you make.

  • Enable Travis for your repository
  • Copy .travis.sample.yml into your repository master as .travis.yml
  • Generate personal access token if you don't have any
  • Encrypt it using travis encrypt -r [user]/[repo] GITHUB_TOKEN=[the token here] (install travis using gem install travis)
    • You can use also --add option when running this command to automatically append encrypted variable into your .travis.yml.
  • Insert following to your .travis.yml (if it was not inserted using --add option):
env:
  global:
    - secure: [encrypted token here without quotes]
  • Visit https://[user].github.io/[repo] in your browser.

Ideas

Discussion, specification and validator for correctness and completeness of storing map styles described in MapBox GL Style JSON together with all related assets in a single directory or github repository.

The spec should solve these issues:

  • Storage of complete JSON GL styles in Github / Gist with revisions (versioning) and possible collaboration of multiple people / designers
  • Specification of the structure of such repo, verifiable by a script
  • Guarantee, that the style and all assets are included - and available in an editable form (sprites in SVG format, correctly linked fonts) - not in a derivative form, verifiable by a script
  • Presence of license of the style (code+creative), part of verification
  • It should be possible to deploy offline or deploy to a tileserver (TileServerGL or another)
  • It should be possible to load & save the styles with an editor (Maputnik or another)
  • Fonts may be saved in a separate repo - for easier reuse
  • JSON style or another metadata file may contain information about compatibility requirements for the fonts, vectortiles, etc
  • Ensure the style package (.zip made from GitHub repo) can be downloaded and used offline in a standalone mobile app

This repo should contain a script (to be run on Travis), which will validate the files with a set of tests, report potential issues and convert the original assets into an online preview hosted on gh-pages of the same github repo.

Related materials:

The spec/travis scripts may be applied on the default styles of OSM2VectorTiles, OpenMapTiles, KlokanTech, OSM Liberty, etc.