{"id":15208948,"url":"https://github.com/ampproject/eleventy-plugin-amp","last_synced_at":"2025-08-21T20:33:16.579Z","repository":{"id":38399826,"uuid":"240269555","full_name":"ampproject/eleventy-plugin-amp","owner":"ampproject","description":"Quickly build interactive websites with Eleventy \u0026 AMP.","archived":false,"fork":false,"pushed_at":"2024-06-03T19:34:09.000Z","size":1318,"stargazers_count":48,"open_issues_count":24,"forks_count":20,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-12-14T23:07:36.463Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ampproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-13T13:41:36.000Z","updated_at":"2024-11-18T08:28:42.000Z","dependencies_parsed_at":"2023-02-18T04:00:19.247Z","dependency_job_id":"d54c72f4-88f1-4b6d-be86-f915cf380cd2","html_url":"https://github.com/ampproject/eleventy-plugin-amp","commit_stats":{"total_commits":82,"total_committers":8,"mean_commits":10.25,"dds":"0.23170731707317072","last_synced_commit":"e1b386155b0eaebe4f935fda2cc3fe243e2bbb71"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ampproject%2Feleventy-plugin-amp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ampproject%2Feleventy-plugin-amp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ampproject%2Feleventy-plugin-amp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ampproject%2Feleventy-plugin-amp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ampproject","download_url":"https://codeload.github.com/ampproject/eleventy-plugin-amp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230532448,"owners_count":18240792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-28T07:05:03.520Z","updated_at":"2024-12-20T04:08:09.760Z","avatar_url":"https://github.com/ampproject.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Eleventy AMP Plugin\n\nQuickly build interactive websites with [Eleventy](https://www.11ty.dev) \u0026 [AMP](https://amp.dev).\n\n## Installation\n\nAvailable on [npm](https://www.npmjs.com/package/@ampproject/eleventy-plugin-amp).\n\n```\nnpm install @ampproject/eleventy-plugin-amp --save-dev\n```\n\n## Usage\n\nEdit your Eleventy config file (probably `.eleventy.js`) and use [`addPlugin`](https://www.11ty.dev/docs/plugins/#add-the-plugin-to-eleventy-in-your-config-file) for integrating the AMP plugin:\n\n```js\nconst ampPlugin = require('@ampproject/eleventy-plugin-amp');\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(ampPlugin);\n};\n```\n\nThis will turn all pages generated by Eleventy into AMP pages.\n\n### Using AMP Components in your templates\n\nYou can use AMP components out-of-the-box, For example, for creating an image carousel:\n\n```html\n\u003camp-carousel layout=\"responsive\" width=\"300\" height=\"200\"\u003e\n  \u003camp-img src=\"image1.png\" alt=\"an image\"\u003e\u003c/amp-img\u003e\n  \u003camp-img src=\"image2.png\" alt=\"another image\"\u003e\u003c/amp-img\u003e\n  \u003camp-img src=\"image3.png\" alt=\"and another another image\"\u003e\u003c/amp-img\u003e\n\u003c/amp-carousel\u003e\n```\n\nThere's no need to explicitly import the `amp-carousel` extension script as it will be added automatically by the AMP plugin:\n\n```html\n\u003chead\u003e\n  ...\n  \u003c!-- this will be added automatically --\u003e\n  \u003cscript\n    async\n    custom-element=\"amp-analytics\"\n    src=\"https://cdn.ampproject.org/v0/amp-analytics-0.1.js\"\n  \u003e\u003c/script\u003e\n  ...\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003camp-carousel layout=\"responsive\" width=\"300\" height=\"200\"\u003e\n    \u003camp-img src=\"image1.png\" alt=\"an image\"\u003e\u003c/amp-img\u003e\n    \u003camp-img src=\"image2.png\" alt=\"another image\"\u003e\u003c/amp-img\u003e\n    \u003camp-img src=\"image3.png\" alt=\"and another another image\"\u003e\u003c/amp-img\u003e\n  \u003c/amp-carousel\u003e\n\u003c/body\u003e\n```\n\nCheckout the [AMP documentation for more components](https://amp.dev/documentation/components/) to use.\n\n### Markdown Support\n\nMarkdown images are automatically converted to `amp-img`:\n\n```\n![image](https://unsplash.it/500/400)\n```\n\nThe AMP Plugin needs to be able to determine the image dimensions from the image file. Use the `imageBasePath` option to customize how to resolve local image files:\n\n```js\nconst ampPlugin = require('@ampproject/eleventy-plugin-amp');\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(ampPlugin, {\n    // For customizing the location of images assets, pass either a directory\n    imageBasePath: `${__dirname}/img`,\n    // ... or a function that returns the correct path based on img src and outputPath.\n    imageBasePath: (imageSrc, outputPath) =\u003e `${outputPath}/../img`,\n  });\n};\n```\n\n### Image Optimization\n\nThe plugin offers automated image optimization and `srcset` generation. The plugin uses [AMP Optimizer's built-in srcset generation](https://github.com/ampproject/amp-toolbox/tree/master/packages/optimizer#image-optimization) and [eleventy-img](https://github.com/11ty/eleventy-img) for image resizing.\n\nTo enable, pass the following options:\n\n```js\nconst ampPlugin = require('@ampproject/eleventy-plugin-amp');\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(ampPlugin, {\n    // Enable image optimization using the default output dir (`_site`) and image folder (`img`).\n    imageOptimization: true,\n  })\n```\n\nYou can customize the image generation via:\n\n```js\nconst ampPlugin = require('@ampproject/eleventy-plugin-amp');\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(ampPlugin, {\n    // Enable image optimization\n    imageOptimization: {\n      // The path optimized images should be served from, the default is '/img/'\n      urlPath: '/images/',\n    }\n    // The target dir as configured in `dir.output`, the default is '_site'\n    outputDir: opts.dir.output,\n  })\n```\n\n### Shortcodes\n\nAMP offers a rich set of third-party embeds. Some of these embeds are available via [shortcodes](https://www.11ty.dev/docs/shortcodes/) (in all templating languages). They all follow the same pattern:\n\n```\n{% shortCodeName ['shortCodeParams']* layoutDefinition? %}\n```\n\nShortcodes support all [AMP layouts](https://amp.dev/documentation/guides-and-tutorials/learn/amp-html-layout/?format=websites). Layouts are always defined last and use the same parameter order: `LAYOUT_NAME? WIDTH? HEIGHT?`. Whereas `LAYOUT`, `WIDTH` and `HEIGHT` are optional depending on the layout.\n\nHere are a few examples:\n\n- `fixed` layout with `width=300` and `height=200`:\n  ```\n  {% video 'video.mp4' 300 200 %}\n  ```\n- `responsive` layout with `width=300` and `height=200`:\n  ```\n  {% video 'video.mp4' 'responsive' 300 200 %}\n  ```\n- `fixed-height` layout with `height=200`:\n  ```\n  {% video 'video.mp4' 200 %}\n  ```\n- `fill` layout:\n  ```\n  {% video 'video.mp4' 'fill' %}\n  ```\n\n#### Video\n\nEmbed a video. The first parameter needs to be the video `src`. Controls are enabled by default. The default layout is `responsive` with an aspect ratio of `16:9`.\n\n```\n{% video 'https://amp.dev/static/inline-examples/videos/kitten-playing.mp4' %}\n```\n\n#### Twitter\n\nEmbed a Tweet. The first parameter needs to be the tweet `id`. There is no default layout.\n\n```\n{% twitter \"1182321926473162752\" \"responsive\" 375 472 %}\n```\n\n#### YouTube\n\nEmbed a YouTube video. The first parameter needs to be the youtube video `id`. The default layout is `responsive` with an aspect ratio of `16:9`.\n\n```\n{% youtube \"v0BVLgEEuMY\" %}\n```\n\n#### Instagram\n\nEmbed an Instagram post. The first parameter needs to be the post `id`. The default layout is `responsive` with an aspect ratio of `1:1`.\n\n```\n{% instagram \"BMQ8i4lBTlb\" %}\n```\n\n#### Github Gists\n\nEmbed a [Github Gist](https://gist.github.com/). The first parameter needs to be the fist `id`. There is no default layout, the recommended layout is `fixed-height`.\n\n```\n{% gist 'b9bb35bc68df68259af94430f012425f' 197 %}\n```\n\n### CSS\n\nAMP requires all CSS to be inlined:\n\n```\n\u003cstyle\u003e\n  {% include \"sample.css\" %}\n\u003c/style\u003e\n```\n\n`\u003cstyle\u003e` elements don't need to be defined in the `head`, but can be added anywhere on the page. This means, it's easy to modularize your CSS. For example, you can define style and markup in the same file, e.g. `components/greeter.njk`:\n\n```\n\u003cstyle\u003e\n.fancy-button {\n  background: black;\n  color: white;\n  border-radius: 4px;\n}\n\u003c/style\u003e\n\u003cbutton class=\"fancy-button\"\u003e\n  {{ buttonTitle }}\n\u003c/button\u003e\n```\n\n...and then use it in a different template like this:\n\n```\n{% set greeting = 'hello world' %}\n{% include \"components/greeter.njk\" %}\n```\n\nA good idea is to use this approach to modularize your CSS to ensure that your pages will only pull in the CSS that is actually needed.\n\n**Tip:** Modularizing CSS helps to stay within AMP’s 75kb CSS limit. The AMP plugin will automatically perform minification.\n\n### Options\n\nOptionally pass in an options object as the second argument to `addPlugin` to further customize this plugin.\n\n```js\nconst ampPlugin = require('@ampproject/eleventy-plugin-amp');\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(ampPlugin, {\n    // Disable AMP Cache (enabled by default)\n    ampCache: false,\n    // The host where the AMP runtime is being served from, the default is cdn.ampproject.org.\n    ampRuntimeHost: 'https://example.com',\n    // The optional target dir as configured in `dir.output`. Required for image optimization\n    // and AMP runtime self-hosting. Defaults to `_site`.\n    // See https://www.11ty.dev/docs/config/#output-directory\n    dir: {\n      output: 'dist',\n    }\n    // Download the AMP Runtime, default is false. Requires dir.output and ampRuntimeHost.\n    downloadAmpRuntime: true,\n    // Only process files that match a regex.\n    filter: /^.*amp.*$/,\n    // Image support in Markdown files might require customizing the location of images assets,\n    // pass either a directory.\n    imageBasePath: `${__dirname}/img`,\n    // ... or a function that returns the correct path based on img src and outputPath.\n    imageBasePath: (imageSrc, outputPath) =\u003e `${outputPath}/../img`,\n    // Enable image optimization (disabled by default). The default output dir is `_site`\n    // and the default image path is `/img/`. Otherwise ...\n    imageOptimization: true,\n    // ... customize output dir and image path.\n    imageOptimization: {\n      // The path optimized images should be served from.\n      urlPath: '/images/',\n    }\n    // Disable CSS minification (enabled by default).\n    minifyCss: false,\n    // If your site lives in a different subdirectory, use pathPrefix to specify this. Required\n    // when self-hosting the AMP runtime.\n    // See https://www.11ty.dev/docs/config/#deploy-to-a-subdirectory-with-a-path-prefix\n    pathPrefix: 'test',\n    // Disable AMP validation (enabled by default).\n    validation: false,\n  });\n};\n```\n\n## Development\n\nRun tests via:\n\n```\n$ npm test\n```\n\n### Adding new Shortcodes\n\nYou can add new shortcodes in [src/shortcodes/](src/shortcodes). It's best to copy and modify one of the existing shortcodes.\n\n# License\n\nCopyright 2020 The AMPHTML Authors\n\nLicensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fampproject%2Feleventy-plugin-amp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fampproject%2Feleventy-plugin-amp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fampproject%2Feleventy-plugin-amp/lists"}