statamic / docs

Statamic Documentation

Statamic Documentation

This is the source of the official Statamic docs.

Local Development

If you want to work on this project on your local machine, you may follow the instructions below. These instructions assume you are serving the site using Laravel Valet out of your ~/Sites directory:

1. Fork this repository
2. Open your terminal and cd to your ~/Sites folder
3. Clone your fork into the ~/Sites/docs folder, by running the following command with your username placed into the {username} slot: git clone [email protected]:{username}/docs statamic-docs
4. CD into the new directory you just created.
5. Run the following commands:

composer install
npm install
npm run dev
cp .env.example .env
php artisan key:generate

Providing Feedback

We love it when people provide thoughtful feedback! Feel free to open issues on for any content you find confusing or incomplete. We are happy to consider anything you feel will make the docs and CMS better.

Contributing

Thank you for considering contributing to Statamic! Every page in the docs site has a link at the bottom that will take you right to the exact content file that renders the page. Click the edit button and submit those PRs!

We simply ask that you please review the contribution guide before you send pull requests.

Code of Conduct

In order to ensure that the Statamic community is welcoming to all and generally a rad place to belong, please review and abide by the Code of Conduct.

Important Links

• Statamic Main Site
• Statamic Documentation
• Statamic CMS Repo (that we maintain)
• Statamic Application Repo (that you clone)
• Statamic Migrator
• Statamic Discord

docs's Issues

Docs Missing for HTML Fieldtype

HTML is missing from https://statamic.dev/fieldtypes

I attempted use this field to prompt user for HTML, but I think the HTML field is used to display custom HTML much like the Section item. However, Blueprint doesn't expose the ability to insert the HTML (possible a bug or feature request?) and there's nothing in the docs on how to do this using the .yaml

(The proper field to prompt for HTML is Code)

Direct non development users to cp demo, basic tutorials or get job quotes

As per discord discussion suggest to put a few simple pointers for non developers on a how to get started or installation page.

Inform non developer users that this platform is probably not for them (despite the Wordpress comparison it really isn't a Wordpress alternative for the general public), in which case perhaps provide a directory of developers they can contact? could be your discord job channel?

Or for the beginner developer/slash hobby coder perhaps a page of links or tips of things they need to learn? (antler, how to set up a local environment (please only one detailed option),

In any case I would love to see a live demo CP environment for non development decision makers which are often the key decision makers in the CMS solution (business owners, marketing heads, Digital Directors and content editors). Given all the promises of artisan simplicity not having access to an easy demo of your CP is sort of making a bad first impression and make non developers feel unwelcome which I don't think is the intention.

Everyone keeps saying that clients love the interface. And it is awesome and simple. Show it off, and then connect them with developers to get them going quickly.

Here's some draft copy for you... hope that helps :)

Interested in Statamic but not a developer?

Brilliant! Thanks for considering us - you're making a great choice. You'll be getting a much easier to use, faster, more scalable and better CMS than Wordpress. But we also have to be honest. While using Statamic is so much easier, faster and better than Wordpress, to get it set up and going you will need some coding skills.

Unlike Wordpress we don't build one click bloated slow and insecure websites with lots of bells and whistles that you don't need. In fact a large portion of our community are ex-Wordpress converts who never look back.

Instead we are focussed on creating lean and extremely user-friendly environments.

You're probably burning to try it out, so here's a link to a live demo of our control panel that you can take for a spin and see for yourself.

Or maybe you're ready to go and start your own project? Join our discord channel here and post your job in our #jobs channel. Our super friendly community of developers will be happy to help you out and give you a quote. Here's a free briefing template to get you going to make sure you and your development team are on the same page.

And if you're a starting out developer who knows a little bit about CSS and HTML and happy to learn some new skills here's a page with some resources and tutorials (link to page with must know tutorials for installing commander, valet, antlers and tailwind) we think will be helpful if you want to give Statamic a go.

Most of the pages in the 'Extend Statamic' section have gone light gray

This might of been on purpose but they weren't like this until recently.

Protecting collections or content routes

Hey guys,
I'm not sure if this is simply omitted in the Protecting Content doc or a bug. There seems to be no information about protecting collection entries or content routes. Neither of my below examples seem to work.

Collection entries
I would expect to be able to add the protect: logged_in to my collection.yaml, for example:

title: 'Collection'
template: collection/show
layout: layout
protect: logged_in

Content routes
For statamic's content routes I'd also expect to be able to pass my protect config like this:

Route::statamic('/alternate-collection-url/{slug}', 'collection/show', ['protect' => 'logged_in']);

Taxonomy fieldtype needs to be changed to Terms

Error in collections-and-entries > Date Behaviours

https://statamic.dev/collections-and-entries
Date Behaviors
future: private|private|unlisted
The first "private" should very likely be public.

Fix Install Now button

The yellow Install Now button somehow breaks ugly when on tablet size and my OCD is kicking in. Simply fix it by giving the a { white-space: nowrap; }.

Structure vs Nav docs confusion

1. The core concepts Structure page says to use the structure tag in your template, and links to a page that doesn’t exist.

This is the example code:

<ul>
{{ structure:top_nav }}
    <li><a href="{{ url }}">{{ title }}</a></li>
{{ /structure:top_nav }}
</ul>

2. The Nav Tag page seems to indicate that structures should be accessed using the nav tag.

My guess is that the Structures page needs to be rewritten? But maybe there just needs to be a page for a structure tag if such a thing exists?

Reflect fact attr parameter is no longer used

Might be a good idea to update the documentation to reflect the fact that the attr parameter has been removed from the form:create tag and normal parameters can be used (like ID, classes, etc)

It caused some confusion on statamic/cms#1743. This would be the documentation page that needs updated.

500 error for OAuth tag page

When navigating to the page, a 500 error is returned

Taxonomy term templating is incorrect

Not sure if this is code or docs that are wrong.

In https://statamic.dev/taxonomies#listing-term-entries the code sample for listing entries on a term route is incorrect. OR the docs are correct and the code is wrong. Take you pick.

Docs say to do:

{{ entries paginate="5" }}
  <ul>
  {{ results }}
    <li><a href="{{ url }}">{{ title }}</a></li>
  {{ /results }}
  </ul>
{{ /entries }}

To get this to work I had to do:

<ul>
  {{ entries }}
    <li><a href="{{ url }}">{{ title }}</a></li>
  {{ /entries }}
</ul>

API now Facades

In the upgrade guide...

Statamic\API classes are now Statamic\Facades

In the OAuth area it is still using Statamic\API

Collection Time Settings?

For collections you show how to enable date based settings but there is nothing about any time settings that can be enabled. I presume there is a way to set the time a collection should publish, so an example of how to configure that would be great.

https://statamic.dev/collections

Structure tag missing

There is a link on the Structures page (https://statamic.dev/structures) to the structure tag, however, when you click on the link, a 'Page not found' text is displayed. There is no structure tag right now.

Amp folder structure error

Small thing on statamic.dev/amp: In the folder illustration, the second "blog /" folder should be one level up.

resources/views/
|-- amp/
| |-- blog/
| |-- |-- index.antlers.html
| |-- |-- show.antlers.html
| |-- blog/
| |-- |-- index.antlers.html
| |-- |-- show.antlers.html

(Or I have to read that part of the docs again?)

Clarify the usage of the default forms template

When looking at the default forms template at https://statamic.dev/forms#the-template I recognized, that there is a new line compared to the Statamic v2 docs:

<div class="p-1">{{ field }}</div>

So I wondered what this line does, because I did not find any hint on that page. After trying out the code it turned out that the field property renders the complete input field. That is nice, so far. However, I wanted to give the input an extra class. In order to find out how that would work I look at the code behind.

My first thought was that field must be a special Tag which renders the field. But that is not true. The field attribute is actually an instance of \Illuminate\View\View, which returns the html markup of a partial. When looking at the partials at vendor/statamic/cms/resources/views/extend/forms/ I realized, that it is not easily possible to change the content of the partial, but that it is better to create my own frontend partials again, as I already did in Statamic v2. Also, when trying to use something different than Text or Textarea like Checkbox, it would still generate a plain text input field.

Long story short, I'd suggest to change this line in the docs to something like this, to prevent people from asking themselves how to modify the generated field markup:

{{ if type === 'text' }}
    <input type="{{ input_type ?? 'text' }}" name="{{ handle }}" value="{{ old }}" />
{{ /if }}

{{ if type === 'textarea' }}
    <textarea name="{{ handle }}" rows="5">{{ old }}</textarea>
{{ /if }}

{{ if type === 'checkboxes' }}
    {{ foreach:options as="key|label" }}
        <div>
            <input type="checkbox" name="{{ handle }}[{{ key }}]" value="1" />
            <span>{{ label }}</span>
        </div>
    {{ /foreach:options }}
{{ /if }}

What do you think?

Document using php in antlers

You name your view .antlers.php

Algolia results doesn't surface tags/collections

Description

If you try to search the Statamic v3 docs for 'collection' or 'collections' you get a load of results but it doesn't surface how to actually output collections i.e. these pages: https://statamic.dev/tags/collection, along with https://statamic.dev/tags/collection-next and https://statamic.dev/tags/collection-previous

As a Statamic beginner, I initially thought that the docs were incomplete until I found collections in the tags section of the v2 docs (through a Google search).

Maybe Algolia hasn't indexed the subpages in tags yet?

blueprints: confusing sentences

I don't understand what is meant here

"Note: This only applies to referenced fields. you can just set everything right there."

Maybe it's supposed to say "For inline fields, you can just set..." ?

Let Windows Users Know How to Symlink

I read it's a good idea to symlink the resources\dist folder during the alpha but the docs only showed a way that didn't work for Windows users. Add this and mark it "for Windows users":
mklink /D C:\path\to\your\app\public\vendor\statamic\cp C:\path\to\three-cms\resources\dist

Show replacements for removed conditions

In the Tag Conditions section of the upgrade guide, it is mentioned that several conditions have been removed.

Would be nice to see what the replacements are for contains not working in an array, for example.

Add example to all fieldtypes

I just wanted to suggest, that all fieldtypes should have an example in the docs, as it is much easier to copy/paste from the docs and edit the settings than to read all the config options and figure out how the syntax is exactly. And have an anchor on them which is on the same position on every fieldtype page, so there is a common pattern with Example/YAML and Config options in the scroll-to nav.

And another suggestion: maybe have a min & max example for all the settings in a fieldtype. Maybe the maximum example has all the default options listed as well.

e.g.: minimum example

favorite:
  type: radio
  options:
    donuts: Donuts
    icecream: Ice Cream
    brownies: Brownies

e.g.: maximum example

favorite:
  type: radio
  inline: false
  options:
    donuts: Donuts
    icecream: Ice Cream
    brownies: Brownies

I used the kitchen.yaml quite a lot in the past to copy example fieldtypes.

Search returns a 404 error

When visiting a search results page (like here https://statamic.dev/search-results?q=asset), a 404 page is returned.

Add localization docs

Will it be added to the docs later?

Multi-pages are covered with a hint about localization, but a deeper explanation would be great in the docs :-)

Development Domains

Would be good to consider adding .docksal to the development domains list as it is growing in popularity.

Typo in upgrade guide > Fieldsets

https://statamic.dev/upgrade-guide
Fieldsets
Fieldsets technically still exist, but they are are now a smaller …

User tags should be added to docs

In v2, a family of user tags are available in views. However they appeared to have disappeared from v3. Any chance we could have them back?

Entry routing examples

The depth and mount meta vars in routing don't have examples to show what they mean.

Explain where to put nginx config

It needs to be made clearer where nginx config goes.
The sample nginx config file we ship with cannot just be renamed to nginx.conf.

'You can betterify' message box smaller than text on some page

On some pages, the 'You can betterify this page on Github!' button is smaller than the text that's meant to be inside it (see screenshot)

Taxonomies: Listings and indexes

https://statamic.dev/taxonomies#listings-and-indexes

When on a taxonomy route, you can list the terms by using either a terms tag pair. For example:

Should this be:

When on a taxonomy route, you can list the terms by using a terms tag pair. For example:

Or is there another way to do it?

Tag features as "Pro"

Title says it all, I think. There was me enabling Git integration and wondering why nothing was working. It was because I had to turn 'Pro' on.

This is also an ideal way to upsell people to Pro!

Thanks, gentlemen!

Document adding config fields to a fieldtype

The $configFields array basically.

Document "message" being a reserved word in forms

You cannot have a field named message in your forms, since Laravel will pass the Message instance to the view.

See https://laravel.com/docs/7.x/mail#inline-attachments
See statamic/cms#2242

Server Error on Variables page

When you visit the variables page, the site returns a 500 server error.

Update collection tag parameters

We changes some around but never updated the docs.

Things like show_unpublished etc being removed.

z-index on search typeahead lets it fall behind page content

Same handle used twice on Grid Fieldtype

https://statamic.dev/blueprints#grid-fieldtype
handle: url

Document the cascade

In v2 there was a nice description of the cascade, that seems to be missing in v3. Shouldn't it be documented?

Add a page for Commands

Similar to https://docs.statamic.com/addons/classes/commands

About the templating part

I'm assuming it's not finished, isn't it?

instead

{{ images }} {{ url }} {{ alt }} {{ /images }}

feels like it should be

{{ images }} <img src="{{ url }}" alt="{{ alt }}"> {{ /images }}
`

Change example of bard set partials to new antlers format

On this page: https://statamic.dev/fieldtypes/bard#templating

You should change the example that reads

partials/
|-- sets/
|   |-- gallery.html
|   |-- image.html
|   |-- poll.html
|   |-- text.html
|   |-- video.html

To:

resources/views/partials/
|-- sets/
|   |-- gallery.antlers.html
|   |-- image.antlers.html
|   |-- poll.antlers.html
|   |-- text.antlers.html
|   |-- video.antlers.html

This way people know where to put these partials and they'll be reminded of the new antlers naming for them.

Um ... this is awesome

so this repo is in markdown which is being used in statamic and rendered by the SSG?

did I get this right?

if so 👍

Screenshot of Taxonomy fieldtype missing

I'm guessing there should be a picture of a taxonomy fieldtype on this page but it seems empty at the moment.

Add examples for Query Scopes & Filters

In the Query Scopes section, you mention:

You may create scopes that can be used in various places, such as inside the collection tag or inside control panel listings.

Would be great if there were examples (or links to examples) of how those can actually be used.

Add example on how to use Live Preview custom render methods

It's not super clear on how to use Live Preview's custom render methods. We should provide an example or two for common use cases - e.g. an SPA, Gatsby, or something like that.

For reference: https://twitter.com/JamesWee_/status/1284095657293131777

Variables sections have wrong ID

The Variables section has id="parameters" instead of id="variables". This also makes the Variables link in the right content navigation not work.

Some examples:
https://statamic.dev/tags/collection
https://statamic.dev/tags/form-create

General Data Protection Regulation tips

It would be nice to have some pointers how to correctly setup Statamic in line with the General Data Protection Regulation or simular regulations. Especially where it comes to user accounts. While storing in file has is the prefered way for usabilty, it is also the hardes to use in line with the GDPR and especially with the "Right to be forgotten" which makes it impossible to add users to a version control repository as removing a single user from the complete repository is pretty much impossible.

site_url Variable does not longer exists

{{ site_url }} is documented here https://statamic.dev/variables/homepage#content but only its alias {{ homepage }} seems to be defined.

Fix Prism.languages.files

Parsedown handles these blocks a bit differently and the output is different.

• <br> isn't added (fixed by commenting out env.content = env.content.replace(/\n/g,'')+'<br />';)
• Directories aren't detected
• Icons are black (and inside base64 encoded SVGs)