new zine

build.zig

@@ -3,12 +3,29 @@ const zine = @import("zine");
 
 pub fn build(b: *std.Build) !void {
     zine.website(b, .{
-        .title = "Zine Static Site Generator",
+        .title = "Zine - Static Site Generator",
         .host_url = "https://zine-ssg.io",
         .layouts_dir_path = "layouts",
         .content_dir_path = "content",
-        .static_dir_path = "static",
-        .debug = true,
+        .assets_dir_path = "assets",
+        .static_assets = &.{
+            "CNAME",
+            // This asset is referenced in some inlined HTML in markdown
+            // which Zine is not yet able to analyze so as a temporary
+            // hack we mark it as a static asset.
+            "vscode-autoformatting.mp4",
+
+            // Fonts referenced in CSS files
+            "BebasNeue-Regular.ttf",
+            "Merriweather/Merriweather-Black.ttf",
+            "Merriweather/Merriweather-BlackItalic.ttf",
+            "Merriweather/Merriweather-Bold.ttf",
+            "Merriweather/Merriweather-BoldItalic.ttf",
+            "Merriweather/Merriweather-Italic.ttf",
+            "Merriweather/Merriweather-Light.ttf",
+            "Merriweather/Merriweather-LightItalic.ttf",
+            "Merriweather/Merriweather-Regular.ttf",
+        },
     });
 
     // This line creates a build step that generates an updated

build.zig.zon

@@ -3,8 +3,8 @@
     .version = "0.0.0",
     .dependencies = .{
         .zine = .{
-            .url = "git+https://github.com/kristoff-it/zine?ref=v0.2.0#e21b179b78de54ab48efe38d2378e87a56cb3542",
-            .hash = "1220781f118454bbc87d7efbd244b4d1ef029e76a6113ddf4752a6f3cd85879dbb3b",
+            .url = "git+https://github.com/kristoff-it/zine?ref=v0.3.0#2bba322c79547fc9ef75bac31fc3e328d7be0375",
+            .hash = "122082799c345efd9630f2f8c55c8a4093125fd10f0f8a7ecd7d768c06c831955483",
         },
     },
     .paths = .{"."},

content/documentation/assets.md

@@ -0,0 +1,139 @@
+---
+.title = "Assets",
+.date = @date("2020-07-06T00:00:00"),
+.author = "Sample Author",
+.draft = false,
+.layout = "documentation.shtml",
+.tags = [],
+--- 
+
+## Assets in Zine
+A Zine site can have 3 kinds of assets: **site**, **page**, and **build** assets.
+
+## Site Assets
+These assets are located under `assets_dir_path`. 
+
+The main way of accessing site assets is by using the following Scripty expression: `$site.asset('logo.png')`.
+
+Once you have an instance of an `Asset`, you can do three main things to it:
+
+- `$site.asset('logo.png').size()` to obtain its size in bytes
+- `$site.asset('logo.png').bytes()` to obtain its contents
+- `$site.asset('logo.png').link()` to obtain a link to it
+
+With `bytes` you can do clever things such as embedding the asset directly into the page itself, like so:
+
+***clever-and-cursed.html***
+```html
+<img src="$site.asset('foo.png').bytes().base64().prefix('data:image/png;base64,')">
+```
+
+While `link` in comparison seems very boring, it's actually both the preferred
+way in Zine to reference assets, and also its most clever asset feature.
+
+**Calling `link` on an asset will cause Zine to install it in the output directory.** 
+Conversely, accessing an asset *without* calling `link` on it will **not** cause it to be installed. 
+
+One example of where this makes sense is when you have a Ziggy (or JSON) document that you want to use to build a page, but that is not meant to be included the final output.
+
+***songs-list.html***
+```html
+<ul loop="$page.asset('songs.json').ziggy()">
+  <li var="$loop.it.get!('name')"></li>
+</ul>
+```
+
+**Note:** Zine uses [Ziggy](https://ziggy-lang.io) as its data serialization format of choice, but JSON documents happen to be a valid subset of Ziggy, so you can use them directly. 
+
+### Static Site Assets
+Some assets should be installed even if no layout or page refers to them. 
+
+For example `favicon.ico` might not be referenced, but browsers will automatically try to fetch it.
+
+Another example could be `.well-known` assets or files that might have special meaning for the hosting service that you're using. GitHub uses a file named `CNAME` to keep track of the custom domain configured for a given GitHub Pages website.
+
+One last example would be font files only referenced inside of CSS files, as Zine currently lacks the ability to inspect CSS files.
+
+To install assets unconditionally, list them in `static_assets` in your `build.zig`:
+
+***build.zig***
+```zig
+pub fn build(b: *std.Build) !void {
+    zine.website(b, .{
+        .title = "Zine - Static Site Generator",
+        .host_url = "https://zine-ssg.io",
+        .layouts_dir_path = "layouts",
+        .content_dir_path = "content",
+        .assets_dir_path = "assets",
+        .static_assets = &.{
+            // Used by GitHub Pages
+            "CNAME",
+            // This asset is referenced in some inlined HTML in Markdown
+            // which Zine is not yet able to analyze so as a temporary
+            // hack we mark it as a static asset.
+            "vscode-autoformatting.mp4",
+
+            // Font referenced in CSS files
+            "BebasNeue-Regular.ttf",
+        },
+    });
+} 
+```
+
+## Page Assets
+Page assets are the same as site assets, but are located inside of `content_dir_path`, next to the page that references them.
+
+If you have an asset that is specific to only a single page of your website, you can conveniently place it next to it inside the content directory, but beware of respecting the expected content structure.
+
+***shell***
+```
+content
+├── blog
+│   ├── first-post.md
+│   └── index.md
+└── index.md
+```
+
+In Zine, pages that are not named `index.md` (i.e. pages that don't define a section) must keep their assets under a directory with the same name.
+
+***shell***
+```
+content
+├── blog
+│   ├── first-post
+│   │   └── C.png
+│   ├── first-post.md
+│   ├── B.png
+│   └── index.md
+├── A.png
+└── index.md
+```
+
+- `A.png` belongs to `content/index.md`
+- `B.png` belongs to `content/blog/index.md`
+- `C.png` belongs to `content/blog/first-post.md`
+
+Note how `C.png` lives under `content/blog/first-post/` because it belongs to a non-section page.
+
+Accessing a page asset can be done using `$page.asset('C.png')`.
+Like all assets, they must be `link`ed to be installed in the output directory.
+
+#### Note 
+Inside of Markdown files you can use standard syntax `![](C.png)` and everything will work as expected (Zine will search for the asset in the right directory and will install it in the output directory). 
+
+That said, Markdown processing in Zine has not yet reached its final form so expect news in the near future.
+
+## Build Assets
+If you have artifacts built using the Zig build system, you can use them in Zine by setting `build_assets` in your `build.zig`.
+
+Accessing a build asset can be done using `$build.asset('foo')`.
+Like all assets, they must be `link`ed to be installed in the output directory.
+
+See the doc comments for `zine.BuildAsset` for more info.
+
+## Next Steps
+Make sure to familiarize yourself with the Scripty Reference Documentation in order to know what operations are available for assets and other kinds of data.
+
+[Read the Scripty Reference Documentation](/documentation/scripty/)
+
+

content/documentation/i18n.md

@@ -1,13 +1,13 @@
 
 ---
-.title = "Documentation",
+.title = "Multilingual Websites",
 .date = @date("2020-07-06T00:00:00"),
 .author = "Sample Author",
 .draft = false,
 .layout = "documentation.shtml",
 .tags = [],
 --- 
-## Multilingual Websites 
+## Creating Multilingual Websites 
 
 To create a multilingual website, use `addMultilingualWebsite` in your
 `build.zig`, like in the following example.
@@ -17,23 +17,23 @@ const std = @import("std");
 const zine = @import("zine");
 
 pub fn build(b: *std.Build) !void {
-    try zine.addMultilingualWebsite(b, .{
+    zine.multilingualWebsite(b, .{
         .host_url = "https://kristoff.it",
         .layouts_dir_path = "layouts",
-        .static_dir_path = "static",
+        .assets_dir_path = "assets",
         .i18n_dir_path = "i18n",
-        .variants = &.{
+        .localized_variants = &.{
             .{
-                .locale_code = "en_US",
+                .locale_code = "en-US",
                 .output_prefix_override = "",
                 .title = "Loris Cro's Blog",
-                .content_dir_path = "content",
+                .content_dir_path = "content/en-US",
             },
 
             .{
-                .locale_code = "it_IT",
+                .locale_code = "it-IT",
                 .title = "Loris 🤌 Cro's 🤌 Blog",
-                .content_dir_path = "content_it",
+                .content_dir_path = "content/it-IT",
             },
         },
     });
@@ -43,7 +43,7 @@ pub fn build(b: *std.Build) !void {
 Each variant can define the following fields:
 
 #### `locale_code`
-A `language_NATION` string, e.g. `en_US`, `en_UK`, `it_IT`, `ja_JP`.
+A `language_NATION` string, e.g. `en-US`, `en-UK`, `it-IT`, `ja-JP`.
 
 #### `title`
 Site title for this variant.
@@ -55,8 +55,8 @@ Content directory with translated versions of your content.
 The default assumption in Zine is that all your localized variants will be
 deployed on the same host, with each translation made available under a `locale_code` prefix:
 
-- `https://site.com/en_US/about/`
-- `https://site.com/it_IT/about/`
+- `https://site.com/en-US/about/`
+- `https://site.com/it-IT/about/`
 
 Some users might want instead to serve each translation from a different hostname:
 
@@ -80,7 +80,7 @@ For example by setting `ouptput_prefix_override` to empty string in `en_US` this
 is the resulting site layout:
 
 - `https://site.com/about/`
-- `https://site.com/it_IT/about/`
+- `https://site.com/it-IT/about/`
 
 
 Here's a table with more examples:
@@ -108,7 +108,7 @@ Here's a table with more examples:
 
 ### The i18n Directory
 When creating a multilingual website, the assumption is that the same layouts
-and static content will be reused across all localized variants, while the 
+and site assets will be reused across all localized variants, while the 
 content folder will vary for each. 
 
 Varying the content folder will allow you to create different translations of 
@@ -124,13 +124,13 @@ Localized variants and translation files are matched using the `locale_code` fie
 **`$tree i18n`**
 ```
 i18n
-├── en_US.ziggy
-└── it_IT.ziggy
+├── en-US.ziggy
+└── it-IT.ziggy
 ```
 
 Each file contains a Ziggy map that can then be accessed from your layouts as `$i18n`.
 
-**`$cat i18n/it_IT.ziggy`**
+**`$cat i18n/it-IT.ziggy`**
 ```ziggy
 {
  "back2top": "Ritorna in cima",
@@ -170,26 +170,25 @@ Consider the following directory structure:
 
 ```
 content
-├── about.md
-├── docs
-│   └── index.md
-└── index.md
-content_it
-├── about.md
-├── pasta.md
-├── docs.md
-└── index.md
+├── en-US
+│   ├── about.md
+│   ├── docs
+│   │   └── index.md
+│   └── index.md
+└── it-IT
+    ├── about.md
+    ├── pasta.md
+    ├── docs.md
+    └── index.md
 ```
 
-- `index.md` and `about.md` are matched because they have the same
-path (respective to the each content directory). 
+- `index.md` and `about.md` are both respectively matched with their corresponding translation because they have the same path (e.g. `en-US/about.md`, `it-IT/about.md`). 
 - `pasta.md` is not matched with any other page because it has a unique relative 
 path.
 - `docs.md` is not matched with any other page because, even though the resulting
 url path would be the same as `docs/index.md`, the *content path* is different.
 
-That said, it is possible to match any page with any other by defining `translation_key` in
-the Ziggy frontmatter of each page.
+That said, it is possible to match any page with any other by setting `translation_key` in the Ziggy frontmatter of each page.
 
 This last way of matching pages is meant to be used when URL paths are also translated,
 for example:
@@ -202,5 +201,5 @@ The following frontmatter key must be set in both "contact us" pages:
 .translation_key = "contact form"
 ```
 
-The value can be any string value, as long as it is unique per each localized variant.
+The translation key can be any string value, as long as it is unique per each localized variant.