GitHub

Writing Demos

Docfy has a concept of "demo" markdown files. It allows you to write code in markdown and have them be extracted as executable code in the host app. You can learn more about the file location rules in Writing Markdown - Demos .

In the context of Ember, all demos are extracted as components. These components can have a template, component, and style code block. Components can also be template only components by only specifying the HBS template.

Note that styles will be extracted as a co-located file with the component, it would only work if your host app is using Ember CSS Modules or something similar.

Below you can see how a demo markdown file looks like.

# Demo of Docfy Demos :D

This is a cool feature of Docfy. It is perfect for documenting design systems and
component libraries.

> Note that this text was extracted from the markdown demo file.

```hbs template
This is my Demo: <DocfyLink @to={{this.url}}>My Link</DocfyLink>
```

```js component
import Component from '@glimmer/component';

export default class MyDemo extends Component {
  url = '/docs'
}
```

The demo will be injected into the owner file as a new section called "Examples"; you can see it below.

Please note that you must pass a metadata to the code block, it can be seen after the file type in the example above. The meta is used to identify the purpose of the code block. The possible values are component, template, and styles.

You can write TypeScript for the component JS as well, if your host app is configured to support it.

Examples

This is my Demo: My Link

This is a cool feature of Docfy. It is perfect for documenting design systems and component libraries.

Note that this text was extracted from the markdown demo file.

This is my Demo: <DocfyLink @to={{this.url}}>My Link</DocfyLink>

Preview Template

When writing documentation in Ember apps, we might want to write some template code to demonstrate how to use a component, while having the code been executed as well. Creating a demo markdown might be too much of an effort; for this purpose, Docfy has another feature called preview-template. It will extract the template from the markdown code block then it will create a template only component. It will also add the code snippet so users can see the code.

Below is an example of how it works:

```hbs preview-template
Click in the link to navigate to the home page: <DocfyLink @to="/>Home</DocfyLink>
```

And here you can see how it looks like when rendered:

Click in the link to navigate to the home page: Home
Click in the link to navigate to the home page: <DocfyLink @to="/">Home</DocfyLink>