|
1 | 1 | # Homepage |
2 | 2 |
|
3 | | -## Directory structure |
| 3 | +Sources for my personal website. The build system had more revisions than the entire side but is currently using the [zola](https://www.getzola.org) template engine. |
4 | 4 |
|
5 | | -### `builder` |
6 | | - |
7 | | -Source code of a program that can be run in the root directory to build a static |
8 | | -website in a new the `out` directory. |
9 | | - |
10 | | -#### Usage: |
11 | | - |
12 | | -- `builder assemble`: merge custom files into a standard compliant website |
13 | | -- `builder pack`: `assemble` and include css directly in html files, tree-shake unused classes and attributes |
14 | | -- `builder compile`: `pack` and minify js and css to reduce size |
15 | | - |
16 | | -### `static` |
17 | | - |
18 | | -Static HTML documents, CSS styles and assets that will be copied in that |
19 | | -structure to the *assemble*d website. |
20 | | - |
21 | | - |
22 | | -### `components` |
23 | | - |
24 | | -HTML snippets that may contain variables and other components of the format |
25 | | -`{{ <id> }}`, where id must be provided during the *assemble*-stage. |
26 | | - |
27 | | -### `templates` |
28 | | - |
29 | | -HTML pages containing markup of the format `{{ <id> }}` where id can be the name |
30 | | -of a component or a custom variable. In the *assemble*-stage first component |
31 | | -names get resolved, followed by variable names. Where variable names come from |
32 | | -is specified in the `builder` code. |
33 | | - |
34 | | -### `pages` |
35 | | - |
36 | | -This is the main directory responsible for building the site. It contains yml |
37 | | -files and other data required to build the site. Each yaml-file represents one |
38 | | -generated html file at the yaml-files relative path pages dir with a similar |
39 | | -name. |
40 | | - |
41 | | -Each yaml file contains a `template:` key specifying the file under the |
42 | | -"templates" directory. Example: `template: base-page.html` |
43 | | - |
44 | | -It can also contain build steps under the `steps:` key. Each step defines |
45 | | -variable names and their replacement. Variable names from the last name are |
46 | | -still present if they weren't overridden. |
47 | | - |
48 | | -*Variable* values can be simple Strings or a map that must contain a `type` key |
49 | | -and a `value` or a `path` key. A value is another *variable* value (can be |
50 | | -nested). Paths are relative to the pages dir and are read as strings. |
51 | | - |
52 | | -```yml |
53 | | -steps: |
54 | | - - "Setup blog template": |
55 | | - title: Hacking window movement |
56 | | - content: "{{ components/blog-entry }}" |
57 | | - - "Fill data": |
58 | | - description: A short tale on the joy of microprojects. |
59 | | - timestamp: |
60 | | - type: unixTimestamp |
61 | | - value: 1706394048 |
62 | | - content: |
63 | | - type: Md |
64 | | - path: blog/kinetic-windows.blog |
65 | | -``` |
66 | | -
|
67 | | -At the end of steps there must be no unresolved variables. |
68 | | -
|
69 | | -#### Available types |
70 | | -
|
71 | | -| *type* | Description | |
72 | | -|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
73 | | -| text | Raw text to directly insert. When `path` is specfied a file is read. | |
74 | | -| unixTimestamp | Unix timestamp in seconds. Creates a `<time>` HTML element. | |
75 | | -| Md | Text in markdown format. | |
76 | | -| index | Requires a directory in the `path` argument. Performs the specified `steps` in every .yml file (except index.yml) in the specified directory on any *component* specified in a custom `itemTemplate` key. Additionally provides a `link` variable that links to the article generated for that item. | |
77 | | - |
78 | | -### Files |
79 | | - |
80 | | -- `page-modifications`: Automatically generated: required in CWD to build the sitemap. |
81 | | - |
82 | | -## CSS |
83 | | - |
84 | | -In general CSS is considered as introducing too much complexity and should be |
85 | | -reduced as far as possible. When using CSS is appropriate it is split between |
86 | | -the `layout.css` and `style.css` files with distinct responsibility. |
87 | | - |
88 | | -The complexity of CSS used for layout should be reduced as far as possible. |
89 | | -CSS used for styling must not shift element position on load, but may be used to |
90 | | -provide colors, fonts and responsiveness. |
91 | | - |
92 | | -Required CSS classes are automatically resolved and no manual imports are |
93 | | -required. Compilation will fail if names collide or couldn't be resolved. |
94 | | - |
95 | | -## Assembly |
96 | | - |
97 | | -TODO: rework section |
98 | | -Posts in `posts/*.blog` insert a blog-post to `{{ latest }}` in the blog |
99 | | -component and a blog-entry component in the base-page template under the `/blog/` |
100 | | -URL path. |
101 | | - |
102 | | -- `components/blog-post.html` contains the "title", "description" date "date" variables read from `posts/*.blog`. |
103 | | -- `components/blog-entry.html` contains the "title", "description", formated "timestamp" and "content" variables read from `posts/*.blog`. |
104 | | - |
105 | | -The `home.html` and `blog.html` components get inserted in a base-page template |
106 | | -and *assemble*d to the `/index.html` and `/blog/index.html` paths respectively |
107 | | - |
108 | | - |
109 | | -# TODO: |
110 | | - |
111 | | -### After: |
| 5 | +## TODO: |
112 | 6 |
|
113 | 7 | - https://developers.google.com/search/docs/appearance/structured-data |
114 | | -- rss feed |
115 | | -- pack |
116 | | -- compile |
0 commit comments