# Lesana Web

Read-only web interface to [Lesana](https://pypi.org/project/lesana/) collections

## Requires

- Lesana
- Flask
- Xapian python bindings from your package manager

## Config

Configuration is read from environment variables:

- `LW_COLLECTION_PATH` : path to the collection folder. If not set, an error is raised.
- `LW_PAGE_SIZE` : how many entries show per page in list. Defaults to `20`.

## Templates

Lesana Web uses three templates, written using [Jinja2](https://jinja.palletsprojects.com/)
templating system:

- `index.html` : show list of entries, used as homepage and for search results
- `entry.html` : display entry details
- `about.html` : display the about page
- `atom.xml`   : atom feed

The applications comes with basic templates, but it's possible to customize 
this templates creating that two file in `templates/web` directory under 
collection's base folder.
Lesana Web will search that path first for templates, using included templates 
as fallback.

Template files in the `templates/` directory are released under the 
Creative Commons Zero ([CC0](https://creativecommons.org/publicdomain/zero/1.0/)) license.

> **TODO** : custom error templates

### Templates context

`index.html` template will get this vars in context:

- `q` : search query string. Defined only in `search` route
- `page` : current page number
- `entries` : list of `lesana.collection.Entry` objects
- `settings` : collection settings

`entry.html` template will get this vars in context:

- `entry` : `lesana.collection.Entry` object
- `settings` : collection settings

`about.html` template will get this vars in context:

- `readme`: an html snippet with the rendered README contents
- `settings` : collection settings

### Routes

Lesana Web defines four routes:

- `index` : the default route. Loads `index.html` template. 
Gets querystring parameter:
  - `p`, the page number to show, starting from 1

- `search` : loads `index.html` template. Gets  querystring parameters:
  - `p`, the page number to show, starting from 1
  - `q`, the search query

- `entry` : loads `entry.html`. It can return `404` if the requested entry does 
not exists, or `400` if the eid matches more than one entry.
Gets url parameter:
  - `eid`, the entry's eid to show

- `about`: loads `about.html`. Tries to load a README file from the root of the
  collection. In order it tries `README.rst` (interpreted as reStructuredText),
  `README.md` (interpreted as markdown) and `README.txt` or `README`, simply
  displayed as-is.


## Develop

```bash
  git clone https://git.sr.ht/~fabrixxm/lesanaweb
  cd lesanaweb
  make env      # build a virtualenv
  make install  # install lesanaweb in venv in editable mode

  # if you have a collection
  LW_COLLECTION_PATH=/path/to/collection make run   # run flask
  # else
  mkdir -p work/collection
  make init
  make run
```