~fabrixxm/lesanaweb

ref: 064fcca59231163b589a35a9c8f8a49904621100 lesanaweb/README.md -rw-r--r-- 2.8 KiB
064fcca5 — fabrixxm Update CHANGELOG 6 months ago

#Lesana Web

Read-only web interface to 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 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) 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

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