Organization

See Content Organization.

.
└── content
    ├── posts
    |   ├── firstpost.md  // <- https://xxx.github.io/posts/firstpost/
    |   ├── happy
    |   |   └── ness.md   // <- https://xxx.github.io/posts/happy/ness/
    |   └── secondpost.md // <- https://xxx.github.io/posts/secondpost/
    └── docs
        ├── first.md      // <- https://xxx.github.io/docs/first/
        └── second.md     // <- https://xxx.github.io/docs/second/

If you want to do some basic settings for your blog, you can add your own header definition.

Fields

Basic Header Fields

+++
title = "title"
description = "write your description"
author = "rltea"
slug = "define_your_slug"
draft = false
date = "2024-06-25"
lastmod = "2024-06-28"
url = "/posts/new_blog"
tags = ["new", "blog"]
include_tags = ["test", "old"]
exclude_tags = ["sloth"]
categories = ["new", "blog"]
include_categories = ["old", "test"]
exclude_categories = ["sloth"]
status = "update"
+++

blog content

As shown in above, between the two “+++” lines, there are the header information of one markdown blog file which in toml format. You can also define the header in yaml format enclosed in “---”, or write directly in json format.

It is worth noting that these header fields can be omitted, because our blog-processor will process the “raw” markdown file and add a extra header to it.

Now we will introduce the function of each field:

  • title: The title of this blog, the default value is the filename.

  • description: The description of the content.

  • author: The author of this blog.

  • date: The created date of this blog, but you can change it any you want.

  • slug: The token to appear in the tail of the URL.

  • url: The full path to the content from the web root.

  • draft: If set this as true, this file will not generate a web page, the default value is false.

  • lastmod: Last modified time.

  • tags: Tag list. If this value is set, it will overwrite the tags defined in the directory-level header information.

  • include_tags: A list of additional tags. This value will be merged with tags, i.e., the union is taken.

  • exclude_tags: A list of tags to exclude. This value will be subtracted from tags.

  • categories: Carerogy list. If this value is set, it will overwrite the categories defined in the directory-level header information.

  • include_categories: A list of additional categories. This value will be merged with categories, i.e., the union is taken.

  • exclude_categories: A list of categories to exclude. This value will be subtracted from categories.

  • status: This value is mainly used to maintain whether the blog file has been modified. As long as this value is different from the last setting, the blog file will be weakly updated when submitted (updated content, local image files with the same name are not generated repeatedly). When the value is set to “update”, the blog file will be strongly updated when submitted (the content and the associated local image files are resubmitted).

Other Fields

  • type: The type of this blog, if the value is “special”, this blog will not be listed.

  • cover: The cover of this blog.

  • placeholder: Used for search box.

  • layout: Used for special pages.

Directory-level Header File

We support directory-level header files. Assume that you create the following .headers.toml file in the content/posts/section directory. When all markdown files in this directory (excluding subdirectories) are processed, the header information defined in this file will be added. The header field in the markdown takes precedence over the header field at the directory level.

tags = ["test", "old"]
categories = ["test", "old"]

Content

See markdown guide.