Lucid HTML DSL

Lucid is a Domain Specific Language (DSL) for writing HTML. The repository contains two distinct versions:

• lucid2: The latest version. If you are starting a new project, use this version. It is released on Hackage as lucid2.
• lucid1: The original version. It is released on Hackage as lucid.

Refer to the changelog in the lucid2 directory to understand the differences between the two versions.

When using Lucid, keep the following behaviors in mind:

• Attribute Escaping: Attributes are automatically escaped. You cannot write arbitrary JavaScript directly inside an attribute string. To execute JS, use an event handler attribute like onclick_ "foo()".
• Attribute Order: Attributes are rendered in the exact order they are written in your Haskell code.
• Text Escaping: Plain text is automatically escaped (e.g., < becomes <).

Lucid provides multiple ways to structure HTML content:

1. Nesting via Function Application: Use standard function application for simple hierarchies.
2. Monoidal Append: Use the <> operator to juxtapose elements.
3. Monadic Sequencing: Use do notation within a block to sequence multiple elements.

Note: Plain text is automatically escaped when using OverloadedStrings and ExtendedDefaultRules extensions.

-- Nesting
table_ (tr_ (td_ (p_ "Hello, World!")))

-- Juxtaposition (Monoidal)
p_ "hello" <> p_ "sup"

-- Sequencing (Monadic)
div_ (do p_ "hello"; p_ "sup")

Lucid can be used within a monad transformer stack. You can use lift to access parent monads (like Reader) while generating HTML. For example, you can use renderTextT to render HTML while pulling values from a Reader context.

runReader (renderTextT (html_ (body_ (do name <- lift ask
                                            p_ [class_ "name"] (toHtml name))))) 
          ("Chris" :: String)

Lucid can be used within a monad transformer stack. You can use renderTextT (or similar transformer versions) and lift to access parent monads (like Reader or State) while generating HTML.

runReader (renderTextT (html_ (body_ (do name <- lift ask
                                            p_ [class_ "name"] (toHtml name))))) 
         ("Chris" :: String)

Attributes are set by providing a list of attribute functions as the first argument to an element function. Attributes are rendered in the order they are written in the code.

Important: Attributes are escaped. To include JavaScript, use the attribute name (e.g., onclick_ "foo()") rather than trying to write raw script inside the attribute value.

-- Single attribute
p_ [class_ "brand"] "Lucid Inc"

-- Multiple attributes
td_ [class_ "top", colspan_ "2", style_ "color:red"] (p_ "Hello!")

To convert Lucid HTML definitions into actual output, use the following rendering functions:

• renderText: Renders the HTML to a Text value.
• renderBS: Renders the HTML to a ByteString.

For low-level control, you can run the monad directly via execHtml to use the Blaze.ByteString.Builder output modes.

-- Render to Text
renderText (p_ "Hello!")

-- Render to ByteString
renderBS (p_ [style_ "color:red"] "Hello!")

Lucid is a Domain Specific Language (DSL) for writing HTML in Haskell. It uses a postfix underscore (_) convention for HTML tags to distinguish them from data.

Key syntax patterns:

• Elements: Written as functions with a postfix underscore (e.g., p_, div_, table_).
• Nesting: Achieved via function application: `tag_ (child_