diff options
| author | Raghuram Subramani <raghus2247@gmail.com> | 2025-09-04 21:51:39 -0400 |
|---|---|---|
| committer | Raghuram Subramani <raghus2247@gmail.com> | 2025-09-04 21:51:39 -0400 |
| commit | f09dd259a4d31073e1aed712b3cd9ce31f88c991 (patch) | |
| tree | b65c258d953a95fd6dd8aed613e67d071d17d3e7 | |
| parent | cf2d094a31523ccc20d85c05954809051e77a9a0 (diff) | |
README: refactor & add explanatory text
| -rw-r--r-- | README.md | 47 |
1 files changed, 40 insertions, 7 deletions
@@ -3,6 +3,8 @@ An incredibly opinionated, hackable, minimal Static Site Generator. > See https://github.com/compromyse/compromyse.xyz for an example site. +The point of this project was very simple; I was in the mood to write a static site generator. I figured I'd start with the most basic feature, "includes," and it ended up expanding to supporting nested for loops. All I required was a simple static site generator that doesn't overdo it. Besides, who doesn't like writing a lexer and generation engine in C. + ### Compilation & Usage ```sh # REQUIREMENTS: CMake, Git, GCC/Clang, GNUMake/Ninja @@ -22,6 +24,13 @@ Usage: ./msg [-h] [-w] [-v] [-o <output>] <directory> ``` ### Site Structure + +The site structure is actually fairly simple. `/config.cfg` describes the static directories, in this case only "assets." It could be any number of files & folders, though. + +Since I wanted to manually define all the resources (pages), I added a list `resources` in `/config.cfg` to encapsulate the collection of web pages. This was largely inspired by C build systems, where each C file is listed in an array of filenames (See [CMakeLists.txt for msg](https://github.com/compromyse/msg/blob/main/CMakeLists.txt#L6)). + +The partials though, must be placed in the hardcoded `/partials` folder. They may, however, be placed in subdirectories therein. I didn't see much of a point allowing multiple partial directories (and likewise with templates). + ```sh . ├── assets @@ -40,6 +49,8 @@ Usage: ./msg [-h] [-w] [-v] [-o <output>] <directory> #### Includes - include files from `/partials` +This directive simply fetches the file content of the operand, in this case `/partials/navbar.html` and replaces the caller's body with it. + ```html <!-- index.html --> <html> @@ -52,6 +63,8 @@ Usage: ./msg [-h] [-w] [-v] [-o <output>] <directory> #### Contentfor - define content for templates +In this particular case, the template must have `content` directives, whose bodies are defined using `contentfor` directives. The example is fairly self-explanatory. + ```html <!-- templates/base.html --> <html> @@ -72,9 +85,13 @@ Usage: ./msg [-h] [-w] [-v] [-o <output>] <directory> ``` #### Eachdo - iterate over resources + +These are actually fairly complicated; EACHDOs iterate over some array of strings or nested-configs. + +In the first example, the source being iterated over is the current page's `links` config. For each link, it's simply printing the respective href and label. + ```html <!-- projects/xyz.html --> -title = XYZ links = [ href = https://example.org label = abc @@ -86,17 +103,29 @@ links = [ <h1>XYZ!</h1> -<!-- index.html --> -{{ eachdo resources.projects }} -<p>{{ put title }}</p> -{{ endeachdo }} - {{ eachdo page.links }} <p>{{ put href }}</p> <p>{{ put label }}</p> {{ endeachdo }} ``` +With this example, `/index.html` is iterating over the `projects` resource (just the /projects directory excluding index.html). For each of the pages, it's simply printing the page's title in a paragraph tag. + +```html +<!-- projects/xyz.html --> +title = XYZ +--- + +<h1>XYZ!</h1> + +<!-- index.html --> +{{ eachdo resources.projects }} +<p>{{ put title }}</p> +{{ endeachdo }} +``` + +This example is much like the first one, but instead of the links being defined in the current page, it's defined in `/config.cfg`. + ```html <!-- config.cfg --> links = [ @@ -113,10 +142,14 @@ links = [ {{ endeachdo }} ``` -#### Template - specify template for page +#### Page Options - specify template, priority in EACHDO iterations, etc. + +Some page options can be defined in a page's config, such as the template that needs to be used, and the priority of this particular page when the resource containing the page (projects) is iterated over. + ```html <!-- projects/xyz.html --> template = base_tailwind.html +priority = 100 --- <h1 class="p-2">XYZ!</h1> |