setup.md

kolay

adjective

• easy
• simple
• uncomplicated

after initial setup

---

Install¹

pnpm add kolay @universal-ember/kolay-ui

Setup

There are two areas of configuration needed: buildtime, and runtime².

Build: Embroider + Webpack

import kolay/webpack

const { kolay } = await import("kolay/webpack");

return require("@embroider/compat").compatBuild(app, Webpack, {
  /* ... */
  packagerOptions: {
    webpackConfig: {
      devtool: "source-map",
      plugins: [
        kolay({
          src: "public/docs",
          // Generate API docs from JSDoc
          packages: ["kolay"],
        }),
      ],
    },
  },
});

You can create docs for multiple libraries at once:

devtool: 'source-map',
plugins: [
  kolay({
    src: 'public/docs',
    groups: [
      {
        name: 'Runtime',
        src: '../ui/docs',
      },
    ],
    // Generate API docs from JSDoc
    // NOTE: these must all be declared in your projects package.json
    packages: ['kolay', 'ember-primitives', 'ember-resources'],
  }),
],

This is useful for monorepos where they may be scaling to large teams and many packages could end up being added quickly. In a traditionally compiled app, this may cause build times to slow down over time. Since many docs' sites are deployed continuously, that is wasted time and money spent on building things that may not be looked at all that often (we all wish folks looked at docs more!).

By distributing the rendering of pages to the browesr, we only pay for "build" when somenoe views the page.

Runtime: Routing

If using @ember/routing/router or @embroider/router

You'll want to also install ember-primitives, so that you can use the [@properLinks] decorator on the router, giveng you the ability to just use anchor tags (<a>) (a requirement for in-browser linking in markdown).

import { kolayRoutes } from "kolay";
import { properLinks } from "ember-primitives/proper-links";

@properLinks
export default class Router extends EmberRouter {
  location = config.locationType;
  rootURL = config.rootURL;
}

Router.map(function () {
  kolayRoutes(this);
});

In the spirit of dynamically compiled and discovered docs, this adds a *wildcard route that matches all paths and then tries to derive which file to load from there.

Footnotes

1. @universal-ember/kolay-ui is only needed because due to a temporary technical problem. Once the ember ecosystem has broader package.json#type=module support for its own ember using libraries, @universal-ember/kolay-ui can be removed and there will only be kolay. Note that package.json#type=module support is already working and has worked for a good number of years for non-Ember libraries. ↩

2. The runtime components are optional and if you don't import them, they will not be included in your app. However, since links generated from markdown use vanilla <a> tags, you'll probably want at least @properLinks from ember-primitives. ↩