{"id":15386679,"url":"https://github.com/zerodevx/amp-build","last_synced_at":"2025-04-14T09:30:53.605Z","repository":{"id":93487652,"uuid":"82673130","full_name":"zerodevx/amp-build","owner":"zerodevx","description":"An opinionated Google AMP static site build","archived":false,"fork":false,"pushed_at":"2020-01-31T06:40:51.000Z","size":2506,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T22:48:33.563Z","etag":null,"topics":["amp-html","boilerplate","pwa","starter-kit","tooling"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zerodevx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-21T11:40:43.000Z","updated_at":"2020-06-16T21:37:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"ef108ab4-2959-4c10-8077-95753a44ac92","html_url":"https://github.com/zerodevx/amp-build","commit_stats":{"total_commits":25,"total_committers":2,"mean_commits":12.5,"dds":"0.040000000000000036","last_synced_commit":"093f0fb0cf761e35f341f10671002d035152968f"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Famp-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Famp-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Famp-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Famp-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerodevx","download_url":"https://codeload.github.com/zerodevx/amp-build/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248854116,"owners_count":21172297,"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":["amp-html","boilerplate","pwa","starter-kit","tooling"],"created_at":"2024-10-01T14:50:10.241Z","updated_at":"2025-04-14T09:30:53.562Z","avatar_url":"https://github.com/zerodevx.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amp-build\n\n![GitHub release](https://img.shields.io/github/release/zerodevx/amp-build)\n\nAn opinionated [AMP](https://amp.dev) static site build and static site generator.\n\nUse this to create full-featured websites that are also AMP-validated pages. Does not require compilation or\na build step during development, because that's so passé. Runs almost entirely off NPM scripts, because things\nshouldn't be so complicated.\n\n\nFeatures:\n\n* Super optimized build.\n* Tailwindcss v1 as utility CSS.\n* PurgeCSS v1 to remove unused CSS.\n* HTMLMinifier v4 for minification.\n* XML Sitemap via static-sitemap-cli v1.\n* Material Icons.\n* Nested navigation menu.\n* Workbox v4 for offline goodness. (WIP)\n* App Shell PWA architecture. (WIP)\n\n\n## Quick-start\n\n### Install\n\nI recommend installing this repo as a `git-subtree`. Here's an [excellent writeup](https://codewinsarguments.co/2016/05/01/git-submodules-vs-git-subtrees/) on this.\n\n\n```\ngit subtree add --prefix amp-build https://github.com/zerodevx/amp-build tags/vX.X.X --squash\n```\n\nwhere `X.X.X` is the latest release semver.\n\n\nNext, install dependencies.\n\n```\ncd amp-build\nnpm install\n```\n\n### Initialise\n\nScaffold the `src` directory.\n\n`npm run scaffold`\n\n\n### Serve and run\n\nStart the local server.\n\n`npm run serve`\n\nPoint your web browser to `http://localhost:8000/src/site/` - no build step required.\n\n\n### Upgrade\n\nTo upgrade `amp-build` to a newer version,\n\n`git subtree pull --prefix amp-build  https://github.com/zerodevx/amp-build tags/vX.X.X --squash`\n\nwhere `X.X.X` is the newer release semver.\n\n\n\n## Usage\n\n\n### Directory structure\n\n```\nsrc/\n  site/           -\u003e site structure goes here\n  layouts/        -\u003e page templates go here\n  images/         -\u003e images go here\n  snippets/       -\u003e reusable HTML chunks go here\n  styles/         -\u003e for tailwind to generate styles.css\n  scripts/        -\u003e insert-snippet.js\n  pwa/            -\u003e PWA-related stuff\n```\n\n\n### Site\n\nDuring development, by design, everything should work without compilation. Simply run any http server\noff the `amp-build` directory at `http://localhost:8000`, or run:\n\n`npm run serve`\n\nVisit your page at `http://localhost:8000/src/site`.\n\nReference all links by their *absolute* url, for example:\n\n`\u003ca href=\"http://localhost:8000/src/site/giraffes/\"\u003eWhat are giraffes?\u003c/a\u003e`\n\n\n### Snippets\n\nReusable HTML blocks go into snippets (located at `/snippets`). Insert snippets into page using a `script` tag,\n`snippet` attribute, and source to `src/scripts/insert-snippet.js`. For example:\n\n`\u003cscript snippet=\"header.html\" src=\"http://localhost:8000/src/scripts/insert-snippet.js\"\u003e\u003c/script\u003e`\n\n\n### Default Snippets\n\n```\nsnippets/header.html          -\u003e Header\nsnippets/footer.html          -\u003e Footer\nsnippets/icons.html           -\u003e Icon meta tags\nsnippets/amp-components.html  -\u003e Default amp-components for every page\nsnippets/analytics.html       -\u003e Default amp-analytics for every page\n```\n\n\n### Images\n\nAll images go into `src/images`. Reference all images by their *absolute* url, for example:\n\n`\u003camp-img src=\"http://localhost:8000/src/images/short-giraffe.jpg\" width=\"500\" height=\"500\" layout=\"responsive\"\u003e\u003c/amp-img\u003e`\n\n\n### Minifying Images\n\nImagemin takes a long time (and really should only be run once), so minify the images in `src/images/` using:\n\n`npm run build:images`\n\nDuring build, the `src/images/` directory will be copied directly without further modifications.\n\n\n### Favicons\n\nI recommend using https://realfavicongenerator.net/ to generate your favicons. Place all favicons into `images/icons`\ndirectory. They will be moved into site root at build. Update `snippets/icons.html` with the associated meta tags.\nNote that `images/icons` will be ignored during `imagemin` minification so as to preserve your quality settings.\n\n\n### Layouts\n\nBy default, new pages are generated from `src/layouts/default.html`. This serves as the template whenever a new page\nis scaffolded.\n\nAdd a new page:\n\n`npm run scaffold:page -- \u003curl\u003e \u003coptional: template\u003e`\n\nFor example:\n\n`npm run scaffold:page -- /about/services section`\n\nThis copies `src/layouts/section.html` to `src/site/about/services/index.html`. If the directory does not exist,\nit will be created.\n\n\n### Adding Pages Manually\n\nYou can add new pages yourself. Simply create the new directory and copy an existing `index.html` in as a reference\ntemplate, and ensure that placeholder comments (for eg. `\u003c!--sw:start ... sw:end--\u003e`) remain.\n\n```\nmkdir src/site/my-new-page\ncp src/site/index.html src/site/my-new-page\n```\n\n\n### Styles\n\nUse tailwind classes to construct your page. If you wish to make changes to `src/styles/tailwind.configjs` (for theming),\nor `src/styles/tailwind.css` to add more functional classes - edit the files, then run the following to regenerate\n`styles.css`:\n\n`npm run build:tailwind`\n\n\n### Config\n\nSet global configuration at `src/config.json`.\n\n| Key              | Type          | Description                                                  |\n|------------------|---------------|--------------------------------------------------------------|\n| stagingUrl       | String        | Base URL of staging site                                     |\n| productionUrl    | String        | Base URL of production site                                  |\n\n\n## Builds\n\n### Test build locally\n\nGenerate your build locally into the `build/` directory.\n\n`npm run build`\n\nBuild can be tested by pointing your web browser to `http://localhost:8000/build`.\n\n### Staging build\n\nEnsure that `stagingUrl` is defined in `src/config.json`, then run\n\n`npm run build-staging`\n\nThis prepares `/build` for Staging - files are minified and amp-validated but have analytics disabled and are not indexable by search engines. The `/build` directory can then be copied over and published to your Staging server.\n\n### Production build\n\nEnsure that `productionUrl` is defined in `src/config.json`, then run\n\n`npm run build-production`\n\nThis generates the production build that is minified, amp-validated, analytics enabled, and indexable. The `/build` directory\nis ready to be copied over to your Production directory for deployment.\n\nI recommend using [rsync](https://gist.github.com/zerodevx/9f71a4530f70d4947747ad170c67cd25) to perform the copy,\nsomething like:\n\n```\ncd build\nrsync -rlpgoDci --del --exclude=.DS_Store . ../production\n```\n\n### Sitemap for Production\n\nI recommend generating the sitemap after the rsync operation. This preserves the correct `lastmod` timestamp\nfor files that are not changed, so Google won't reindex those in vain.\n\n```\nnpm run build:sitemap -- -r \u003cpath/to/production\u003e\n```\n\nThis generates a `sitemap.xml` in your production path.\n\n\n### amp-cache\n\nThe first AMP page that a user enters, on mobile, from a search engine, are viewed through the AMP viewer - which loads\na special cached version of your page from the AMP cache. You might want to invalidate the cache after a new production\ndeployment.\n\nThe amp-cache can be updated via a [update-cache](https://developers.google.com/amp/cache/update-cache) operation.\n\nView instructions from the link to generate your `privateKey.pem` and `apikey.pub` pair. The cache can be updated via\n\n```\nnpm i --save @ampproject/toolbox-cli\nsscli [BASEURL] -r \u003cpath/to/root\u003e -t \u003e sitemap.txt\nwhile IFS= read -r line; do amp update-cache $line; done \u003c sitemap.txt\n```\n\n\n\n## TO-DOs\n\n### LD+JSON\n\nMake a better way to automate this.\n\n\n### Service Worker\n\nIntegrate service worker generation into build.\n\n\n### PWA/App Shell\n\nBuild should eventually become a [PWA](https://developers.google.com/web/progressive-web-apps/), where AMP-validated pages\nare indexed by search engines and act as an entry point to a complete PWA app.\n\nAt the moment, [Amp Shadow](https://github.com/ampproject/amphtml/blob/master/spec/amp-shadow-doc.md) does not\nseem to be working very well, and it's not clear if AMP devs are continuing work on it.\n\nAlso, during proof-of-concept it's discovered that not all AMP components work as expected after being piped in.\n\n\n## Changelog\n\n**v1.1.0** - 2019-08-17:\n* Remove `shx` - sorry Windows.\n* Update `static-sitemap-cli` to v1.\n* Add gist for copy-build best practice.\n\n**v1.0.0** - 2019-07-31:\n* Complete overhaul so that things should be easier to reason with now.\n* This should be good enough as a base to build on.\n\n**v0.1.0** - 2018-10-05:\n* Initial release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodevx%2Famp-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerodevx%2Famp-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodevx%2Famp-build/lists"}