Merge pull request #177 from zonkyio/restructure-documentation

Restructure documentation

README.md

@@ -6,7 +6,7 @@
 [![dependencies Status](https://david-dm.org/zonkyio/ember-web-app/status.svg)](https://david-dm.org/zonkyio/ember-web-app)
 [![devDependencies Status](https://david-dm.org/zonkyio/ember-web-app/dev-status.svg)](https://david-dm.org/zonkyio/ember-web-app?type=dev)
 
-This Ember addon helps you configure and manage the web app manifest and related meta tags needed to create a Progressive Web Application
+This Ember addon helps you configure and manage the Web App Manifest to create a Progressive Web App.
 
 ## Compatibility
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ember-web-app",
   "version": "3.0.0-beta.3",
-  "description": "This Ember addon helps you configure and manage the web app manifest and related meta tags needed to create a Progressive Web Application",
+  "description": "This Ember addon helps you configure and manage the Web App Manifest to create a Progressive Web App",
   "keywords": [
     "PWA",
     "android",

tests/dummy/app/router.js

@@ -7,7 +7,24 @@ const Router = AddonDocsRouter.extend({
 });
 
 Router.map(function() {
-  docsRoute(this, function() {});
+  docsRoute(this, function() {
+    this.route('getting-started', function() {
+      this.route('what-is-web-app');
+      this.route('installation');
+      this.route('upgrade-guide');
+      this.route('overview');
+    });
+
+    this.route('manifest', function() {
+      this.route('available-properties');
+    });
+
+    this.route('advanced', function() {
+      this.route('fingerprinting');
+      this.route('using-cors');
+      this.route('generating-icons');
+    });
+  });
 
   this.route('not-found', { path: '/*path' });
 });

tests/dummy/app/routes/docs/index.js

@@ -0,0 +1,7 @@
+import Route from '@ember/routing/route';
+
+export default Route.extend({
+  beforeModel() {
+    this.transitionTo('docs.getting-started.what-is-web-app');
+  },
+});

tests/dummy/app/templates/application.hbs

@@ -1 +1,2 @@
+{{docs-header}}
 {{outlet}}

tests/dummy/app/templates/docs.hbs

@@ -1,11 +1,21 @@
-{{docs-header}}
-
 {{#docs-viewer as |viewer|}}
+  {{#viewer.nav as |nav|}}
+    {{nav.section "Getting Started"}}
+    {{nav.item "What is Web App?" "docs.getting-started.what-is-web-app"}}
+    {{nav.item "Installation" "docs.getting-started.installation"}}
+    {{nav.item "Upgrade Guide" "docs.getting-started.upgrade-guide"}}
+    {{nav.item "Overview" "docs.getting-started.overview"}}
+
+    {{nav.section "Manifest"}}
+    {{nav.item "Available Properties" "docs.manifest.available-properties"}}
+
+    {{nav.section "Advanced"}}
+    {{nav.item "Fingerprinting" "docs.advanced.fingerprinting"}}
+    {{nav.item "Using CORS" "docs.advanced.using-cors"}}
+    {{nav.item "Generating Icons" "docs.advanced.generating-icons"}}
+  {{/viewer.nav}}
+
   {{#viewer.main}}
-    <div class="docs-container">
-      <div class="docs-section">
-        {{outlet}}
-      </div>
-    </div>
+    {{outlet}}
   {{/viewer.main}}
 {{/docs-viewer}}

tests/dummy/app/templates/docs/advanced/fingerprinting.md

@@ -0,0 +1,26 @@
+# Fingerprinting
+
+You can add fingerprint checksum to your `manifest.webmanifest` file by configuring [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev) in `ember-cli-build.js`.
+
+The following example prepends with a custom domain and adds fingerprint checksum to the `manifest.webmanifest` file.
+
+```javascript
+'use strict';
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+const broccoliAssetRevDefaults = require('broccoli-asset-rev/lib/default-options');
+
+module.exports = function(defaults) {
+  let options = {
+    fingerprint: {
+      extensions: broccoliAssetRevDefaults.extensions.concat(['webmanifest']),
+      prepend: 'https://www.example.com/',
+    },
+  };
+
+  let app = new EmberApp(defaults, options);
+
+  return app.toTree();
+};
+```
+
+_Note that the `replaceExtensions` configuration from `broccoli-asset-rev` is updated internally by `ember-web-app` so you don't have to configure yourself on your project._

tests/dummy/app/templates/docs/advanced/generating-icons.md

@@ -0,0 +1,49 @@
+# Generating Icons
+
+`ember-web-app` doesn't generate icons. If you want to automate the generation of icons starting from a master image, you can install [ember-cli-image-transformer](https://github.com/jrjohnson/ember-cli-image-transformer).
+
+If your `config/manifest.js` looks like this and needs a `192px` and a `512px` icon:
+
+```javascript
+'use strict';
+export default function() {
+  return {
+    icons: [
+      {
+        src: '/assets/icons/appicon-32.png',
+        sizes: '32x32',
+        targets: ['favicon'],
+      },
+      ...[192, 280, 512].map(size => ({
+        src: `/assets/icons/appicon-${size}.png`,
+        sizes: `${size}x${size}`,
+      })),
+    ],
+  };
+}
+```
+
+You can start with a base `brand-icon.svg` image and automatically build the `192x192` and `512x512` versions by installing `ember-cli-image-transformer` and adding the necessary configuration to your `ember-cli-build.js` file:
+
+```javascript
+'use strict';
+module.exports = function(defaults) {
+  let options = {
+    'ember-cli-image-transformer': {
+      images: [
+        {
+          inputFilename: 'lib/images/brand-icon.svg',
+          outputFileName: 'appicon-',
+          convertTo: 'png',
+          destination: 'assets/icons/',
+          sizes: [32, 192, 280, 512],
+        },
+      ],
+    },
+  };
+
+  let app = new EmberApp(defaults, options);
+
+  return app.toTree();
+};
+```

tests/dummy/app/templates/docs/advanced/using-cors.md

@@ -0,0 +1,13 @@
+# Using CORS
+
+You can specify `crossorigin` behaviour for `manifest.webmanifest` by updating the `app/index.html` file.
+
+```html
+<link
+  rel="manifest"
+  href="{{rootURL}}/manifest.webmanifest"
+  crossorigin="use-credentials"
+/>
+```
+
+_See [Mozilla's Documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) for more details._

tests/dummy/app/templates/docs/getting-started/installation.md

@@ -0,0 +1,18 @@
+# Installation
+
+To install Web App, run
+
+```sh
+ember install ember-web-app
+```
+
+Ember should install the addon, add a `config/manifest.js` file, and insert HTML tags for `manifest.webmanifest` and `browserconfig.xml` into `app/index.html` file.
+
+```html
+<head>
+  <link rel="manifest" src="{{rootURL}}manifest.webmanifest" />
+  <meta name="msapplication-config" content="{{rootURL}}browserconfig.xml" />
+</head>
+```
+
+Check out the {{docs-link "upgrade guide" "docs.getting-started.upgrade-guide"}} if you're coming from a previous version of Web App.

tests/dummy/app/templates/docs/getting-started/overview.md

@@ -0,0 +1,49 @@
+# Overview
+
+This Ember addon generates a _Web Application Manifest_ and _Browser configuration schema_ files at build time using the `config/manifest.js` file, it also inserts additional `meta` tags for non-standard vendor implementations.
+
+## Web App Manifest
+
+From [MDN](https://developer.mozilla.org/en-US/docs/Web/Manifest)
+
+> The web app manifest provides information about an application (such as name,
+> author, icon, and description) in a text file. The purpose of the manifest is
+> to install web applications to the homescreen of a device, providing users
+> with quicker access and a richer experience.
+
+The generated `manifest.webmanifest` file is linked to the application using `link` tag in `app/index.html` file.
+
+```html
+<link rel="manifest" src="{{rootURL}}manifest.webmanifest" />
+```
+
+_The generated manifest is validated using `web-app-manifest-validator` package._
+
+## Browserconfig
+
+From [Microsoft](https://msdn.microsoft.com/en-us/library/dn320426%28v=vs.85%29.aspx)
+
+> Browser configuration files (also known as browserconfig) can be used to define pinned site customizations, such as tile backgrounds, badge updates, and tile notifications.
+
+The generated `browserconfig.xml` file is linked to the application using `meta` tag in `app/index.html` file.
+
+```html
+<meta name="msapplication-config" content="{{rootURL}}browserconfig.xml" />
+```
+
+_You can skip generating of `browserconfig.xml` file by removing the `meta` tag from the `app/index.html` file._
+
+## Additional `meta` Tags
+
+It also generates some compatibility `meta` tags for supporting non-standard vendor features like Apple's [Web Content For Safari](https://developer.apple.com/library/content/documentation/AppleApplications/Reference/SafariWebContent/Introduction/Introduction.html) and that don't yet support the _Web App Manifest_ standard.
+
+## Targets
+
+Internally, Web App takes into account four different types of targets for generating the _Web App Manifest_ taking care of including some backward compatibility `meta` tags in order to support as many devices and browsers as possible. These targets are:
+
+- `manifest` (default target)
+- `android` (to target Android devices)
+- `apple` (to target Apple devices)
+- `ms` (to target Win8/Win10 devices)
+
+_Not all targets are used for all properties (actually, most properties are not affected by the targets)._

tests/dummy/app/templates/docs/getting-started/upgrade-guide.md

@@ -0,0 +1,35 @@
+# Upgrade Guide
+
+If you're upgrading from an existing version of Web App, you can run the following:
+
+```sh
+# Using npm
+npm install -D ember-web-app@X.X.X
+
+# Using yarn
+yarn add -D ember-web-app@X.X.X
+```
+
+## Full Changelog
+
+You can view all of Web App's release notes on [our Releases page](https://github.com/zonkyio/ember-web-app/releases).
+
+## 3.0 Upgrade Guide
+
+There were a two breaking changes made in the 3.0 release.
+
+### 1. Use explicit _Web App Manifest_ and _browserconfig_ references
+
+Previously, Web App was automatically inserting tags for _Web App Manifest_ and _browserconfig_ at build time. This feature was buggy and poorly extensible by developers, so it was removed and the explicit references in `app/index.html` are required.
+
+You can run Web App's blueprint to insert tags into `app/index.html`.
+
+```sh
+ember generate ember-web-app
+```
+
+If the generation of _browserconfig_ is disabled by falsy `ms` property value in your `config/manifest.js` file, you can remove the `meta` tag from the `app/index.html` file and the `ms` property from the `config/manifest.js` file.
+
+### 2. Drop Node.js 6 support
+
+Web App supports Node.js 8+ versions.

tests/dummy/app/templates/docs/getting-started/what-is-web-app.md

@@ -0,0 +1,9 @@
+# What is Web App?
+
+From [MDN](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)
+
+> Progressive web apps use modern web APIs along with traditional progressive enhancement strategy to create cross-platform web applications. These apps work everywhere and provide several features that give them the same user experience advantages as native apps.
+
+This Ember addon helps you configure and manage the _Web App Manifest_ to create a _Progressive Web App_.
+
+It also supports _browserconfig_ and set of _meta_ tags for non-standard vendor implementations.