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

Demo of Docfy Demos :D

Edit this demo

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: My Link
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 whilst also having the code executed to embed the same template into the rendered markdown. 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 and create a component backed by an empty Glimmer component class to provide a this context so helpers such as mut or set can be used within the demonstration. 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>