Add Statamic's Antlers template language

[jasonvarga]

Description

This PR adds support for Statamic's templating language named "Antlers".

As the language is a subset of HTML, we use prefixed extensions:

• filename.antlers.html
• filename.antlers.xml
• filename.antlers.php

I'm not sure of the implications of this regarding the classifier. The contribution guide suggests I should ping @lildude, so, ping! 👋

I haven't contributed a language before, so I don't know if I've missed anything.
I can confirm the syntax itself does work (outside the context of linguist) as its been successfully used in VSCode using https://antlers.dev and in libraries such as Shiki using the same grammar file.

Let me know if you need anything else from me. Thanks!

Checklist:

• I am adding a new language.
  • The extension of the new language is used in hundreds of repositories on GitHub.com.
    • Statamic itself is used in hundreds of repos. It's possible to use other templating languages but most of the time they would be using Antlers.
    • Search results for each extension:
      • It doesn't look like GitHub's search supports searching for a suffixed extension like .antlers.html so here are some filename searches instead:
      • layout.antlers.html https://github.com/search?q=div+filename%3Alayout.antlers.html&type=Code
      • default.antlers.html https://github.com/search?q=div+filename%3Adefault.antlers.html&type=Code
      • page.antlers.html https://github.com/search?q=div+filename%3Apage.antlers.html&type=Code
  • I have included a real-world usage sample for all extensions added in this PR:
    • Sample source(s):
      • https://github.com/statamic/starter-kit-starters-creek/blob/master/resources/views/blog/index.antlers.html
      • https://github.com/studio1902/statamic-peak/blob/main/resources/views/layout.antlers.html
      • https://github.com/studio1902/statamic-peak/blob/main/resources/views/sitemap/sitemap.antlers.xml
      • kitchensink.antlers.html and kitchensink.antlers.php were written specifically for Linguist in this PR.
    • Sample license(s):
      • https://github.com/statamic/starter-kit-starters-creek/blob/master/LICENSE.md
      • https://github.com/studio1902/statamic-peak/blob/main/LICENSE
  • I have included a syntax highlighting grammar: https://github.com/Stillat/vscode-antlers-language-server
  • I have updated the heuristics to distinguish my language from others using the same extension. Not sure what's required here.

[lildude]

These samples are essentially all identical and don't appear to be real-world samples. Please replace them with real-world examples of the usage, ideally with different uses of the langauge as these files are used to train the classifier. You should really have added the samples your said you have in the OP 😉

You've also missed off adding the grammar license file which would have been downloaded when you ran script/add-grammar. Please add this file.

[jasonvarga]

These samples are essentially all identical and don't appear to be real-world samples.

I was basically copying from Blade https://github.com/github/linguist/blob/master/samples/Blade/hello.blade.php which was super simple.

You should really have added the samples your said you have in the OP

I thought that was a bit redundant when I was filling out the PR, now I understand what the samples are for. Hah, sorry!

You've also missed off adding the grammar license file which would have been downloaded when you ran script/add-grammar. Please add this file.

I committed whatever the command gave me. It didn't give me a license file at the time. I've now deleted it and re-run the command it looks like it added more stuff. Not sure why it didn't work right the first time.

[lildude]

Thanks. One nit: shouldn't samples/Antlers/sitemap.antlers.html have an .xml extension?

You're adding *.antlers.xml but haven't included a sample and this one is the only one that looks like XML 😁

[jasonvarga]

Yup! My bad. Done.

[lildude]

Ooof, I've just noticed where you've got your samples from. We can't accept these as the files are not covered by an open source licence… the repo even states it's all proprietary. Please replace all the samples with open source licensed files and update the OP to link to the spices and stated the relevant licenses.

[jasonvarga]

the repo even states it's all proprietary

Which repo are you looking at? https://github.com/studio1902/statamic-peak is MIT, and the other two don't have explicit LICENSE files.

[lildude]

Which repo are you looking at? https://github.com/studio1902/statamic-peak is MIT, and the other two don't have explicit LICENSE files.

This file:

https://github.com/statamic/statamic/blob/master/resources/views/layout.antlers.html

And this license:

https://github.com/statamic/cms/blob/master/CONTRIBUTING.md#statamic-isnt-foss

I missed the two covered by MIT. They can stay. The one without can't either though.

[jasonvarga]

Statamic the CMS itself isn't open source, but I'm not sure why the projects that use the templating language need to be open source?

[lildude]

... but I'm not sure why the projects that use the templating language need to be open source?

They don't, however files we include in Linguist need to be. We have that section in the template to ensure we don't infringe upon anyone's rights and accidentally include files we have not right to use.

IANAL but the fact that Statamic clearly state this:

Statamic is not Free Open Source Software. It is proprietary. Everything in this and our other repos on Github — including community-contributed code — is the property of Wilderborn.

... without any explicit indication of open source license usage for any of the files within their other repos says to me that we're potentially on risky legal ground—maybe not now, but potentially in the future—and I'm not prepared to accept that risk on behalf of GitHub, especially when you can easily replace this file with one that we know for sure is safe to include.

[jasonvarga]

Right on. I'm a maintainer of Statamic, so we'll just adjust the license (and/or at least that section of the CONTRIBUTING file).

The statamic/statamic repo is essentially an app template, so we don't want to include a license file otherwise people might accidentally license their projects incorrectly.

[jasonvarga]

Okay, we've removed the "and our other repos" part of the section you quoted from https://github.com/statamic/cms/blob/3.3/CONTRIBUTING.md#statamic-isnt-foss

Does this give you the all clear enough to use the samples now?

[lildude]

Does this give you the all clear enough to use the samples now?

Not really as the source repo still has no license. If it were your personal repo we’d accept you stating in the template we’re free to use the file as we wish.

There’s also the case of the other file without a license.

I’m not sure what the problem is with finding alternate liberally licensed files. You can easily search GitHub for these files.

[jasonvarga]

I've replaced the statamic/statamic file with one from an MIT licensed repo.

I've left a kitchensink.antlers.html sample, which doesn't exist in a repo, I created it just for this PR as a way to include all language features. Do you need me to remove it?

I've removed the PHP extension and the sample, as I can't find any MIT licensed ones through GitHub search.
If you're fine with the made up kitchensink sample, could I bring back the php extension with a kitchensink.antlers.php sample?

[lildude]

I've left a kitchensink.antlers.html sample, which doesn't exist in a repo, I created it just for this PR as a way to include all language features. Do you need me to remove it?

No, this is fine, and you can do the same for the PHP file. In both cases we prefer real-world usage samples as this is used to train the classifier.

[jasonvarga]

Ok, done!

[jasonvarga]

Hey @lildude thanks for the release. Syntax highlighting is working great!

Are we supposed to see Antlers appear in the language summary? At the moment I'm still just seeing HTML.

For example on https://github.com/studio1902/statamic-peak we see:

I know the majority in this repo are actually .antlers.html - not just .html files.

[jasonvarga]

Someone pointed out to me that it updates when the default branch is pushed to. And confirmed. The languages update just fine. Thanks again!

[joshuablum]

Hey @lildude,

Syntax highlighting and repo stats work great, thanks for that! 🚀

I found one potential bug/misconfiguration though:
When clicking on "Antlers" in the stats (or just plainly searching for it manually) the search always comes up empty. I tested it on multiple repos (e.g. #1, #2, #3)

Any idea why? Anything we can do?

[lildude]

Any idea why?

Yup. You're looking at Search which is completely independent of Linguist. It doesn't use Linguist. Instead it uses go-enry which pulls in the Linguist releases, however it tends to lag behind Linguist by a few weeks to months. It also requires our Search team to pull in the latest version as and when.

Anything we can do?

Nope. It's up to go-enry and our Search team now.

[joshuablum]

Alright, wasn't aware of this. (Although I already thought it might be something like this)

Thanks!