As we discussed, we'll need to add format filtering to examples to make this work without functionality-breaking transforms from #2389.

Proposal is to allow examples to include @format(format1,format2) anywhere in the block comment. This comment signifies that the section that follows is only relevant for those formats and will be stripped prior to running formatTransform.

Sorry if I am missing context, just wanted to add this: wouldn't filtering the comments/documentation work with the already implemented syntax like [filter formats="email"]This only shows for email[/format]?

Good idea. That could work. The closing tag might be a problem in some cases as you need to add a dummy empty comment before subsequent html elements without comment:

<!--
[filter formats="email"] 

This is amp-form ...
-->
<form class="sample-form"
  method="GET"
  action="/documentation/examples/api/submit-form"
  target="_top">
  ...
</form>
<!-- [/format] -->
<!-- -->
<div class="this-should-not-be-displayed-as-a-snippet"></div>

Sorry, I fear that adding logic like that (specifically, implementation that includes both start and end tag) would take significant time for me (with my knowledge of the samples parser, based on experience doing ampproject/amp-by-example#1338) and I have limited bandwidth for this.

It's significantly easier to implement IFF:

• It's section level, i.e. no ending tag.
• It can be caught with a (simple) regex.

@fstanis please give Matthias's suggestion a try. It might already work as sample pages are also generated via grow (which understands the filter syntax).

Sorry @mathiasbynens, misunderstood your comment!

Anyway, this works, but only if both start and end are in the same comment. Your code sample results in this error which I'm not sure how to debug:

Unexpected end of template. Jinja was looking for the following tags: 'endcall'. The innermost block that needs to be closed is 'call'.

(there are a few other issue, such as the fact that the current system assumes an example always has one format, but that could probably be fixed)

More importantly, this wouldn't work for the preview.amp.dev endpoint, which is my first priority with this feature. For that to work, we need the different formats to all be generated at build time rather than runtime. For this reason, I prefer the aforementioned @format block-level syntax.

Good point. This won't work for the previews.

Sorry @mathiasbynens, misunderstood your comment!

You meant @matthiasrohmer, not me. (GitHub’s autocomplete widget could use some love…)

@fstanis what's the status here?

This should now be done. PTAL.

I added @formats logic, removed metadata (now it will attempt to transform every component sample) and validation after transform.

Addressed comments, updated tests for formatTransform (do we have tests for gulp too?) and fixed linter issues.

I changed the way validation results are returned and added some tests for it.

Tried the PR locally. Two things:

• can you remove the (email) postfix. It's confusing as you're already in "email" mode
• we should fix the URLs as part of this PR

@matthiasrohmer have you got a good idea, how we load sample.$FORMAT.html instead of sample.html if /sample/?format=$FORMAT is requested? If I remember correctly you implemented something similar for the normal doc pages?

can you remove the (email) postfix. It's confusing as you're already in "email" mode

Done.

we should fix the URLs as part of this PR

I added logic for the following:

1. If the URL has a format parameter and the format is not websites (e.g. ?format=email), then try to load template with .${format} first.
2. If that fails, continue with normal flow.
3. If the URL ends with .<something>, redirect to ?format=<something> (amp-img.email/ -> amp-img/?format=email).

As we discussed, I temporarily made it so generated samples are hidden from the main website and only visible in the playground and preview until we resolve the issues with URLs.