Quickstart

1. Install AddonDocs

ember install ember-cli-addon-docs

2. Install ember-cli-addon-docs-yuidoc

API docs are autogenerated from comments in your source code, and require an additional plugin to be installed.

For both classic and native classes, install the YUIDoc plugin:

ember install ember-cli-addon-docs-yuidoc

You can see an example of an autodocumented YUIDoc component in the sandbox, and view its source on GitHub.

3. Add the docs routes

Open tests/dummy/app/router.js and replace the standard EmberRouter with the AddonDocsRouter:

import AddonDocsRouter, { docsRoute } from 'ember-cli-addon-docs/router';
import config from './config/environment';

const Router = AddonDocsRouter.extend({
  location: config.locationType,
  rootURL: config.rootURL,
});

Router.map(function() {
  docsRoute(this, function() { /_ Your docs routes go here _/ });
});

export default Router;

4. Start developing your dummy app

AddonDocs uses your addon's dummy application, which is a full-fledged Ember application, as its documentation site.

So let's start with the application template:

<DocsHeader/>

{{outlet}}

<DocsHeader /> is an AddonDocs component that renders a header using data from your addon's package.json. It renders a homepage link, documentation link, version selector, search bar, and link to your GitHub repository. Check out the guide for more on the header.

At this point, fire up ember s and you should see your new docs site & header at localhost:4200!

5. Create your homepage

AddonDocs comes with some components to help you showcase your addon. Let's add them to your dummy app's index template:

<DocsHero/>

<div style="max-width: 40rem; margin: 0 auto; padding: 0 1.5rem">
  <DocsDemo 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>
  </DocsDemo>
</div>

<DocsHero /> renders a homepage banner, and <DocsDemo /> can be used to show an interactive code examples.

AddonDocs is unopinionated about how you style your application, so you can use whatever approach you like. (AddonDocs' own components are styled with a customized version of Tailwind CSS. At this time, these classes, prefixed with docs-*, should be considered private.)

6. Create your docs skeleton

The docs route is the entry point for your guides and API docs. Create a new docs.hbs file for the docs route and add the <DocsViewer /> component:

<DocsViewer as |viewer|>
  <viewer.nav as |nav|>
    <nav.section @label="Introduction"/>
  </viewer.nav>

  <viewer.main>
    {{outlet}}
  </viewer.main>

</DocsViewer>

If you visit /docs or click the Documentation link in the header, you should see the viewer's nav on the left-hand side and an area in the center where your guides content will go.

7. Create your first docs page

Let's create our first guides page with the docs-page generator:

ember generate docs-page index

Guides pages can be either Handlebars .hbs files or Markdown .md templates. AddonDocs includes support for compiling your Markdown files to Handlebars templates at build time.

Since most guides contain written prose, the majority of your guides pages will end up being Markdown files.

The generator should have created

• the markdown file in the tests/dummy/app/templates/docs directory
• the nav item entry in tests/dummy/app/templates/docs.hbs
• the route entry in tests/dummy/app/router.js for non-index routes

You can generate additional pages as you build out your docs site:

ember generate docs-page usage

This will generate and modify the files for your usage docs page.

# Usage

Usage content

Remember, the dummy site is a full Ember application and these components are just here to help you get going. Feel free to make other components to help you best document your library!

8. Add some API docs to a component, object or function

As you document the public objects in your addon, they'll automatically show up in the left-hand navigation of your docs route under the "API REFERENCE" section, assuming you added the <DocsViewer/> component.

Check out the sandbox for an example addon with autogenerated API docs on the side. You can also take a look at the code on GitHub to see how these objects were documented.

9. Add a 404 route

Just as with any Ember app, it's a good idea to add a 404 route for unmatched URLs.

Add the following route to the end of your router and create the associated template.

this.route('not-found', { path: '/\*path' });

<div style="max-width: 40rem; margin: 0 auto; padding: 0 1.5rem">
  <h1>Not found</h1>
  <p>This page doesn't exist. <DocsLink @route="index">Head home?</DocsLink></p>
</div>

You've now got a bootstrapped docs site ready to share with the world! Keep working on it until you're happy, then read on to learn more about AddonDocs' patterns and how to deploy your application for free on GitHub pages.

Optional steps

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.

{{outlet}}

<DocsKeyboardShortcuts />

1. Add a favicon. You may want to place a favicon in the tests/dummy/public folder. We recommend using using Ember CLI Favicon.

2. Optionally customize your brand. The primary brand color is #E04E39. You can change this value by setting the --brand-primary CSS custom property in your dummy app's app.css file.

For example, to set your brand color as #3490DC:

/* tests/dummy/app/styles/app.css */
:root {
  --brand-primary: #3490dc;
}