Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify the documentation for allowed attributes #994

Closed
uncompiled opened this issue Nov 23, 2015 · 7 comments
Closed

Clarify the documentation for allowed attributes #994

uncompiled opened this issue Nov 23, 2015 · 7 comments
Assignees
@Gregable
Labels
Related to: Documentation WG: caching
Milestone
Backlog Bugs

Comments

@uncompiled
Copy link

It would be helpful to clarify the allowed attributes for whitelisted elements. This would help publishers avoid validation errors when transforming content from their content management systems.

There is already a HTML5 element whitelist in the AMP Tag Addendum, but there isn't a clear reference for the attributes that are allowed vs. prohibited by the AMP spec.

There is some documentation in the form of the validator, but the validator might not be the most accessible format for all users.
@Gregable
Copy link
Member

I think what I'd like to do is generate some code which will take the validator's spec file and produce some markdown from it that is more human readable.

For example, the section regarding the <meta> tag in the validator reads:

# 4.2.5 the meta element
# Charset must be utf8, and a specific viewport is required.
# Other meta elements not supported.
tags: {
  name: "meta"
  mandatory: true
  mandatory_parent: "head"
  unique: true
  detail: "charset utf-8 declaration"
  spec_url: "https://github.com/ampproject/amphtml/blob/master/spec/amp-html-format.md#chrs"
  attrs: {
    name: "charset"
    mandatory: true
    value: "utf-8"
  }
}
tags: {
  name: "meta"
  detail: "viewport declaration"
  mandatory: true
  mandatory_parent: "head"
  unique: true
  spec_url: "https://github.com/ampproject/amphtml/blob/master/spec/amp-html-format.md#vprt"
  attrs: {
    name: "name"
    mandatory: true
    value: "viewport"
  }
  attrs: {
    name: "content"
    mandatory: true
    value_properties: {
      properties: { name: "width" mandatory: true value: "device-width" }
      properties: { name: "height" }
      properties: { name: "initial-scale" }
      properties: { name: "minimum-scale" mandatory: true value_double: 1.0 }
      properties: { name: "maximum-scale" }
      properties: { name: "user-scalable" }
    }
  }
}
tags: {
  name: "meta"
  attrs: {
    name: "property"
    mandatory: true
  }
  attrs: {
    name: "content"
    mandatory: true
  }
}
# The validator accepts any name="..." content="..." attribute pair except
# for a few specific name values which have more specific rules above or
# are altogether disallowed.
tags: {
  name: "meta"
  attrs: {
    name: "name"
    mandatory: true
    blacklisted_value_regex: "viewport|content-disposition|revisit-after"
  }
  attrs: {
    name: "content"
    mandatory: true
  }
}

And could be converted to markdown to look something like:

4.2.5 <meta>

There are 2 mandatory meta tags

  1. charset utf-8 declaration
    • mandatory attribute charset, value utf-8
    • There may be only one of these tags.
    • This tag's parent must be a <head> tag.
    • Spec Reference
  2. viewport declaration
    • mandatory attribute name, value viewport
    • mandatory attribute content, value is a list of properties:
    • mandatory name width, value device-width
    • mandatory name maximum-scale, value 1.0
    • optional name height, any value
    • optional name initial-scale, any value
    • optional name maximum-scale, any value
    • optional name user-scalable, any value
    • There may be only one of these tags.
    • This tag's parent must be a <head> tag.
    • Spec Reference

There are 2 optional meta tags variants:

  1. -unnamed-
    • mandatory attribute property, any value
    • mandatory attribute content, any value
  2. -unnamed-
    • mandatory attribute name, value must match the regex viewport|content-disposition|revisit-after
    • mandatory attribute content, any value

This is currently just an example done by hand. The Tag addendum was an attempt to do the same (also by hand) before folks had access to the validator spec file. I think we should write some code to generate this automatically from the spec file, however.

@Gregable Gregable mentioned this issue Nov 23, 2015
Closed
@rudygalfi rudygalfi added this to the M2 milestone Jan 30, 2016
@hugronaphor hugronaphor mentioned this issue Feb 1, 2016
Closed
@Meggin
Copy link
Contributor

Meggin commented Feb 25, 2016

FYI, I've added quite a bit of validation documentation. The main new doc is here: https://www.ampproject.org/docs/reference/validation_errors.html. As well, each spec has a validation errors table. Check out a couple of examples to see what they look like: https://www.ampproject.org/docs/reference/amp-img.html, https://www.ampproject.org/docs/reference/extended/amp-iframe.html.

@erwinmombay
Copy link
Member

@Gregable i can take on that work, im currently in the process of writing down some scripts for the docs site to pull the data from the protoascii.

@Gregable
Copy link
Member

@erwinmombay , sync up with @honeybadgerdontcare as I think he had started on this as well.

@honeybadgerdontcare
Copy link
Contributor

Yeah, let's chat. I am in the process of markdown generation from the protoascii.

@rudygalfi rudygalfi modified the milestones: M2, Backlog Mar 4, 2016
@adelinamart
Copy link
Contributor

Is this still relevant?

@uncompiled
Copy link
Author

I think this ticket can be closed. IMO, since this ticket was opened, the release of the AMP validator as a Chrome plugin and nodejs module provide enough information.

@dependabot-preview dependabot-preview bot mentioned this issue May 3, 2018
Open
@ChrisAntaki ChrisAntaki mentioned this issue Mar 2, 2020
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Gregable Gregable

Labels
Related to: Documentation WG: caching
Projects
None yet
Milestone
Backlog Bugs
Development

No branches or pull requests
7 participants
@Gregable @erwinmombay @uncompiled @honeybadgerdontcare @Meggin @rudygalfi @adelinamart