Statamic Starter Kit

Statamic Peak is an opinionated starter kit for all your Statamic sites. It's design agnostic but comes bundled with tools like Tailwind and AlpineJS and a workflow you can use to build anything you want. Peak features a page builder, a rich collection of starter templates, fieldsets, blueprints, configuration and more to get you started on your clients' site straight away. Peak is easy to extend or edit to fit your clients' website needs.

The aim of Peak is to make it easy to start new projects as they often share much of the same principles. Whether you're new to Statamic or a veteran, there will be something interesting in here for you. Feel free to participate and discuss on how to make Peak better.

Getting started

Browser support

Peak makes extensive use of CSS Grid so it doesn't support IE11.

Knowledge assumptions

Before using Peak make sure you're familiar with:

Statamic
Antlers
TailwindCSS
And to lesser extend: AlpineJS (JS framework)

Installation

Installation via the CLI

The easiest way to install Statamic together with Peak is to use the official CLI. Install the CLI by running composer global require statamic/cli and for each project just run statamic new my-site and pick Peak as a starter kit. Alternatively you can skip this manual selection by running: statamic new my-site --starter="statamic/starter-kit-cool-writings".

Manual installation.

1. Create a new site - cloning the repo and removing the origin repo.

git clone git@github.com:studio1902/statamic-peak.git my-site
cd my-site
rm -rf .git
composer install
cp .env.example .env && php artisan key:generate

2. Edit .env file - make sure you edited the .env file with at least the correct values for APP_NAME, APP_URL and the local mail configuration.

3. Make a new user – you'll want it to be a super so you have access to everything.

php please make:user

4. Compile the fontend assets - the TailwindCSS compiled assets aren't included in this repo. You need to compile it yourself. Compilation is configured in webpack.mix.js. Make sure you add your hostname to your .env file (APP_URL) as it's being used for Browsersync in webpack.mix.js.

npm i && npm run watch (or npm run dev)

To compile for production run this (on your server). It will purge all unnecessary utility classes and greatly reduce file size:

npm run production

5. Build! - if you're using Laravel Valet, your site should be available at http://my-site.test. You can access the control panel at http://my-site.test/cp and login with your new user. Build your site, read the Statamic Docs and have fun!

Tailwind configuration

Peak comes with a tailwind.config.js which dictates how Tailwind should be compiled. This file imports multiple Tailwind config files each responsible for various parts of your website. Next to the default config, it uses the following configuration files:

tailwind.config.typography.js: the Tailwind typography configuration for customizing the prose class.
tailwind.config.peak.js: all Peak's configuration, utilities and components.
tailwind.config.site.js: your site's configuration. This file would typically include all custom styles and config for the project you're currently working on.

All configuration files are fully documented. Read the Tailwind docs on theme configuration for more information.

Read up on the Tailwind Forms and Tailwind Typography plugins. They're easy to customize and the config file for typography already include some basic customization. The plugins are easy to remove if you don't plan on using them.

When your app environment is local, Peak will add a breakpoint notice to your site so you can tell on which breakpoint you're currently displaying the website. You can turn this off by removing {{ environment == 'local' ? 'debug' : '' }} from resources/views/layout.antlers.html.

You can use a helper utility by adding the class ? to quickly identify elements on screen. Original idea by Gavin Joyce.

Features

Assets

Images

Peak comes a picture partial that will add responsive sourcesets to your images. The variants generated are defined in config/statamic/assets.php and cover most use cases. In resources/views/components/_figure.antlers.html you can see an example of how to include the picture partial. It accepts the following arguments:

image: asset, the actual image variable.
class: string, optional css classes that should be applied to the image.
cover: boolean, true means the image should cover the containing element.
sizes: string, the sizes attribute that informs the browser how the image should be rendered.

See this article for more information.

Background images

Peak comes with a background image snippet you can use to apply responsive images (WebP included) to an elements background. Just use {{ partial:snippets/background_image image="YOUR_IMAGE" class="CLASS_OF_ELEMENT_THAT_NEEDS_BG_IMAGE" }}. The predefined sizes used in resources/views/snippets/_background_image.antlers.html are defined in config/statamic/assets.php.

Bard

For long form content you can use the Article content block. This is a Bard fieldtype with multiple sets of fields that are regularly used in longer articles.

Adding sets

Edit resources/fieldsets/article.yaml to add sets (preferably imports) to the article. In resources/views/page_builder/_article.antlers.html you can see the sets being loaded. Antlers will look in the resources/views/components/ folder for partials with the handle of your set.

For example if you add a fieldset to the article.yaml with the handle table make sure you add a _table.antlers.html file to the resources/views/components folder.

Note: sets are scoped under set to avoid collision with other fields. Make sure you reference variables in a block like this: {{ set:field_name }}

Sizing utilities

An article goes into a CSS Grid with 12 columns. By default all sets get the class size-md. As you can see in tailwind.config.js on mobile this means those elements span 12 columns. On larger screens however they just span 6 columns (centered). There are other sizing utilities as well:

size-sm: 12 columns on mobile, 4 columns from medium screens up
size-md: 12 columns on mobile, 6 columns from medium screens up
size-lg: 12 columns on mobile, 8 columns from medium screens up
size-xl: 12 columns on mobile, 10 columns from medium screens up

For example use the sizing utilities to let an image break out of it's content. In sets like figure and video the user can pick their own size using the size field in resources/fieldsets/common.yaml.

Note: the layout doesn't have to be centered and is easy to change in the tailwind.config.js file.

Screenshot Bard Sets | Screenshot Bard Figure & Buttons

Buttons

The files resources/fieldsets/buttons.yaml and resources/views/components/_buttons.antlers.html go together. The button fieldset is a set in Bard but can also be called from other fieldsets where you want to include buttons. Just call the buttons partial in your template and one or multiple buttons will be rendered.

Screenshot Bard Figure & Buttons

Forms

Peak renders forms and mail templates dynamically so you can add as many forms as you'd like, just by creating them in the CP. Peak ships with a default basic contact form you can edit using the following files:

resources/forms/contact.yaml The contact form configuration.
resources/blueprints/forms/contact.yaml The forms blueprint defining all the fields.
resources/views/page_builder/_form.antlers.html The forms template file.
resources/views/email/form_owner.html The forms email template that goes out to the site owner. The _text.html version contains the text template.
resources/views/email/form_sender.html The forms email template that goes out to the sender of the form. The _text.html version contains the text template.

Strings used in the e-mail templates are localized and defined in resources/lang/en/site.php, and the form's field labels are localized and defined in resources/lang/en.json.

The forms sending is done with AJAX and uses Alpine to display the various notifications.

Note: Peak dynamically fetches a CSRF token so you can even use forms with Static File Caching on. This technique is based on the Dynamic Token addon for Statamic v2 by Mykolas. It's ported to v3 and included with Peak.

Note: When using BrowserSync and visit your site by means of an IP adress as url; You'll get an 500-error upon submitting the form. This is caused by Statamic's FormController which identifies your Site by means of the FQDN listed in config/statamic/sites.php. As you visit the website through an IP adress this lookup will fail, resulting in the said 500 Call to a member function shortLocale() on null error.

Screenshot Form Page Builder | Screenshot Form error handling | Screenshot Form mail to owner | Screenshot Form mail to sender

Globals

Peak currently comes with two global sets you often need, one to edit content on error pages like the 404 page and one to add social media accounts to your website. There's already a basic 404 template in place (resources/views/errors/404.antlers.html) to display those messages.

Screenshot Globals Errors | Screenshot Globals Social Media

Navigation

Peak includes basic unstyled responsive navigation with two levels. Open resources/views/navigation/_main.antlers.html to make changes. There's a desktop version that only shows on md screens and up as well as a mobile version that shows on smaller screens. AlpineJS takes care of the interactivity. The state of the mobile navigation toggle is defined on the <body> tag in resources/views/layout.antlers.html.

Peak also includes an optional breadcrumbs partial you can find in resources/views/navigation/_breadcrumbs.antlers.html.

Page builder

While you could make different templates for all your page types, the idea is to make pages as modular as possible. Every unique element of your website could be a partial and a dedicated button in the page builder.

If the layout of a page is totally different - or you really want to - you can always opt for using templates.

Screenshot page builder

Adding blocks

Edit resources/fieldsets/page_builder.yaml to add blocks (preferably imports) to the fieldset. In resources/views/default.antlers.html you can see the blocks being loaded. Antlers will look in the resources/views/page_builder/ folder for partials with the handle of your block. Peak ships with the following blocks:

Article (long form content)
Call to action (title, text and a button)
Collection (title and links to other entries)
Forms
Link blocks (blocks with a title and text that link to other entries)

For example if you add a fieldset to the page_builder.yaml with the handle call_to_action make sure you add a _call_to_action.antlers.html file to the resources/views/page_builder folder.

Note: blocks are scoped under block to avoid collision with other fields. Make sure you reference variables in a block like this: {{ block:field_name }}

Screenshot link blocks | Screenshot link blocks

Pagination

When you're working with the collection tag and want to use pagination, just add the pagination partial using partial:components/pagination to automagically add pagination buttons. They're easily editable in resources/views/components/_pagination.antlers.html.

The pagination partial automatically adds linktags to your documents head with rel="next" and rel="prev".

Note: the strings used in the partial are translatable and can be edited in resources/lang/en/site.php.

SEO

Peak includes full SEO support. It's easy to expand on since it's all built with native fields and templating. You can also easily replace it with a professional addon like Aardvark SEO or SEO Pro.

SEO features

Edit the title.
Edit the website title and separator.
Edit the meta description.
Add a canonical URL.
Add Open Graph data and image.
Add a default Open Graph image.
Auto generated sitemap.xml, customize which collections are included and per entry frequency and priority settings.
Turn on no-index for an entry, also have it excluded in the sitemap.
Add custom JSON-ld schema objects.
Auto generated hreflang tags on localized sites.
Add knowledge graph data (organization, person or custom).
Auto generated optional JSON-ld breadcrumbs.
Add trackers: Google Analytics, Google Tag Manager, Site Verification or Fathom.

Screenshot global | Screenshot per entry | Screenshot per entry

Disable SEO features

If you plan on using an addon for SEO and Peak's built in features, do the following:

Remove {{ partial:snippets/seo }} from resources/views/layout.antlers.html.
Remove {{ yield:google_tag_manager }} from resources/views/layout.antlers.html.
Remove the SEO section and import from resources/blueprints/collections/pages/page.yaml.
Remove the whole {{ section:pagination }}{{ /section:pagination }} from resources/views/components/_pagination.antlers.html.
Delete the SEO global content/globals/seo.yaml.

And optionally to erase all traces:

Delete the SEO sitemap view resources/views/sitemap/sitemap.antlers.html
Delete the SEO global blueprint resources/blueprints/globals/seo.yaml.
Delete the SEO fieldset resources/fieldsets/seo.yaml.
Delete the SEO partial resources/views/snippets/_seo.antlers.html.

Statamic login screen

The Rad Mode™ on the login screen is disabled by default to give the login screen a less fun, but more businessy look. If you want to re-enable Rad Mode, delete resources/views/vendor/statamic/auth/login.blade.php.

If you want to use another logo on the login screen. For example the current sites logo, uncomment the code in /public/vendor/app/css/cp.css and point to an image file of choice.

Typography

Peak contains a few basic typography partials in resources/views/typography. Whenever you need to render text in your partial you should call the relevant partial or add a new one. Let's say we have a block in our page builder with a {{ title }} field. In the template partial for your block you could do the following:

{{ partial:typography/h1 :content="block:title" }}

This will render the title with the styling defined in typography/h1. This way you ensure the same styling throughout your website without having to add or edit Tailwinds utility classes in multiple template files. You can even change the tag and text color and add classes if need be:

{{ partial:typography/h1 tag="span" color="text-error-600" class="mb-8" :content="block:title" }}

Peak comes with a few defaults that are easy to style. Feel free to add more partials for your current website.

Other

Configuration changes

Peak changes the default Statamic config. The following is different:

File	Default	Peak
`.env.example`		Add more default Statamic and Redis settings by default.
`app/console/Kernel.php`		Add a schedule you can invoke via a cron to warm all caches.
`app/Http/Controllers/DynamicToken.php`	-	New Controller for forms
`app/Http/Middleware/VerifyCsrfToken.php`	`protected $except = []`	`protected $except = ['/!/DynamicToken']`
`app/Tags/DynamicToken.php`	-	New Tag for forms
`config/statamic/assets.php`	`'cache' => false`	`'cache' => env('SAVE_CACHED_IMAGES', true),`
`config/statamic/assets.php`	`'presets' => [],`	Contains a whole bunch of asset presets.
`config/statamic/cp.php`	A getting started widget	A page collection widget
`config/statamic/cp.php`	`'link_to_docs' => true`	`'link_to_docs' => false`
`config/statamic/editions.php`	`'pro' -> false`	`'pro' -> true`
`config/statamic/git.php`		Add `[BOT]` to git commit message.
`config/statamic/live_preview.php`	Three breakpoints	All tailwinds breakpoints defined in `tailwind.config.js`
`config/statamic/stache.php`	`'watcher' => true`	`'watcher' => env('STATAMIC_STACHE_WATCHER', true)`
`config/statamic/static_caching.php`	`rules' => [ // ]`	`'rules' => 'all'`
`config/statamic/users.php`	`'avatars' => 'initials'`	`'avatars' => 'gravatar'`
`routes/console.php`		A `php artisan warm` command to warm the static cache.
`routes/web.php`		Routes for the sitemap and dynamic form token.

Deployment script

You could use the following deployment script together with Peak to make sure everything runs smoothly after a deploy.

php artisan cache:clear # Clear the Laravel application cache.
php artisan config:cache # Clear and refresh the Laravel config cache.
php artisan statamic:stache:warm # Warm the Statamic stache.
php artisan statamic:static:clear # Clear the Statamic static cache (if you use this).
php artisan warm # Warm the Statamic static cache (if you use this / only available in Peak).
php artisan statamic:assets:generate-presets # Generate all asset presets.

Focus-visible

Focus-visible solves a lot of issues regarding a11y and styling. To use focus-visible today we need polyfills (for Safari). One in Javascript and one in PostCSS. With focus-visible we can make sure the browser only shows an outline when the user navigates with a keyboard. This means no more outlines in Chrome when you click styled buttons.

You can take this even further by using the Tailwind Ring utilties together with the focus-visible: variant to customize and brand your focus styles. Peak has the focus-visible: variant enabled by default for the ringWidth utility. You can disable this in tailwind.config.js.

Modernizr

Peak comes with Modernizr support. By default the only feature detect that's added is WebP. It will add a webp class or a no-webp class to the <html> tag. If you want to add more feature detects you can edit modernizr.config.js.

Multilingual fields and localization

It is currently not possible in Statamic to translate field labels and descriptions so I settled for English. Translate the labels and descriptions in all fieldsets (resources/fieldsets/*.yaml) and follow the the instructions in the Statamic documentation to make the Statamic CP available in your language of choice.

Reduced motion

The default anchor styles configured in tailwind.config.site.js respects users that prefer less motion. Other transition utilities used in Peaks' templates are prefixed with the motion-safe: variant by default. Motion-safe variants are enabled for all animation and transition utilities. You can disable this in tailwind.config.js. Read more on how motion safe works.

Upcoming features

Check the issues and pull requests for upcoming features.

Warm all caches

Running php artisan warm after your deployments will visit all urls and warm up the static cache. This is a custom command and is defined in routes/console.php.

Triggering php artisan schedule:run with a cronjob on a server will hourly clear and warm all caches. It basically chains all commands defined in the deployment-script. Edit app/console/Kernel.php if you don't want this hourly but for example daily. Read more in the Laravel Docs.

Contributing and license

Contributing

Contributions and discussions are always welcome, no matter how large or small. Treat each other with respect. Read the Code of Conduct.

License

The MIT License (MIT). Please see License File for more information. Statamic itself is commercial software and has its' own license.

Pixney-William/statamic-peak

Statamic Starter Kit

Getting started

Features

Other

Contibuting and license

Getting started

Browser support

Knowledge assumptions

Installation

Installation via the CLI

Manual installation.

Tailwind configuration

Features

Assets

Images

Background images

Bard

Adding sets

Sizing utilities

Buttons

Forms

Globals

Navigation

Page builder

Adding blocks

Pagination

SEO

SEO features

Disable SEO features

Statamic login screen

Typography

Other

Configuration changes

Deployment script

Focus-visible

Modernizr

Multilingual fields and localization

Reduced motion

Upcoming features

Warm all caches

Contributing and license

Contributing

License