AMP Project Starter
Starting a new project can take a lot of time, especially if the technology is new to you. What often helps is a project starter, meaning a template so you can have a look at how it's done.
For the development process, the AMP project itself has very good documentation and additionally there's AMP by Example which helps with countless examples. Both of those resources are great, but they lack information on how to actually build an entire AMP page. The AMP by example page actually is built with AMP and the code is available on Github, but it's a bit too overengineered for most people building an AMP page and not that well documented. I wanted something simple to understand, yet modular and scalable. That's why I'm writing html templates with Mustache and use the css preprocessor Sass (scss). Many developers are familiar with those tools, yet AMP pages of any size can be built with good modularity.
Install & Run
git clone https://github.com/bersling/amp-project-starter cd amp-project-starter npm install npm start
To get an overview of what you'll be working with, here's the structure:
amp-project-starter/ ├── app/ │ ├── components/ # here are reusable UI elements for your app │ │ ├── some-component/ │ │ │ ├── some-component.html │ │ │ └── some-component.scss │ │ └── ... # more components │ ├── pages/ #here go pages of your app (e.g. /about) │ │ ├── index.html # the root page │ │ ├── ... # more pages │ │ ├── category1/ # pages that will be available on /category1 │ │ │ ├── page1.html # will be on /category/page1 │ │ │ ├── page2.html │ │ │ └── ... # more pages │ │ └── ... # more categories │ └── styles/ # here go styles that don't belong to a component │ ├── styles.scss # the root of your scss │ ├── button.scss # styling your buttons... │ └── ... # even more styles ├── img/ # all images ├── dist/ # auto-generated folder that holds the compiled sources ├── node_modules/ # auto-generated folder that holds the node_modules ├── README.md # what you're currently reading (copied from readme.html) ├── deploy.sh # deploy script, adjust to your needs... ├── package.json # definition of all "npm" commands & packages that are required ├── server.js # small server to test app locally ├── .gitignore # files being ignored from git └── compile.js # part of the build process
Running a server
You can run a local server for development using
Now you should have a server running at port 8082. You'll just do this at the start of each development session. If you're heading ofer to http://localhost:8082, you'll find what the server is serving. If you've built the project, it should display the landing page.
Rebuilding when you changed something
To rebuild the project, after you've modified html or scss files or after you've added images to the img directory (or after any changes at all), run:
npm run build
This executes the "build" command in "scripts" in the
HTML powered by Mustache
Html is divided into two groups: pages and components. Pages are e.g. /about or /home. Components are things you want to reuse, for example
footer.html which you'll use on every page. After changes, run
npm run build.
To create a new page, create the necessary (AMP compatible) html. Then open
register your new page there! The same holds true for new components.
CSS powered by Sass (Scss)
Scss is sass, which is a precompiler for css to write more modular css. It's actually pretty easy to learn, you'll get the basics in 10 minutes by reading: http://sass-lang.com/guide
If styles are for a specific component, put them in the same folder as the html. You'll have to register/import all .scss files in styles.scss!
If they are general-purpose styles, put them in the styles folder at a matching position.
After changes, run
npm run build.
Since it's an AMP project, you'll have to be careful to follow the rules
of AMP. For instance, in an AMP project you're not allowed to use
<img> tag. You'll have to use the
<amp-img> tag. If you don't follow those rules
your page doesn't break, it just doesn't get the "AMP-SEO Bonus" anymore. During the build process, it logs to the console whether each page passes amp validation or not.
AMP has a lot of predefined components and a pretty good documentation you can find at https://www.ampproject.org/ and you'll find examples for all components at https://ampbyexample.com/.
To check out a larger page built with AMP starter, visit www.tsmean.com.
If you're missing a feature from this starter or have some other feedback for me, let me know! You can reach me at email@example.com.