readme

vite
----

A fast (this time, actually) and minimal static site generator.

INSTALLING

    go install git.icyphox.sh/vite@latest


USAGE

    usage: vite [options]

    A simple and minimal static site generator.

    options:
        init PATH                   create vite project at PATH
        build                       builds the current project
        new PATH                    create a new markdown post
        serve [HOST:PORT]           serves the 'build' directory


CONFIG

The configuration is unmarshalled from a config.yaml file, into the
below struct:

    type ConfigYaml struct {
        Title           string `yaml:"title"`
        Desc            string `yaml:"description"`
        DefaultTemplate string `yaml:"-"`
        Author          struct {
            Name  string `yaml:"name"`
            Email string `yaml:"email"`
        } `yaml:"author"`
        URL       string   `yaml:"url"`
        PreBuild  []string `yaml:"preBuild"`
        PostBuild []string `yaml:"postBuild"`
    }

Example config: https://git.icyphox.sh/site/tree/config.yaml


SYNTAX HIGHLIGHTING

vite uses chroma (https://github.com/alecthomas/chroma) for syntax
highlighting. Note that CSS is not provided, and will have to be
included by the user in the templates. A sample style can be generated
by running:

    go run contrib/style.go > syntax.css


SPECIAL META DIRECTIVES

• draft: sets a post to draft (boolean) and will only be rendered if
  the build command is run with the --drafts flag.
• atroot: sets a post to be also rendered at the root of the site.


TEMPLATING

Non-index templates have access to the below objects:
• Cfg: object of ConfigYaml
• Meta: map[string]string of the page's frontmatter metadata
• Body: Contains the HTML


Index templates have access to everything above, and an Extra object,
which is a slice of types.Post containing Body and Meta. This is useful
for iterating through to generate an index page.
Example: https://git.icyphox.sh/site/tree/templates/index.html

Templates are written as standard Go templates (ref:
https://godocs.io/text/template), and can be loaded recursively.
Consider the below template structure:

    templates/
    |-- blog.html
    |-- index.html
    |-- project/
        |-- index.html
        `-- project.html

The templates under project/ are referenced as project/index.html.
This deserves mention because Go templates don't recurse into
subdirectories by default (template.ParseGlob uses filepath.Glob, and
doesn't support deep-matching, i.e. **).

vite also supports templating generic YAML files. Take for instance,
pages/reading.yaml (https://git.icyphox.sh/site/blob/master/pages/reading.yaml):

    meta:
      template: reading.html
      title: reading
      subtitle: Tracking my reading.
      description: I use this page to track my reading.

    books:
      - 2024:
        - name: Dune Messiah
          link: https://en.wikipedia.org/wiki/Dune_Messiah
          author: Frank Herbert
          status: now reading
      - 2023:
        - name: Dune
          link: https://en.wikipedia.org/wiki/Dune_(novel)
          author: Frank Herbert
          status: finished

vite will look for a 'meta' key in the YAML file, and use the 'template'
specified to render the page. The rest of the YAML file is available to
you in the template as a map[string]interface{} called Yaml.


More templating examples can be found at:
https://git.icyphox.sh/site/tree/templates


FEEDS

Atom feeds are generated for all directories under pages/. So
pages/foo will have a Atom feed at build/foo/feed.xml.


FILE TREE

    .
    |-- build/
    |-- config.yaml
    |-- pages/
    |-- static/
    |-- templates/

The entire static/ directory gets copied over to build/, and can be
used to reference static assets -- css, images, etc. pages/ supports
only nesting one directory deep; for example: pages/blog/*.md will
render, but pages/blog/foo/*.md will not.


BUGS

Or rather, (undocumented) features. There's probably a couple. If you are
actually using this, feel free to reach out and I can try to help.