Use public dir for clarity and to allow static files on root (#368)

blog/content/docs/advanced.adoc

@@ -340,7 +340,6 @@ TIP: By default, url will be rendered as relative from the site root. You can al
 
 Sometimes, you want to create a link for a page without holding the variable, in this case, you can use `site.url(relativePath)` which will be automatically resolved from the site root path.
 
-
 == Site Configuration
 |}
 

blog/content/docs/basics.adoc

@@ -27,6 +27,12 @@ This header contains yaml data used to configure many things such as:
 * Content generation
 * Pagination
 
+== Content
+
+The `content/` directory contains the index page and all the pages and collections (such as blog posts). It may also contain attached static files (<<page-files>>).
+
+NOTE: We sometimes refer to pages in collections as documents, documents are just a special kind of pages.
+
 == Layouts and Partials
 
 For your site, you will have one or more kind of pages, this is what we call "layouts", located by default in `templates/layouts/`. For example:
@@ -36,7 +42,7 @@ For your site, you will have one or more kind of pages, this is what we call "la
 * `post`: the layout for blog posts
 * `recipe`: the layout for recipes or whatever
 
-A layout may be specified in pages and documents through the `layout` FrontMatter key (e.g. `layout: page`). By default, `posts` will use the `post` layout and normal pages the `page` layout (this can be configured through link:{site.url('docs/advanced/')}#quarkus-roq-frontmatter_site-page-layout[site configuration]).
+A layout may be specified in pages through the `layout` FrontMatter key (e.g. `layout: page`). By default, `posts` will use the `post` layout and normal pages the `page` layout (this can be configured through link:{site.url('docs/advanced/')}#quarkus-roq-frontmatter_site-page-layout[site configuration]).
 
 TIP: Roq layouts are using the Qute `include` section under the hood to achieve template inheritance. For more details, see the Qute documentation on includes: https://quarkus.io/guides/qute-reference#include_helper[Qute includes]. Unlike partials, layouts can also define Frontmatter data, which is inherited along with the template structure.
 
@@ -63,7 +69,6 @@ To install a theme, simply add the dependency to your pom.xml. Example with Roq'
 
 It will provide templates, scripts and styles for your site. To use a theme layout, refer to it with `:theme/` prefix (there is an example in the next part). For advanced usage, refer to the link:{site.url('docs/advanced')}#themes[*Theme section*].
 
-
 == Site index template
 
 Your site index template is required and should be located in `content/index.html`.
@@ -212,7 +217,7 @@ You can use Qute to access site and pages data. For this use the `site` and `pag
 
 == Pages
 
-Any directory without the `_` prefix in the site directory will be scanned for pages content.
+Any template file without the `_` prefix in the site `content/` directory (and subdirectories) will be scanned as pages.
 
 Let's create your first page and spice things up a bit by using Markdown.
 
@@ -381,24 +386,27 @@ Since the new collection is also a normal page, we can use all variables describ
 
 [#site-static]
 == Site static files
+
+Site static files are served as-is without any additional processing.
+
 [source]
 ----
-static/
+public/
 ├── image.jpg
 └── presentation.pdf
 ----
 
-By default, all files in `static/` are scanned.
+By default, all files in `public/` are scanned as static files.
 
-Site static files url can be accessed through `site.staticFile('/static/presentation.pdf')`.
+Site static files url can be accessed through `site.file('presentation.pdf')`.
 
-TIP: `site.staticFile(path)` also checks that the file exists on disk and will adapt on site configuration (e.g. root path change)
+TIP: `site.file(path)` also checks that the file exists on disk and will adapt on site configuration (e.g. root path change)
 
 
-[#attachments]
-== Page and Documents attachments files
+[#page-files]
+== Page attached static files
 
-Pages and documents may have attachments files (image, pdf, slides, ...). For this, instead of creating a file page/document, create a directory with an index page:
+Pages may have attached static files (image, pdf, slides, ...). For this, instead of creating a file page, create a directory with an index page:
 
 [source]
 ----
@@ -408,106 +416,121 @@ content/my-page/
         └── index.md  // <2>
 ----
 
-<1> Every non page files in the directory are treated as attachments
-<2> Use an index.(html,md,...) for the page or document content
+<1> Every non page files in the directory will be attached to the page.
+<2> Use an index.(html,md,...) for the page content;
 
-In that case, attachments will be served under the same path as the page or document and can be accessed via a relative link:
+TIP: this also works in collections.
+
+In that case, those attached files will be served under the same path as the page and can be accessed via a relative link:
 [source,markdown]
 ----
 [slide](./slide.pdf)
 ----
 
-The resulting link for a page can be different from its directory name, attachments will be relative to the resulting link. This way it works both in IDEs preview and in the browser.
+The resulting link for a page can be different from its directory name, attached files will be relative to the resulting link. This way it works both in IDEs preview and in the browser.
 
 Let's imagine for a minute that the page link is `https://my-site.org/awesome-page/`, then the slide will be served on `https://my-site.org/awesome-page/slide.pdf`.
 
-You can use `{page.attachment("slide.pdf")}` to resolve the attachment url *and check that the file exists*. This is useful from another page or if you want the absolute url (i.e. `{page.attachment("slide.pdf").absolute}`):
+You can use `{page.file("slide.pdf")}` to resolve the file url *and check that the file exists*. This is useful from another page or if you want the absolute url (i.e. `{page.file("slide.pdf").absolute}`):
 
-TIP: If you want to iterate over attachments, they can be listed using `{page.attachments}`.
+TIP: If you want to iterate over page files, they can be listed using `{page.files}`.
 
 
 === Images
 
-==== Site image
-
-The site image should be added as a static site file (e.g. `my-site/static/assets/images/my-site.png`) and referenced in the site index FM `image` data.
-
-[source,yaml]
-.index.html
-----
----
-image: my-site.png
----
-----
+==== Site images
 
-It can be accessed in any template through `{site.image}`.
+The site images should be added in the public image directory (e.g. `my-site/public/images/image-1.png`).
 
-==== Page/Document cover image
+The default public path prefix for images is `images/` (this can be changed in the site configuration).
 
-Page/Document cover image can be added as an attachment (or as a static site file) and referenced in the page FM `image` data.
-[source,yaml]
-.some-page.md
-----
----
-image: my-page.png
----
-----
+Url can be accessed using the site variable as shown in this example: `<img src="{site.image('image-1.png')`}" />.
 
+TIP: The image method is a convenience and is equivalent to using `<img src="{site.file('images/image-1.png')`}" />.
 
-It can be accessed through `{page.image}`.
+==== Page images
 
-NOTE: `page.image` is smart and falls back to the static site files if the image is not an attachment.
+When using pages as directories (such as `posts/surf/index.html`), `{page.image(name)}` checks if the file is attached to the given page and return its url.
 
-==== Content images
+In other pages (such as `posts/basketball.md`), `{page.image(name)}` will act the same as `site.image(name)` and resolve from the site image directory.
 
-You also need images in your pages and articles content. Let's take this example structure:
+Let's take this example structure:
 
 [source]
 ----
 my-site/
 ├── content/
 │   └── posts/
-│       └── article-with-attachments/
-│           ├── surf.jpg                <1>
+|       └── basketball-article.md               <1>
+│       └── surf-article/
+            ├── cover.jpg
+│           ├── surf.jpg                <2>
 │           └── index.html
-└── static/
-    └── assets/
-        └── images/                     <2>
-            ├── basketball.png
-            └── football.jpg
+└── public/
+    └── images/                         <3>
+        ├── basketball-cover.png
+        ├── basketball.png
+        └── football.jpg
 ----
 
-<1> Accessible via `page.image('surf.jpg')` or via a simple relative link from the page.
-<2> Accessible via `site.image('basketball.png')` or `page.image('basketball.png')` (it falls back to site).
+<1> With non directory pages, `page.image()` is equivalent to `site.image()`.
+<2> Accessible via `page.image('surf.jpg')` or via a simple relative link only from the index page.
+<3> Accessible via `site.image('basketball.png')` on all pages.
 
 Here is how to access those images from the article:
 
 [source,html]
-.article-with-attachments/index.html
+.surf-article/index.html
 ----
-
+---
+image: cover.jpg
+---
 <h2>👍</h2>
 <img src="surf.jpg" /> <1>
-<img src="{page.image('surf.jpg')}" /> <2>
-<img src="{site.image('basketball.jpg')}" /> <3>
-<img src="{page.image('basketball.png')}" /> <4>
-<img src="{page.image('basketball.png').absolute}" /> <5>
-
+<img src="{page.image()}" /> <2>
+<img src="{page.image('surf.jpg')}" /> <3>
+<img src="{site.image('basketball.jpg')}" /> <4>
+<img src="{site.image('basketball.png').absolute}" /> <5>
 
 <h2>👎</h2>
 <img src="{site.image('surf.jpg')}" /> <6>
 <img src="{page.image('soccer.jpg')}" /> <6>
+<img src="{page.image('basketball.jpg')}" /> <6>
 ----
 
-<1> Relative links are working when using <<attachments>>.
-<2> The `image()` method also checks that the file exists on disk.
-<3> `site.image(path)` looks into `/static/assets/images/` by default (with disk checking).
-<4> Same as _3._ because `page.image(path)` fall backs to `site.image(path)`.
-<5> render the absolute url (e.g. `https://my-site.org/static/assets/images/basketball.png`)
+<1> Relative links are working when using <<page-files>>.
+<2> Will show the page cover image (same as `{page.image('cover.png')}`)
+<3> `surf.jpg` is also attached to this page
+<4> `site.image(path)` looks into `/public/images/` by default (with disk checking).
+<5> render the absolute url (e.g. `https://my-site.org/images/basketball.png`)
 <6> this would throw an error!
 
-== Styles and Javascript
+=== Page & Site cover image
 
+Page cover image is referenced in the page FM `image` data.
+[source,yaml]
+.some-page.md
+----
+---
+image: my-page.png
+---
+
+{page.image}
+----
+
+The url can be accessed from this template (and its parent layouts) through `{page.image}`.
+
+[source,yaml]
+.index.html
+----
+---
+image: my-site.png
+---
+----
+
+It can be accessed in any template through `{site.image}`.
+
+== Styles and Javascript
 
 Here are two options to consume scripts and styles:
 
@@ -560,19 +583,4 @@ The standard Asciidoc include is not supported, but you can use Qute includes in
 . Place your file in a folder under the `template` directory (for example `partials`)
 . Use Qute include directive `{# partials/your_included_file.adoc /}` to include it
 
-=== Images
-
-If you placed your images under the `static/assets/images` folder, you may reference them with the image macro :
-
-[source,asciidoc]
-----
- image::{site.image('your_image.png')}[Image description]
-----
-
-If you are using attachments, you can reference them directly:
-[source,asciidoc]
-----
- image::./foo.png[Image description]
-----
-
 |}

blog/content/posts/2024-10-31-roq-with-blogs/index.md

@@ -58,7 +58,7 @@ At this point, I thought back on what my wife had said... maybe it was time to r
 
 🗓️ **May 7, 2024:**
 
-![Discussion with Max](./generator-runtime-discussion.png)
+![Discussion with Max]({page.image('generator-runtime-discussion.png')})
 
 My idea was to generate static pages at runtime… because then all of Quarkus could become static without any changes 😍.
 

blog/content/posts/2024-12-26-attachments/index.md → blog/content/posts/2024-12-26-page-files/index.md

@@ -1,14 +1,14 @@
 ---
 layout: :theme/post
-title: Static attachments for posts and pages
+title: Static attached files for posts and pages
 image: dina-badamshina-j7vbBmTHmjY-unsplash.jpg
 description: |
-    This Christmas, I’m Roq-ing a cool new feature (inspired by Hugo 😅): posts and pages can have static attachments that are served relative to the page. 🎁🤩
+  This Christmas, I’m Roq-ing a cool new feature (inspired by Hugo 😅): it is possible to attach static files to posts and pages. They will be served relative to the page. 🎁🤩
 author: ia3andy
 tags: frontmatter, cool-stuff
 ---
 
-This Christmas, I’m Roq-ing a cool new feature (inspired by Hugo 😅): posts and pages can have static attachments that are served relative to the page. 🎁🤩
+This Christmas, I’m Roq-ing a cool new feature (inspired by Hugo 😅): it is possible to attach static files to posts and pages. They will be served relative to the page. 🎁🤩
 
 I love it because it allows to put all the content related to one page or post in the same place. Bonus, images are displayed on previews since they are relative to the template.
 

blog/public/googlefb811abf43ab0eb2.html

@@ -0,0 +1 @@
+google-site-verification: googlefb811abf43ab0eb2.html

blog/templates/partials/doc/directory-structure.adoc

@@ -18,8 +18,8 @@ my-site/
 │   ├── roq-bottom.md                    // <4>
 │   └── index.html                       // <5>
 │
-├── static/                              // <6>
-│   └── assets/
+├── public/                              // <6>
+│   └── style.css
 │
 └── templates/                           // <7>
     ├── partials/                        // <8>
@@ -48,8 +48,8 @@ You may provide additional pages files like `roq-bottom.md` outside a collection
 <5> **Index File**
 The `index.html` file is required and serves as the homepage. It provides site-wide data using FrontMatter.
 
-<6> **Static Assets**
-The `static/` directory holds static assets, such as images, CSS, or JavaScript files. These files are configurable and will not be processed.
+<6> **Static Files**
+The `public/` directory holds static files, such as images, CSS, or JavaScript files. These files will not be processed.
 
 <7> **Templates**
 The `templates/` directory is optional as templates can be provided by a theme. It contains Qute templates for partials and layouts.