fast and minimal static site generator
anirudh.fi
ssg
1vite
2----
3
4A fast (this time, actually) and minimal static site generator.
5
6INSTALLING
7
8 go install tangled.sh/icyphox.sh/vite@latest
9
10
11USAGE
12
13 usage: vite [options]
14
15 A simple and minimal static site generator.
16
17 options:
18 init PATH create vite project at PATH
19 build builds the current project
20 new PATH create a new markdown post
21 serve [HOST:PORT] serves the 'build' directory
22
23
24CONFIG
25
26The configuration is unmarshalled from a config.yaml file, into the
27below struct:
28
29 type ConfigYaml struct {
30 Title string `yaml:"title"`
31 Desc string `yaml:"description"`
32 DefaultTemplate string `yaml:"-"`
33 Author struct {
34 Name string `yaml:"name"`
35 Email string `yaml:"email"`
36 } `yaml:"author"`
37 URL string `yaml:"url"`
38 PreBuild []string `yaml:"preBuild"`
39 PostBuild []string `yaml:"postBuild"`
40 }
41
42Example config: https://tangled.sh/@icyphox.sh/site/blob/master/config.yaml
43
44
45SYNTAX HIGHLIGHTING
46
47vite uses chroma (https://github.com/alecthomas/chroma) for syntax
48highlighting. Note that CSS is not provided, and will have to be
49included by the user in the templates. A sample style can be generated
50by running:
51
52 go run contrib/style.go > syntax.css
53
54
55SPECIAL META DIRECTIVES
56
57• draft: sets a post to draft (boolean) and will only be rendered if
58 the build command is run with the --drafts flag.
59• atroot: sets a post to be also rendered at the root of the site.
60
61
62TEMPLATING
63
64Non-index templates have access to the below objects:
65• Cfg: object of ConfigYaml
66• Meta: map[string]string of the page's frontmatter metadata
67• Body: Contains the HTML
68
69
70Index templates have access to everything above, and an Extra object,
71which is a slice of types.Post containing Body and Meta. This is useful
72for iterating through to generate an index page.
73Example: https://git.icyphox.sh/site/tree/templates/index.html
74
75Templates are written as standard Go templates (ref:
76https://godocs.io/text/template), and can be loaded recursively.
77Consider the below template structure:
78
79 templates/
80 |-- blog.html
81 |-- index.html
82 |-- project/
83 |-- index.html
84 `-- project.html
85
86The templates under project/ are referenced as project/index.html.
87This deserves mention because Go templates don't recurse into
88subdirectories by default (template.ParseGlob uses filepath.Glob, and
89doesn't support deep-matching, i.e. **).
90
91vite also supports templating generic YAML files. Take for instance,
92pages/reading.yaml (https://git.icyphox.sh/site/blob/master/pages/reading.yaml):
93
94 meta:
95 template: reading.html
96 title: reading
97 subtitle: Tracking my reading.
98 description: I use this page to track my reading.
99
100 books:
101 - 2024:
102 - name: Dune Messiah
103 link: https://en.wikipedia.org/wiki/Dune_Messiah
104 author: Frank Herbert
105 status: now reading
106 - 2023:
107 - name: Dune
108 link: https://en.wikipedia.org/wiki/Dune_(novel)
109 author: Frank Herbert
110 status: finished
111
112vite will look for a 'meta' key in the YAML file, and use the 'template'
113specified to render the page. The rest of the YAML file is available to
114you in the template as a map[string]interface{} called Yaml.
115
116
117More templating examples can be found at:
118https://git.icyphox.sh/site/tree/templates
119
120
121FEEDS
122
123Atom feeds are generated for all directories under pages/. So
124pages/foo will have a Atom feed at build/foo/feed.xml.
125
126
127FILE TREE
128
129 .
130 |-- build/
131 |-- config.yaml
132 |-- pages/
133 |-- static/
134 |-- templates/
135
136The entire static/ directory gets copied over to build/, and can be
137used to reference static assets -- css, images, etc. pages/ supports
138only nesting one directory deep; for example: pages/blog/*.md will
139render, but pages/blog/foo/*.md will not.
140
141
142BUGS
143
144Or rather, (undocumented) features. There's probably a couple. If you are
145actually using this, feel free to reach out and I can try to help.