You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Write versioned API references](#write-versioned-api-references)
@@ -25,22 +25,30 @@ Every addon comes with a fully bootstrapped Ember application that can be found
25
25
26
26
Once you document the new behavior on your doc site, you can now write an acceptance test against it, ensuring (1) that your code is functioning correctly, and (2) that your docs are accurate and up-to-date. Win-win!
27
27
28
-
## Author in Markdown when possible
28
+
## Author in Markdown
29
29
30
-
In general it is good to author your docs pages as Markdown documents. This helps you focus on content and makes it easy for contributors to make edits and improvements to your docs. For functionality-rich docs pages you can always fall back to `template.hbs` files.
30
+
Authoring your docs pages in Markdown makes it easy for you and your contributors to read and edit your site.
31
31
32
-
We automatically set up a template preprocessor so that you can opt-in to authoring any page you'd like as a Markdown file — just create a `template.md` file wherever you'd normally create a `template.hbs` file. [The file you're reading](#) is an example.
32
+
To make a route a Markdown document, simply create a `template.md` file instead of a `template.hbs`.
33
33
34
-
Whenever you author a template as a Markdown file, we wrap it in a div with the class `.docs-md`. You can view our [predefined styles here](#) — feel free to overwrite these in your own app if you'd like.
34
+
To show additional functionality, create route-specific components and render them from your `template.md` files:
35
+
36
+
```md
37
+
## My Component demo
38
+
39
+
Here's a demo of it working:
40
+
41
+
{{docs/my-component/demo1}}
42
+
```
35
43
36
44
In addition to authoring normal Markdown content, you can
37
45
46
+
- Use an `<aside>` element. This is good for calling out important info or long-standing bug fixes that were part of a release.
47
+
38
48
<aside>
39
49
Here's an example of an aside.
40
50
</aside>
41
51
42
-
- Use an `<aside>` element. This is good for calling out important info or long-standing bug fixes that were part of a release.
43
-
44
52
- Use Handlebars helpers. For example, you can use `link-to` to render a link to {{link-to 'the home page' 'index'}}, or you can even render a component.
<aside>Looking for the quickstart? {{link-to'Click here''docs.quickstart'}}.</aside>
16
17
<p>Documenting software libraries has gotten easier. We have nicely-formatted README.md files, the ability to host custom sites for free on GitHub Pages, and even dedicated tools like <ahref="#">GitBook</a> and <ahref="#">ReadTheDocs</a>. But even though these tools have come a long way, modern developers have high expectations, and library authors can quickly find themselves juggling more tasks than they can manage.</p>
17
18
<p>Ember addons occupy a unique space here. Besides everything that's expected of any modern JavaScript library, there's even more that goes into authoring a library that plays nicely with an ecosystem as mature as Ember's. And too often addon authors with limited time must choose between being a better community citizen, or focusing on the core problem their library was created to solve in the first place.</p>
0 commit comments