## Using Roq (copy this section to your project's CLAUDE.md / AGENTS.md)

Roq is a static site generator built on Quarkus. It uses the Qute template engine with FrontMatter headers (YAML between `---` delimiters).

### Quick Start

1. Install via JBang: `curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force roq@quarkiverse/quarkus-roq`
2. Create a site: `roq create my-site` (adds the default theme with example content)
3. Start dev mode: `cd my-site && roq start` (live-reload on http://localhost:8080, most changes are picked up automatically, use `-p 9090` for a custom port, press `s` to force a soft restart if needed)
4. Build static site: `roq generate` (output in `target/roq/`), preview with `roq serve`
5. Add a plugin or theme: `roq add plugin:tagging`, `roq add theme:default`
6. Update to latest versions: `roq update`

For a minimal HTML structure without the default theme: `roq create my-site -x theme:base`. Use `--no-code` to skip example content, `--gradle` for Gradle.

Available commands: `roq create`, `roq start`, `roq generate`, `roq serve`, `roq add`, `roq update`, `roq blog`. There is NO `roq dev` command, use `roq start` for dev mode.

### AI Agent Integration (Quarkus Agent MCP)

AI coding agents (Claude Code, VS Code Copilot, Cursor, etc.) can manage Roq dev servers using [Quarkus Agent MCP](https://github.com/quarkusio/quarkus-agent-mcp). It handles lifecycle (start, stop, soft restart via `s`), log capture, and proxies to Dev MCP tools in the running app.

**Install via JBang:**
```
jbang app install --fresh --force quarkus-agent-mcp@quarkusio
```

**Configure in Claude Code:**
```
claude mcp add quarkus-agent -- jbang quarkus-agent-mcp@quarkusio
```

**Configure in VS Code / Cursor (`.vscode/mcp.json`):**
```json
{
  "servers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}
```

Once configured, the agent uses `quarkus_start` to launch the Roq dev server, `quarkus_restart` for soft restart, `quarkus_logs` to read output, and `quarkus_searchTools` / `quarkus_callTool` to interact with the running app.

### Directory Structure

```
my-site/
├── content/           # Pages, collections (posts/, etc.), index.html (required)
├── templates/
│   ├── layouts/       # Page layouts (page.html, post.html)
│   └── partials/      # Reusable template fragments
├── data/              # Structured data files (YAML/JSON), accessible via {cdi:filename.property}
├── public/            # Static assets served as-is (images, PDFs)
├── web/               # JS/CSS sources (bundled by Quarkus Web Bundler)
└── config/
    └── application.properties  # Site config with site.* prefix
```

## Installing Roq Skill Files for AI Coding Assistants

Roq extensions ship detailed reference docs as skill files inside their deployment JARs at `META-INF/quarkus-skill.md`. Follow these steps to install them in your project.

### 1. Find your Roq extensions and version

```
mvn dependency:list -DincludeGroupIds=io.quarkiverse.roq -DoutputAbsoluteArtifactFilename=true
```

### 2. Extract the relevant skills

Extract from the matching JAR in your local Maven repository:
```
unzip -p ~/.m2/repository/io/quarkiverse/roq/ARTIFACT_ID/VERSION/ARTIFACT_ID-VERSION.jar META-INF/quarkus-skill.md > .claude/skills/SHORT_NAME.md
```

Install to the appropriate skills directory (`.claude/skills/` for Claude Code), or append to your CLAUDE.md/AGENTS.md.

Install a skill for each `*-deployment` JAR listed in the dependency output.

### 3. Keep skills in sync

After running `roq update`, re-extract the skill files to match the new version. Compare the Roq version in your dependencies with the version of the installed skill to detect staleness.

**Migrating to Roq:**
- [Migrating to Roq](https://iamroq.dev/docs/migrating/): phased workflow, syntax mappings, configuration reference, and LLM prompts for migrating a Jekyll/Hugo site to Roq

**Skill files (latest version for reference):**
- [quarkus-roq-frontmatter-deployment](https://raw.githubusercontent.com/quarkiverse/quarkus-roq/main/roq-frontmatter/deployment/src/main/resources/META-INF/quarkus-skill.md): base reference (FrontMatter pages, layouts, collections, pagination, template variables, Qute syntax, built-in tags, data files, template extensions, configuration, common pitfalls)
- [quarkus-roq-deployment](https://raw.githubusercontent.com/quarkiverse/quarkus-roq/main/roq/deployment/src/main/resources/META-INF/quarkus-skill.md): full Roq extras (directory structure, themes, RSS, LLMs.txt, static generation, testing, CLI commands)
- [quarkus-roq-data-deployment](https://raw.githubusercontent.com/quarkiverse/quarkus-roq/main/roq-data/deployment/src/main/resources/META-INF/quarkus-skill.md): data file mapping with @DataMapping and CDI

---
The following is the content of this blog site:

# Hello, world! I'm Roq — a funny little SSG (Static Site Generator) with a Java soul and Quarkus energy — Open Source and Free.

> An Open Source static site generator (SSG) that makes it fun and easy to build websites and blogs. It's built with Java and Quarkus under the hood.

## Marketplace

- [Tailwind CSS](/web/tailwind-css/): Use Tailwind CSS utility classes in your Roq site with automatic purging and optimized builds
- [Svelte](/web/svelte/): Build interactive components with Svelte and embed them in your Roq site
- [Sass](/web/sass/): Write stylesheets with Sass variables, nesting, and mixins for your Roq site
- [mvnpm](/web/mvnpm/): Use npm packages as Maven dependencies with zero Node.js installation required
- [Tagging](/plugin/tagging/): Auto-generate tag pages and filtered views for any content collection
- [Sitemap](/plugin/sitemap/): Generate an XML sitemap automatically so search engines index every page
- [Series](/plugin/series/): Organize posts into multi-part series with automatic navigation
- [QR Code](/plugin/qr-code/): Embed auto-generated QR codes for any URL or custom text
- [Markdown](/plugin/markdown/): Write content in Markdown with CommonMark support, included by default
- [Lunr Search](/plugin/lunr-search/): Add instant full-text search to your site using Lunr.
- [Diagram](/plugin/diagram/): Render diagrams from code blocks using Kroki (Mermaid, PlantUML, and more)
- [AsciiDoc](/plugin/asciidoc/): Write content in AsciiDoc with a fast, pure-Java processor
- [AsciiDoc JRuby](/plugin/asciidoc-jruby/): Full AsciiDoctor via JRuby with support for all extensions and macros
- [Aliases](/plugin/aliases/): Set up URL redirects and short links to keep old URLs working
- [Resume Theme](/theme/resume-theme/): Build a polished personal resume or CV from simple YAML data files
- [Default Theme](/theme/default-theme/): The default Roq theme for blogs and sites, built with Tailwind CSS, featuring dark mode, responsive design, sidebar navigation, and social media links.
- [Base Theme](/theme/base-theme/): Minimal built-in theme with SEO, favicon, and Web Bundler. The ideal starting point to build a fully custom site from scratch.

## Posts

- [GFM Alert Blocks: Styled Callouts in Your Markdown](/posts/gfm-alert-blocks-styled-callouts-in-your-markdown/): Roq supports GitHub Flavored Markdown alert blocks with icons and themed colors. Learn how to use NOTE, TIP, IMPORTANT, WARNING, and CAUTION blocks, and how to add custom alert types.
- [Set It in Roq: The Editor that change the game!](/posts/set-it-in-roq-the-editor-that-change-the-game/): Roq introduces a TipTap-powered editor with Markdown support, transforming it from a static site generator into a lightweight, developer-friendly CMS. Create, edit, and preview content seamlessly within the Quarkus dev experience.
- [Roq 2.0 and Java Advent Calendar article](/posts/roq-2-0-and-java-advent-calendar-article/): An introduction to Roq 2.0, a Quarkus-inspired approach to static site generation in Java. Learn about its new foundation, plugin support, and live-reload feature through a practical tutorial.
- [Major site migrations to Roq](/posts/major-site-migrations-to-roq/): ✨ Two prominent websites have just migrated to Roq—any guesses who they might be?
- [More diagram than you could have dreamed of.](/posts/more-diagram-than-you-could-have-dreamed-of/): Leveraging Kroki.io to generate diagram from text
- [🔎 Your users deserve searching capabilities!](/posts/your-users-deserve-searching-capabilities/): No third party service needed 🚀
- [No pain updates with Roq](/posts/no-pain-updates-with-roq/): One of the most overlooked aspects when choosing a Static Site Generator (SSG) is how easy it is to keep your project up to date. Many developers have struggled with complex upgrade processes, dependency conflicts, and breaking changes when using traditional SSGs like Jekyll or Hugo.
- [Comparing Roq with Hugo, Jekyll, and JBake: A Feature Breakdown](/posts/comparing-roq-with-hugo-jekyll-and-jbake-a-feature-breakdown/)
- [Roq n Roll Your Tests 🎶](/posts/roq-n-roll-your-tests/): Testing the actual Roq generation has never been this cool! 🎸
- [Easily Generate a `sitemap.xml` for Your Site with Roq](/posts/easily-generate-a-sitemap-xml-for-your-site-with-roq/): Learn how to quickly set up and customize a sitemap.xml for your site using the Roq plugin.
- [Static attached files for posts and pages](/posts/static-attached-files-for-posts-and-pages/): 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. 🎁🤩

- [Already some happy users 🧑‍💻](/posts/already-some-happy-users/): This is a good start, we already have a few happy users!
- [Do you want to publish a blog post series ?](/posts/do-you-want-to-publish-a-blog-post-series/): Make your blog posts part of a series.
- [Need a QR Code?](/posts/need-a-qr-code/): Add a QR Code to your Roq website.
- [Roq with Blogs](/posts/roq-with-blogs/): 🚀 Roq 1.0 is ON! It is time to give it a shot and give us feedback 🚀
- [Write your blog posts in AsciiDoc](/posts/write-your-blog-posts-in-asciidoc/): Automatically generate html from AsciiDoc content
- [RSS Feed of your blog posts](/posts/rss-feed-of-your-blog-posts/): Automatically generate an RSS feed of your blog links.
- [The second Roq plugin is for redirecting your page to a better place!](/posts/the-second-roq-plugin-is-for-redirecting-your-page-to-a-better-place/): We introduced a way to declare aliases in FrontMatter. It is now easy create redirections to your blog posts!
- [The first Roq plugin is for tagging (with pagination)](/posts/the-first-roq-plugin-is-for-tagging-with-pagination/): We introduced the first Roq plugin, it is for collection tagging & with pagination support!
- [Out of the box awesome SEO](/posts/out-of-the-box-awesome-seo/): Learn how to implement SEO in Roq in a blink of an eye.
- [Mastering Pagination in Roq](/posts/mastering-pagination-in-roq/): Learn how to implement pagination in Roq to enhance your content navigation. This article walks through the process of adding pagination, configuring page size, and customizing links.
- [How to add syntax highlighting to your Roq site](/posts/how-to-add-syntax-highlighting-to-your-roq-site/): Learn how to integrate syntax highlighting into your Roq site using Highlight.js and the Quarkus web-bundler extension. This guide walks you through the simple steps to add it via the pom.xml, JavaScript, and SCSS files.
- [Easily manage Drafts and Future articles in Roq](/posts/easily-manage-drafts-and-future-articles-in-roq/): Roq SSG introduces a new feature that allows you to hide or show draft and future articles using simple Quarkus configurations. This update gives developers greater control over which content is visible, improving content management and workflow.
- [Effortless URL Handling in Roq with Qute super-power](/posts/effortless-url-handling-in-roq-with-qute-super-power/): Effortlessly manage both relative and absolute URLs with our enhanced Qute-powered feature. Utilizing the RoqUrl class, you can easily join and resolve paths, ensuring clean and predictable URLs. This update simplifies URL handling, making your code more efficient and your content easier to navigate and share.
- [Welcome to Roq!](/posts/welcome-to-roq/): This is the first article ever made with Quarkus Roq

## Pages

- [Markup Examples](/markups/): Pages demonstrating different markup languages supported by Roq
- [Oops! Roq is saying 404](/404.html)
- [About Roq](/about/): Roq is a powerful static site generator that combines the best features of tools like Jekyll and Hugo, but within the Java ecosystem. It offers a modern approach with Quarkus at its core, requiring zero configuration to get started —ideal for developers who want to jump right in, while still being flexible enough for advanced users to hook into Java for deeper customization.

- [Roq Advanced Stuff](/docs/advanced/)
- [Roq the basics](/docs/basics/)
- [Getting started](/docs/getting-started/): Roq allows to easily create a static website or blog using Quarkus super-powers.
- [Migrating to Roq](/docs/migrating/)
- [Publishing a Roq Site](/docs/publishing/)
- [Roq Release Notes](/docs/releases/): Want to follow Roq’s progress and update your project safely? You’re in the right place.
- [Roq Events](/events/): The Roq community is warmly encouraged to share, discuss, and contribute to the project. Whether you're building something cool, writing a blog post, or giving a talk, we'd love to hear about it!
- [Plugins & Themes](/marketplace/): Browse plugins and themes for your Roq site
- [AsciiDoc Markup Example](/markups/asciidoc/): All AsciiDoc content types to verify theme styling
- [Markdown Markup Test](/markups/markdown/): All Markdown content types to verify theme styling
- [🎸 The Roqers Hall Of Fame](/roqers/): Already a Roqer? be a part of the hall of fame, please share the link with a small description in the comments and give us your experience.
- [Blog](/blog/): All the latest posts from the Roq team.
- [Blog](/posts/page2/): All the latest posts from the Roq team.
- [Blog](/posts/page3/): All the latest posts from the Roq team.
- [#features](/posts/tag/features/)
- [#styling](/posts/tag/styling/)
- [#plugin](/posts/tag/plugin/)
- [#plugin](/posts/tag/plugin/page2/)
- [#blogging](/posts/tag/blogging/)
- [#happy-users](/posts/tag/happy-users/)
- [#markdown](/posts/tag/markdown/)
- [#frontmatter](/posts/tag/frontmatter/)
- [#cool-stuff](/posts/tag/cool-stuff/)
- [#cool-stuff](/posts/tag/cool-stuff/page2/)
- [#cool-stuff](/posts/tag/cool-stuff/page3/)
- [#seo](/posts/tag/seo/)
- [#guide](/posts/tag/guide/)
- [#guide](/posts/tag/guide/page2/)
- [#guide](/posts/tag/guide/page3/)
- [#guide](/posts/tag/guide/page4/)
- [#gfm](/posts/tag/gfm/)