glyph-zero

The origin template for all glyph powered blogs.

Project Structure

├── config.toml                 # contains all settings for glyph
├── docs                        # the export folder for glyph, used by Github pages
├── LICENSE
├── Makefile                    # commands for cleaning and building
├── README.md
└── themes                      # folder containing all themes
    └── default                 # the default theme used by glyph
        ├── config.toml         # settings file for a theme
        ├── index.mustache      # template for the index page
        ├── issue.mustache      # template for the issue page (mandatory)
        ├── layout.mustache     # template for the site layout (frame for all other templates)
        ├── README.md           # contains info about contributors
        ├── style.css           # \
        ├── tachyons.css        #  > custom styling css
        └── tachyons.min.css    # /
    └── .. more themes

Setup

Install glyph. Make sure it's in your path.
Fork this repository.
Rename your new repository to e.g. "blog". Your Github pages address will be https://<user>.github.io/<repo>.
Enable Github pages via the repository settings. Make sure you choose master branch /docs folder. This is currently the only option that is compatible with glyph.
Clone your repository to your hard disk.
Edit the site's config.toml and the theme's config.toml. The files are documented and should be easy to understand.

Congratulations you set up everything. This step was a one time thing. Now build your blog for the first time. Instructions are in the Usage section.

Usage

Build the site at any time by running make blog or glyph directly. Remember that glyph needs to be in your path. With make clean you can clean all exported files (in the docs folder). Usually you won't need to do this.

After building your site don't forget to add your docs folder to git and commit & push to github.

If you just built your blog for the first time go visit https://<user>.github.io/<repo> and after a short while you should see the raw skeleton of your blog without any posts (we will call them issues from now on).

Writing issues is as simple as writing new issues in your Github repository. You just use the Github markdown editor directly or pre-write them locally and copy & paste them into a Github issue. When you are finished you run the build step locally and commit/push, done. Your new issue is live on your blog within about a minute.

Some important points to keep in mind:

Summaries: The first paragraph of your issue is treated as summary for the blog post. This summary is shown in the index list of the blog.
Drafts: You can create a draft by attaching the draft label to the issue. Issues with a draft label are not exported to HTML. You may at any point remove the label and rebuild with glyph to export or readd the label and rebuild to unpublish again.
Deletions: If you want to delete an issue, just close it and rebuild with glyph. Closed issues will not be exported to HTML.

Always remember to run make clean if you want to delete old files from the source tree. This may be useful after deletion or un-publishing. E.g. if you deleted(closed) an issue Glyph will not export it anymore but the file is still there. Running make clean and then make blog will only keep the currently valid files.

Creating Themes & Customizing

You can just use the default theme provided by glyph-zero. How it looks can be seen on my personal blog. If you don't like it or just want something entirely different, you should just create a new theme. The easiest way to do this is by copying the default theme and adjusting it to your needs.

Every theme consists of a directory in the themes folder and a few mandatory files (see Project Structure above). The name of the directory is the theme's name. Files that must exist for every theme are:

README.md: this file should contain the creator(s) and contributors of the theme plus any other information that is needed.
config.toml: this file contains theme specific settings. Have a look at the config.toml of the default theme for a better understanding.
issue.mustache: the only template file that is mandatory is the issue template. It determines how a single issue will look after rendering .

glyph uses the mustache templating system to insert data into the final HTML pages. glyph lets you access the following data in your templates:

Exports from config.toml

The data here is completely specified in config.toml and exported to the template rendering process by glyph.

[Site]
    Title       = string, # site/blog title
    Author      = string, # author's name
    OneLineDesc = string, # short description of the site's content
    Twitter     = string, # twitter handle (without @, e.g. john_doe)
    Mail        = string, # mail address for contact (public)
    Theme       = string  # theme name (assumes default if not specified)

[Repository]
    Users   =   []string, # all users that can author blog posts, "owner" must be the first user
    Name    =   string    # name of the repository

    # First user and repo name are integral parts of your repository URL:
    # https://github.com/<user>/<name>
    # and your Github pages URL:
    # https://<user>.github.io/<name>

    # Usually you will only provide 1 user.

Custom = dict[string]:generic # a dictionary that allows definition of custom key/value pairs

The Custom attribute allows to export custom data from the config file to the template rendering process. There is a simple example included in config.toml.

Issue Exports

The export of issues has two possible cases. For the issue.mustache template only the current Issue is exported:

Issue = Issue object # the issue that is rendered

whereas for all other templates all issues are exported:

Issues = []Issue # array of all issues

In any case a single Issue is defined as follows:

[Issue]
    Number      = int           # Github issue number (not id)
    Title       = string        # original issue title
    Link        = string        # slugified title
    Content     = string        # content of the issue in HTML
    Summary     = string        # first paragraph of Github Issue in HTML
    Labels      = []string      # all labels assigned to the issue on Github
    GithubLink  = string        # direct link to the issue (and to the comments)
    Created     = time.Time     # time of creation, type from Go standard library

Theme Exports

These exports all come from the theme config file config.toml in the theme folder.

[Theme]
    Name            = string                # name of the template, must match directory name
    IndexTemplate   = Template              # the template used to render index.html and an index page for each label
    IssueTemplate   = Template              # the template used to render a single issue
    OtherTemplates  = []Template            # the rest of the templates used in the theme
    Custom          = dict[string]:generic  # a dictionary that allows definition of custom key/value pairs

A single template is structured as follows:

    Source = string     # the source template file
    Layout = string     # the layout template file (optional)
                        # a layout acts like a frame for other templates
    Target = string     # the name of the target html file

Utility Exports

Today = time.Time type from the Go standard library   # exports the time of building.

The Go time.Time type is documented here.

5k3105/blog