Merge pull request #116 from bravo-kernel/quickstart-guide

Full rewrite of the Quickstart Guide

Author: pzuraq

tests/dummy/app/pods/docs/quickstart/template.md

@@ -1,34 +1,38 @@
 # Quickstart
 
-This quickstart guide will get you going with a docs site for your brand new addon.
+This quickstart guide will get you started with a docs site for your brand new
+addon. After completion you will have a docs homepage, a docs subpage named
+`usage`, an automatically generated API reference and a nice looking
+marketing/demo page you can use to promote your addon.
 
-1. **Install the addon.**
+1. **Install Addon Docs.**
 
   ```
   ember install ember-cli-addon-docs
   ```
 
-2. **Add the required routes.** Open `tests/dummy/app/router.js` and add the following route definitions:
+2. **Add the docs routes.** Open `tests/dummy/app/router.js` and add the
+following route definitions to your main route.
 
   {{#docs-snippet name='quickstart-router.js' title='tests/dummy/app/router.js'}}
-    this.route('docs', function() {
-      this.route('api', function() {
-        this.route('item', { path: '/*path' });
+    this.route('docs', function() { // docs homepage (required)
+      this.route('usage'); // docs subpage
+      this.route('api', function() { // autogenerated API homepage (required)
+        this.route('item', { path: '/*path' }); // autogenerated API subpages (required)
       });
     });
   {{/docs-snippet}}
 
-3. **Create your app skeleton.** You can add the global keyboard shortcuts component to enable keyboard navigation around your docs site (use `?` to show the help window). Here's our application template:
+3. **Create your docs skeleton.** Create a new template for the `docs` route
+and make sure it contains the `DocsViewer` component and navigation items for
+all docs pages in your site.
 
-  {{docs-snippet name="docs-demo-application-template.hbs" title="tests/dummy/app/templates/application.hbs"}}
-
-4. **Create your docs skeleton.** Create a template for the `docs` route and add the DocsViewer component.
-
-  {{#docs-snippet name='quickstart-skeleton.hbs' title='tests/dummy/app/pods/docs/template.hbs'}}
+  {{#docs-snippet name='quickstart-skeleton.hbs' title='tests/dummy/app/templates/docs.hbs'}}
     {{#docs-viewer as |viewer|}}
 
       {{#viewer.nav as |nav|}}
-        {{nav.item 'Overview' 'docs.index'}}
+        {{nav.item 'Introduction' 'docs.index'}}
+        {{nav.item 'Usage' 'docs.usage'}}
       {{/viewer.nav}}
 
       {{#viewer.main}}
@@ -42,15 +46,48 @@ This quickstart guide will get you going with a docs site for your brand new add
     {{/docs-viewer}}
   {{/docs-snippet}}
 
-5. **Fill out the index of your docs page.** We called it Overview but you can call it whatever you want. Since Addon Docs supports markdown templates out of the box, we can make this a Markdown file.
+4. **Create your Markdown templates.** Markdown templates contain the actual
+documentation for your addon and live in the folder
+`tests/dummy/app/templates/docs`. Since Addon Docs supports Markdown out
+of the box we will create two `.md` files (one for your docs `index` and one
+for the `usage` page).
 
-  {{#docs-snippet name='quickstart-markdown.md' title='tests/dummy/app/templates/docs/index.md' language='markdown'}}
-    # Overview
+  {{#docs-snippet name='quickstart-markdown-index.md' title='tests/dummy/app/templates/docs/index.md' language='markdown'}}
+    # Index
 
     This is my new addon, and it rocks!
   {{/docs-snippet}}
 
-6. **Add a 404 route.** Add a route to the end of your router and create an associated template.
+  {{#docs-snippet name='quickstart-markdown-subpage.md' title='tests/dummy/app/templates/docs/usage.md' language='markdown'}}
+    # Usage
+
+    So easy to use, sweet!
+  {{/docs-snippet}}
+
+5. **Create your marketing homepage**. Addon Docs comes with a set of
+components that take out all the hard work normally required for creating
+good looking marketing/demo pages. Creating a template with the following
+components will instantly give your main page a navbar, a nice hero
+and a snippet-ready demo container.
+
+  {{#docs-snippet name='quickstart-marketing-index.hbs' title='tests/dummy/app/templates/index.hbs'}}
+    {{docs-navbar}}
+
+    {{docs-hero
+      logo='ember'
+      slimHeading='My'
+      strongHeading='Addon'
+      byline='My addon demo/marketing page.'}}
+
+    {{#docs-demo as |demo|}}
+      {{#demo.example name='my-demo.hbs'}}
+        <p>Make sure to read up on the DocsDemo component before building out this page.</p>
+      {{/demo.example}}
+    {{/docs-demo}}
+  {{/docs-snippet}}
+
+6. **Add a 404 route.** Add the following route to the end of your router and
+create the associated template.
 
   {{#docs-snippet name='quickstart-404.js' title='tests/dummy/app/router.js'}}
     this.route('not-found', { path: '/*path' });
@@ -63,28 +100,30 @@ This quickstart guide will get you going with a docs site for your brand new add
     </div>
   {{/docs-snippet}}
 
-8. **Add more docs pages.** It's up to you how to structure your docs - use the Snippet, Viewer and Demo components to help you write your documentation. Let's add another page to ours: we'll add the route, link to our docs viewer, and the actual template.
+7. **Launch your docs site**. Run `ember serve` and browse to
+`localhost:4200/docs` to enjoy your brand new documentation website.
 
-  {{#docs-snippet name='quickstart-more-docs.js' title='tests/dummy/app/router.js'}}
-    this.route('docs', function() {
-      this.route('installation');
-    });
-  {{/docs-snippet}}
+8. **Create more pages.** To add more doc pages simply follow the same steps as
+used for the `Usage page in above examples`:
 
-  {{#docs-snippet name='quickstart-more-nav.hbs' title='tests/dummy/app/templates/docs.hbs'}}
-    {{#viewer.nav as |nav|}}
-      {{nav.item 'Installation' 'docs.installation'}}
-    {{/viewer.nav}}
-  {{/docs-snippet}}
+  - create a docs subroute
+  - add a corresponding navigation item to the `docs` template
+  - create a corresponding Markdown template
 
-  {{#docs-snippet name='quickstart-installation-readme.md' title='tests/dummy/app/templates/docs/installation.md'}}
-    # Installation
+## Optional
 
-    To install My Addon, run...
-  {{/docs-snippet}}
+1. **Keyboard navigation.** You may want to enable keyboard navigation for your
+docs site by adding the `DocsKeyboardShortcuts` component to your dummy
+application template. Once enabled you can use `?` to show the navigation help
+windows.
+
+  {{docs-snippet name="docs-demo-application-template.hbs" title="tests/dummy/app/templates/application.hbs"}}
 
-8. **Round out your site.**
+2. **Add a favicon.** You may want to place a favicon in the
+`tests/dummy/public` folder. We recommend using using
+ [Ember CLI Favicon](https://github.com/davewasmer/ember-cli-favicon).
 
-* **Add a favicon to your dummy app.** We recommend using [Ember CLI Favicon](https://github.com/davewasmer/ember-cli-favicon).
+3. **Better scrolling.** You may want to install
+[Ember Router Scroll](https://github.com/dollarshaveclub/ember-router-scroll)
+to enable "scroll to top with preserved browser history scroll position".
 
-* **Install [Ember Router Scroll](https://github.com/dollarshaveclub/ember-router-scroll).**