Could you describe how the package.json works?

I'm also interested in this - I thought it might be usable to create arbitrary pages but that doesn't appear to work. There also seem to be nuances to the order of entries that would be helpful if explained.

I tried to use partials in "package.json" to feed custom texts to a tag page, hacking the lack of a tag page feature. I could obviously pull a text-string from the package.json by calling a specific name {{>tagname}}, but couldn't figure how to nest mustache tags or manage to write a script so that it will get dynamic, not sure if it's even possible.

Aside from that, I use "locals" to store and quickly edit links and css properties, could be helpful if you have many different template views

What do you mean by a tag page? Like descriptions for each tag?

Firstly, sorry, the developer documentation sucks. I know it's bad. I feel bad that it's bad. I'm working on the template engine right now, it's a mess. Secondly, package.json is a bad name. I just copied the node.js convention.

What is package.json?

It's a configuration file for templates on Blot.

What do the properties in package.json mean?

• name – A string, the template's display name
• isPublic – A boolean, can be used to make the template visible to other Blot users
• enabled– A boolean, can be used to auto-install a locally-edited template
• locals– An object which contains template-specific variables used to render the pages on your site
• views – An object which contains configuration for specific files of the template

What is the locals object?

The properties of the locals object are local variables which are exposed to each page on your template when it is rendered. For example, consider line 6 of the Blog template's package.json file:

    "text_color": "#000000",

Because this local variable is present, you can use the mustache tag {{text_color}} in any of the Blog template's files, for example you could add this to entry.html:

<p>My site's text color is {{text_color}}.</p>

Which is rendered as:

<p>My site's text color is #000000.</p>

Now the above example is an illustration – in reality we use the {{text_color}} variable inside style.css on line 29:

body {
  color: {{text_color}};
    ...

Blot merges these template locals in with other properties to render pages on your site – you can view all this JSON if you append the querystring ?json=true to any of the pages on your site. For example:

See the JSON used to render the archives page of the blog template

How do locals and the template editor interact?

You've noticed that the template editor on Blot's dashboard also offers a point-and-click GUI to manipulate some of the properties in package.json. For example, if you create a new local under the locals object with the suffix _color, Blot's template editor will generate a point-and-click color picker for it on the template settings page. There are a variety of these inputs available, and you can see the source code responsible on GitHub. But ultimately, package.json is the source of truth.

What is the views object?

As package.json is the configuration for the template, the views property offers the opportunity to configure how Blot handles particular template files. For example, consider lines 55-61 of the Blog template's package.json file:

    "archives.html": {
      "url": "/archives",
      "partials": {
        "title": "Archives - {{{title}}}",
        "description": "All the entries posted on {{{title}}}"
      }
    },

These lines affect how Blot handles the template file archives.html. There are two properties:

• url a string which contains the URL path Blot should use when rendering the template file
• partials an object which contains partial templates available specifically to the archives.html file.

What is the partials object?

The partials object contains partials templates. This is a property of a specific template file, under the views object. For example, consider again lines 55-61 of the Blog template's package.json file:

    "archives.html": {
      "url": "/archives",
      "partials": {
        "title": "Archives - {{{title}}}",
        "description": "All the entries posted on {{{title}}}"
      }
    },

Because the partial template title is defined, you can do the following inside archives.html:

<p>What is the title of this page? It's {{> title}}</p>

You'll get the following output, assuming the title of your site is 'Example blog':

<p>What is the title of this page? It's Archives - Example Blog</p>

Partials are useful because they are rendered dynamically and can themselves contain template tags – references to other properties of your template, your posts, etc. Local on the other hand are rendered literally.

Anyway, I need to add all of this to the developer documentation. Please let me know if you have any questions about any of this

Chiming in here as I'm struggling to build my own theme based on an existing one.

It's not even clear to me what is the recommended way to fork a theme even is.

What I'd like to do is making magazine my own, removing any dependency to the original one, and edit it locally.

• I did do some adjustments through the online editor
• I can download the adjusted theme through the Share Button
• But the downloaded theme's package.json differs hugely from the one I see online
• What do these properties mean
  • "cloneFrom": "SITE:magazine"
  • "slug": "magazine",
  • "previewPath": "/",
• "id": "blog_2dbb9381293b439d95520360c3c108c4:magazine",
• "locals.demo_folder": "plants",
• Does cloneFrom": "SITE:magazine imply that partials my theme doesn't have are still inherited from SITE:magazine?
• Could I just copy the original package.json I see online and change the name, removing any ties to the clone source?
• Will a theme I move into my Templates folder still be editable through the web editor? Will editing either locally or only have any effects? (like making the other version inactive)
• Does the folder in which the theme lives has any significance or is only the name relevant? Or the slug?

PS: I'm trying to have get new local properties working as intended, and it seems like always the wrong value is being saved: local changes weren't picked up online. Then I changed them online, but they've been reverted again. I cannot figure out for the life of me how to have my local theme be the source of truth and have its changes conistently reflected online. This seem impossible at the moment and is driving me insane :(