bemit / create-amp-page-starter

⚡ AMP page starter, build handling, 1-click deployment with netlify cms and styled with @formanta/sass.

Create AMP Page Starter ⚡

Starting point for AMP pages generated with create-amp-page and using @formanta/sass for styling. Directly deploy with netlify cms as git managed static site generator!

npm i
npm start

# or
npm run build

# test driven UI development with cypress:
npm run tdd-ui

npm run tasks
npm run clean

Open localhost:4488/defaultPage for your local page preview and change something in src/*!

Features

Provides a basic file structure and uses the gulp build tasks of create-amp-page, with additionally: markdown and netlify cms.

• uses .scss files
• page data as .json and/or .md with frontmatter
• twig templates and pages
  • pages by template files in src/html/pages
  • pages with folders of frontmatter / collections
  • using page filename for
    • frontmatter files resolution
    • links generation (e.g. canonical)
  • use custom data, functions, filters and more
• media optimizing for png, jpg, gif, svg
• markdown to HTML generation, preinstalled markdown-it plugins for extended syntax
• basic Twig template for AMP or none AMP pages
  • ampEnabled = true as template variable enables the needed AMP parts
  • HTML for AMP scripts
  • inline CSS parts for AMP, also where the CSS is injected by gulp task
  • amp attribute at html tag
• AMP Optimizer and removing unused CSS for production
• Headless Netlify CMS for site generation supported
  • uses also frontmatter
  • git repository management and netlify CI/CD
  • identity management by netlify, github and more
  • easily removable when not wanted:
    • delete public/admin folder and remove the netlify cms part in src/html/_base.twig block body_end_script

Default File Structure

• build dist folder after running npm run build or while npm run start
• public with general files in root like manifest.json
• public/admin config and setup files for netlify cms
• src/api may be used as mock api
• src/data contains the page frontmatter and data
• src/html is the base for all twig templates
• src/html/pages will be build to individual HTML pages
• src/media may contain images
• src/styles/main.scss is the style sheet

Netlify CMS

This starter repository supports one click deployment on netlify, in your netlify project the identity handling must be setup - and you are ready! The template files, scripts and content schemas are already configured.

Setup identity management and adjust the email templates:

1. Setup netlify project
   • In netlify project, under identity: click enable identity
   • Click on Settings & Usage
   • Scroll to Registration preferences and change to Invite only
   • Optional, recommended: add external providers with default config like GitHub
   • Scroll to Git Gateway and enable it
   • Now the general identity handling is working
2. Change email template paths in netlify, read why below
   • Invitation template to: /email/invitation.html
   • Confirmation template to: /email/confirmation.html
   • Recovery template to: /email/recovery.html
   • Email change template to: /email/email-change.html
3. Invite yourself in the project's identity management
4. Ready to login under https://<your-page-name>.netlify.app/admin/, your page is published at https://<your-page-name>.netlify.app/
5. Check netlify.toml for deployment settings like basic auth, edit the CMS content schema in public/admin/config.yml

This is an AMP boilerplate and can't use netlifys custom JS login redirect-handling, the login would be buggy: after accepting the invite you will be directed to /, this triggers the login correctly (JWT exchange) when the identity widget is loaded, but you will not be redirected to /admin/ again. To solve this, the email templates must be changed and /admin/ added between domain and # before the tokens, the templates at src/email/ are already adjusted. For ampEnabled=false the identity widget will be loaded by default in frontend, you may remove it in src/html/_base.twig. The email templates are copied to build/email as netlify needs normal HTTP access.

Take a look at the authentication documentation for netlify cms, check how to configure the cms and checkout the default widgets.

AMP Component Library

This starter will contain more and more ready to use AMP components and their CMS definitions when needed.

Universal Twig functions, used within templates, are included in create-amp-page, check out the function docs

Twig Embed Image

Displays an img or amp-img tag using ampEnabled, layout defaults to 'responsive'. Set's width and height using getImage fn, adds sha1 cachebuster.

todo: srcset and image resizing support

{% embed 'blocks/image.twig' with {
    src: '/media/img-01.png',
    alt: 'A blog hero image',
    classes: 'mb2',
    layout: 'responsive',
} %}
{% endembed %}

PWA / Javascript Support

This is not really AMP compatible, or harder to develop e.g. SSL for local amp-script debugging and max. 150KB of total script sizes. Suites non-AMP pages perfectly. Use with AMP when you know what you do!

Checkout the separate create-page-starter repository, it has babel+webpack configured with Typescript and React.

License

This project is free software distributed under the MIT License.

See: LICENSE.

Contributors

By committing your code/creating a pull request to this repository you agree to release the code under the MIT License attached to the repository.

Copyright

2022 | Michael Becker, bemit UG (haftungsbeschränkt)