La Famille 🐙

La Famille is a fast, feature-rich static site generator written in Go. It goes beyond simple markdown-to-HTML conversion by offering powerful developer tools, an interactive Terminal UI (TUI), and AI-ready RAG (Retrieval-Augmented Generation) exports.

This project is built and maintained primarily by Jules (AI assistant) alongside an eight-legged friend, Raoul(s) the Octopus. We take a "Jules-forward" approach to development. If you are opening a Pull Request, please make sure to tag Jules in the comments to keep the AI looped in.

Features ✨

• Lightning-Fast Static Generation: Converts Markdown content into clean, semantic HTML using the goldmark library.
• Interactive TUI: A sleek Bubbletea-powered terminal interface for managing builds, serving the site locally, and viewing project stats.
• Robust CLI: A powerful command-line interface built with cobra for tasks like initialization, building, serving, and RAG generation.
• RAG Export: Native tools to extract your site's content and metadata into clean archives optimized for LLM context windows (rag-system.md, rag-content.md, etc.).
• Flexible Templating: Support for multiple HTML layouts (e.g., standard, cyberpunk, minimal) easily overridden via YAML frontmatter.
• Built-in Local Server: Instantly preview your site with go run ./cmd/la-famille serve.
• Smart Graphing: Automatically generates graph.json, backlinks.json, and handles non-existent internal links by generating helpful stub pages.
• Interactive Knowledge Graph Explorer: Every build emits a self-contained /graph/index.html page that visualizes the site as a directed graph — search by title, page ID, tag, category, or author, filter by render/raw/stub/orphan, jump into "focus mode" for a selected page plus its neighbors, and deep-link selections via ?node=. No runtime server; just open the file. Disable with graph_explorer: false in config.yaml.

Quickstart 🚀

Prerequisites

• Go installed on your machine.

Build & Run

To run the static site generator using the CLI:

go run ./cmd/la-famille build

To launch the interactive TUI:

go run ./cmd/la-famille tui

To export RAG bundles:

go run ./cmd/la-famille rag

After go run ./cmd/la-famille build, open public/graph/index.html to explore the site's relationships interactively. The page is fully static — it loads graph.json, meta.json, and backlinks.json from the same output directory via relative fetches.

Note: rag-archive/ is generated by go run ./cmd/la-famille rag. It is intentionally ignored and must not be edited or committed. The Pages workflow may publish a copy under public/rag-archive/.

TUI Navigation & Controls

The TUI uses standard, frictionless keybindings for easy navigation:

• Navigation: Use up/down arrows or Unix-centric j/k primitives to move through the menus.
• Selection & Exit: Press Enter or Space to execute a command. Press q or Esc to safely drop back to the main menu screen buffer.
• Active Server Views: When you select "Serve Site" (or "Serve Site with Watch"), the TUI locks into an alternate screen buffer, displaying the dancing mascot animation (Raoul!). To gracefully tear down the network handle and exit back to the main menu, press q or Esc.

To serve the generated site locally (defaults to port 8080):

go run ./cmd/la-famille serve

Documentation 📚

The commands above will get you started, but La Famille has a lot more to offer. For deep-dive guides on how to use all the features, please explore our documentation:

• Setup & Getting Started
• CLI Reference
• Using the TUI
• Templating Guide
• RAG Export Guide
• How the Generator Works

---

Generated with ❤️ by Jules

CI/Testing

La Famille uses a comprehensive automated testing pipeline. All code merges are gated by passing go test and static analysis provided by golangci-lint to ensure security and code quality.

GitHub Action 🤖

You can easily build your La Famille site in CI using our GitHub Action:

steps:
  - uses: actions/checkout@v4
  - name: Build with La Famille
    uses: drawmeanelephant/la-famille@main

Configurable Inputs

All inputs are optional and fall back to sensible defaults:

steps:
  - uses: actions/checkout@v4
  - name: Build with La Famille
    uses: drawmeanelephant/la-famille@main
    with:
      content-dir: 'content'
      output-dir: 'public'
      template: 'templates/layout.html'
      site-url: 'https://example.github.io/my-site'