Theme / Theme structure

Theme structure

Here is an example of the file structure of a Typlog theme:

.
├── /css
|   └── app.css
├── README.md
├── home.j2     [required]
├── list.j2     [required]
├── item.j2     [required]
├── lang.j2
├── tag.j2
├── author.j2
└── theme.json  [required]

Templates

Three templates are required: home.j2, list.j2, and item.j2. All other templates are optional.

home.j2

This template is for rendering the home page, which is /.

list.j2

This is the default template for rendering list pages. It is used if your theme does not have a lang.j2, tag.j2, or author.j2 template.

lang.j2

This is an optional template for rendering items in the given language. For example, /en/, /zh-hans/.

tag.j2

This is an optional template for tagged posts and episodes.

author.j2

This is an optional template for rendering a certain author's posts and episodes.

item.j2

This is the default template for rendering one single post, episode, or page.

theme.json

This file is required when submiting your theme into Typlog theme repository. It defines the information of your theme. Here is an example:

{
  "name": "akasaka",
  "name#ja": "赤坂",
  "name#zh": "赤坂",
  "author": "Typlog",
  "repo": "typlog/akasaka",
  "version": "0.1.0",
  "templates": [
    "home.j2",
    "item.j2",
    "list.j2",
    "lang.j2"
  ],
  "tags": ["doc"],
  "images": [
    "https://user-images.githubusercontent.com/290496/141270232-8ae07471-526a-4280-9189-2e421bb0bdea.png"
  ]
}

name

This field is required. The English name of your theme. You can also add name#ja for Japanese name, and name#zh for Chinese name.

author

This field is required. Your name if you are the author.

repo

This field is required. The GitHub repository name of the theme.

version

This field is required. Current version of the theme. You need to add push the matching git tag to GitHub.

images

This field is required. An array of previewing images of your theme.

templates

This field is optional. If the theme contains optional templates, it is required to list all the templates with templates key.

site

This field is optional. Specify the site for previewing:

{
  "site": {
    "id": 123,
    "name": "My Theme"
  }
}

README.md

A markdown formatted text file to introduce the theme. If there are some specified settings the theme required, you can write them in this README.md file.

Nov 12, 2021