[[!template id=plugin name=poetry author="[[Louis|spalax]]"]]

# Poetry

The poetry plugin provides the [[ikiwiki/directive/poetry]] directive, used to
render poetry (or songs).

## Why?

### Typography

In regular text, there are two different meaning of a new line: a break between
two paragraphs, and the word wrap.

When rendering poetry, we need a third one: the carriage return between two
verse lines. This one should be different from the word wrap carriage return,
otherwise one will not be able to tell apart these two (generally, wrapped text
is indented, whereas verse lines are not).

### Markdown

One could use carriage return (two white spaces at the end of a line) between
verse lines, and paragraph break between stanzas, but:

* adding white spaces at the end of lines is painful;
* there is no easy way to render chorus (in a different way from verses).

## Usage

The directive takes only one argument `content`, containing the poetry to
render. Carriage returns are respected.

Chorus are lines with `> ` as a starting character.

Lines starting with `) ` are consored/outdated/crossed out verses.

[[!toggle id=example text="View example"]]
[[!toggleable id=example text='''
    \[[!poetry content="""
    This is a verse
    Made of several lines

    > And here is the chorus
    > La la la!
    > A beautiful chorus

    Another verse
    A bit longer
    Than the previous one

    ) This one is deleted
    ) Because I did not like it
    """]]
''']]


## CSS

This plugin is useless without some corresponding CSS. An example is given
below.

[[!toggle id=css text="CSS"]]
[[!toggleable id=css text="""
    .poetry {
      padding-left: 1em;
      border-left: 0.1em solid lightgray;
      border-radius: 0.5em;
    }
    
    .poetry .stanza {
      padding-left: 1em;
    }
    
    .poetry .paren {
      font-style: italic;
      font-size: smaller;
      text-decoration: line-through;
    }
    
    .poetry .paren:hover {
      text-decoration: initial;
    }
    
    .poetry .chorus {
      margin-left: 0.1em;
      padding-left: 2em;
      border-left: 0.3em solid slategray;
    }
    
    .poetry .line {
      display: block;
      text-indent: -1em;
    }
"""]]

## Example

This plugin is used to render songs on [this choir's
website](http://barricades.int.eu.org/repertoire/bread_and_roses/).

## Code

Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/Poetry]].