Merge pull request quarkiverse#119 from ia3andy/doc

Start doc

README.md

@@ -9,9 +9,13 @@
 
 [![Version](https://img.shields.io/maven-central/v/io.quarkiverse.roq/quarkus-roq?logo=apache-maven&style=flat-square)](https://central.sonatype.com/artifact/io.quarkiverse.roq/quarkus-roq-parent)
 
-All the tools to generate static websites out of your Quarkus web application:
-- Roq Data: Use json/yaml files content from your templates and articles with type safety.
-- Roq FrontMatter: Directly serve your Markdown/Asciidoc/Html pages using FrontMatter header (url, layout, seo, data) and make the global pages header data available in other templates.
-- Roq Generator: Command to run any Quarkus web application and extract it in a directory as purely static files (html and assets).
+The Roq Static Site Generator extension allows to easily create a static website or blog using Quarkus super-powers.
+
+Get started with the [documentation](https://docs.quarkiverse.io/quarkus-roq/dev/index.html).
+
+Roq already includes a set of extensions which can also be used standalone:
+- [Roq Data](https://docs.quarkiverse.io/quarkus-roq/dev/quarkus-roq-data.html): Use json/yaml files content from your templates and articles with type safety.
+- [Roq FrontMatter](https://docs.quarkiverse.io/quarkus-roq/dev/quarkus-roq-frontmatter.html):  Create a website from your Markdown/Asciidoc/Html pages using FrontMatter headers (url, layout, seo, data).
+- [Roq Generator](https://docs.quarkiverse.io/quarkus-roq/dev/quarkus-roq-generator.html): Command to run any Quarkus web application and extract it in a directory as purely static files (html and assets).
 
 

docs/modules/ROOT/nav.adoc

@@ -1,2 +1,3 @@
 * xref:index.adoc[Getting started]
-* xref:quarkus-roq-data.adoc[Quarkus Roq Data]
+* xref:quarkus-roq-data.adoc[Quarkus Roq Data]
+* xref:quarkus-roq-generator.adoc[Quarkus Roq Generator]

docs/modules/ROOT/pages/includes/getting-started-frontmatter.adoc

@@ -0,0 +1,96 @@
+[[getting-started]]
+== Getting started
+
+By default, your site should be located in the `site` directory of your project root, or in the resources (i.e. `src/main/resources/site`).
+
+The site directory structure is:
+
+
+image::roq-dirs.png[Roq directory structure]
+
+// https://excalidraw.com/#json=r097DRsiEfB1ivnrhz5ky,X5N6SEHHofuhh7vII-81OQ
+
+
+NOTE: The https://pages.quarkiverse.io/quarkus-roq/[Roq blog] is a good example of site made with Roq (https://github.com/quarkiverse/quarkus-roq/tree/main/blog[sources]).
+
+
+=== Site index
+
+Your site index is required and should be located in `site/index.html`, it should include a FrontMatter header containing yaml data:
+[source,html]
+.index.html
+----
+---
+title: Hello, world! I'm Roq <1>
+description: I provide you with all the tools to generate static websites out of your Quarkus web application.
+layout: main //<2>
+---
+
+<h1>Hello World</h1>
+
+----
+
+<1> The index.html also describe your `site` information through a FrontMatter header
+<2> The layout to use (in this case `main` which refers to `site/_layout/main.html`)
+
+=== Variables
+
+You can use Qute to access site and pages data. For this use the `site` and `page` variables:
+
+* The `site` variable allow to access site global data from any page or document.
+* The `page` variable allow to access page data for the current page. It is available in layouts and includes and will contain the data for the page it is used from.
+
+=== Pages
+
+Any directory without the `_` prefix in the site directory will be scanned for pages content.
+
+For example:
+[source,html]
+.pages/events.html
+----
+---
+layout: main
+link: /events
+---
+
+{#for event in cdi:events.list}
+<article class="event">
+  <div class="event-content">
+    <h2 class="event-title">{event.title}</h2>
+    <p>{event.description}</p>
+    <span class="post-date">{event.parsedDate.format('yyyy, MMM dd')}&nbsp;&nbsp;&nbsp;—&nbsp;</span>
+  </div>
+</article>
+{/for}
+
+----
+
+=== Collections
+
+TODO
+
+=== Static files, Styles and Javascript
+
+NOTE: The Quarkus Web Bundler is included by default with the Roq extension.
+
+Put your static files in `src/main/resources/web/static`.
+
+You can add css and scripts in your static directory or bundle them.
+To use bundling scripts (js, ts) and styles (css, scss) should be located in `src/main/web/app/`. To include the generated bundle in your template, specify the bundle tag in the `html>head` tag:
+
+[source,html]
+._layouts/head.html
+----
+<head>
+  ...
+  {#bundle /}
+</head>
+----
+
+It will be rendered with the relevant `<script>` and `<style>` tags to include your bundle.
+
+You may also consume and bundle npm dependencies among other cool things.
+For more info, read the https://docs.quarkiverse.io/quarkus-web-bundler/dev/[Quarkus Web Bundler documentation].
+
+
+

docs/modules/ROOT/pages/index.adoc

@@ -2,9 +2,13 @@
 
 include::./includes/attributes.adoc[]
 
-Quarkus Roq includes robust tooling for generating a static website from your Quarkus application.
+The Roq Static Site Generator extension allows to easily create a static website or blog using Quarkus super-powers.
 
-* xref:quarkus-roq-data.adoc[*Roq Data*] - Use json/yaml files content from your templates and articles with type safety.
+Roq already includes a set of extensions which can also be used standalone:
+
+* xref:quarkus-roq-data.adoc[*Roq Data*]: Use json/yaml files content from your templates and articles with type safety.
+* xref:quarkus-roq-frontmatter.adoc[*Roq FrontMatter*]:  Create a website from your Markdown/Asciidoc/Html pages using FrontMatter headers (url, layout, seo, data).
+* xref:quarkus-roq-generator.adoc[*Roq Generator*]: Command to run any Quarkus web application and extract it in a directory as purely static files (html and assets).
 
 == Installation
 
@@ -21,6 +25,31 @@ For instance, with Maven, add the following dependency to your POM file:
 </dependency>
 ----
 
+include::includes/getting-started-frontmatter.adoc[]
+
+[[custom-site-dir]]
+== Configure a custom Roq site directory
+
+It can be located in a resource directory such as `src/main/resources/my-site`:
+[source,properties]
+.application.properties
+----
+quarkus.roq.resource-dir=my-site
+----
+
+or in your project directory such as `my-site`:
+[source,properties]
+.application.properties
+----
+quarkus.roq.dir=my-site
+----
+
+
+
+
+
+
+
 [[extension-configuration-reference]]
 == Extension Configuration Reference