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.
git clone https://github.com/bersling/amp-project-starter
cd amp-project-starter
npm install
npm startTo 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
You can run a local server for development using
npm start
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.
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 package.json file.
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 compile.js and
register your new page there! The same holds true for new components.
As a templating language, this starter uses Mustache. Here's a good tutorial on Mustache: The Ultimate Mustache Tutorial. The following mustache implementation is used: Mustache for JavaScript.
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
the <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/.
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 protected].