Demos should be rendered inline

[nightire]

Multiple presentations on the same page will be rendered together at the top of the page currently, this is not ideal for documentation.

For instance, I write a page based on the official guide example like this:

What I expect is that the demo and description can be rendered interlaced, but here's what I got finally:

---

@NullVoxPopuli and I had some discussion regades this issue on Discord here: https://discord.com/channels/480462759797063690/480462759797063692/803975172284481596

[josemarluedke]

Yeah, so in Ember, the demos are inserted automatically before the second heading found on the owner page.

I could see the benefit of choosing where each demo goes, but we would lose the ability to just add a demo and have it show up on the page. Alternatively, we should set up a marker to indicate where all the demos would be inserted in the page, if none were found, then insert them on the default location.

Also, worth mentioning that the "Demos" feature is meant to be used for demoing a component. If you want to have inline code samples or just HBS samples, that is supported.

[bertdeblock]

I like the idea of having a marker to indicate where demos should be inserted. However, in my case, it would also be nice to have a global option to indicate that demos should always be inserted at the bottom of the page. Does that sound like a useful addition @josemarluedke? I could have a look at doing the implementation.

[josemarluedke]

@bertdeblock That does sounds like a good option.

[DingoEatingFuzz]

Having used Docfy for a bit now, I find myself going out of my way to keep examples limited to HBS so I have control over where in a document the example gets rendered.

I can kind of see the value in automatic demo insertion, but only barely. Personally, if someone is willing to take the time to create an hbs and a js file for their example, then it isn't a big ask to expect them to add some sort of marker in their markdown file to denote an insertion point.

The other pattern I've seen is people refrain from writing docs in the main markdown file, instead putting prose in demo descriptions and relying on demo order to compose pages. This also seems like something we should discourage.

I would like to see two things:

1. Some sort of marker that makes it ergonomic to manually add demo components to a doc page, e.g.,

[[demo:one]]

2. A frontmatter option for disabling automatic demo insertion for a page

I imagine the marker would still be implemented as an AST transform, but now it would match markers with demos instead of iterating over the whole lot and stuffing them in an arbitrary place in the document.

Maybe a third request to satisfy what @bertdeblock wants would be a marker for where all demos should be inserted. Something like

[[demos-all]]