LunaGen Guide
=============
..contents::
LunaGen is a static website generator for episodic media created
to support the "Lunatics_!" open animated series project. The site
structure it is designed for has:
* An index page with lists of episodes in (possibly) multiple series.
* A page for each episode, with structure determined by the theme and data.
* Additional special list pages for Characters, Settings, Sponsors, and Affiliates.
* Any additional hand-created pages desired.
The data driving the site is authored directly in YAML_ format.
The templates used for site generation (which can be overridden in themes) are
written in Jinja2_.
In addition, both theme and data also contain site "skeletons", which provide additional
files needed: most notably the CSS style sheets in the theme and the necessary images
and static HTML pages you want to use in your site source data directory.
It is very likely you will want to create a custom theme for your site. Please see
the `Theme Author Guide`_ for how to do that. This `Site Author Guide`_ is targeted
at users who simply want to use the package to generate a website using an existing
theme. Should you want to make changes to the code itself, you'll want to read the
`Developer Guide`.
Alternatives
------------
Is LunaGen for you? LunaGen sacrifices generality in order to provide an extremely
simple authoring environment for publishing episodic multimedia content.
I do not recommend it for publishing textual content simply because
it lacks any sophisticated markup language. It is also not a general purpose
content management system, as it is very specific to episodic data, and only
provides a few hard-coded special pages. Making all these assumptions allows
us to keep the data we have to write to update the site very short and simple,
but it also means we can't stretch the software much to do other tasks.
If you want a more text-intensive site, like a static blog listing, you should
probably check out more robust solutions like Pelican_ or Jekyll_, which are
optimized for that kind of use. Perhaps in the future we'll create some kind
of integration to allow LunaGen to be used along with other tools more easily.
We rejected those and designed our own generator because of the amount of
boilerplate we'd need to add to generate simple listings of the type we wanted
using a blog-oriented generator. Using YAML_ allows us to keep our information
field-oriented, with only a little descriptive text needed, but without the
overhead of a database-driven site.
Site Author Guide
-----------------
LunaGen site data consists primarily of a set of YAML_ files and a site skeleton
containing additional content files your site needs -- mostly images, but also
possibly static HTML pages that will simply be copied without modification to your
site.
In general, you should not include CSS files in your site skeleton. These should be
incorporated into a custom **theme** skeleton instead. However, any files you put in
your site skeleton will be copied to your site after the theme files, potentially
replacing them if there is a name collision. So you *can* override CSS this way, though
it's not recommended.
The YAML files for your site follow a very specific structure and some files are
mandatory. At the top level you will find:
``site.yaml``
This defines global variables needed throughout your site:
``sitename``
This is the name used for your entire site. Probably the name of the show.
It must be a simple identifier, and may be used to construct some filenames
or variables.
``sitetitle``
This is the fully-styled name for your site, which may contain punctuation
and spaces.
``imgdir``
This is the location where your images live in your site skeleton.
Whenever a template looks for an image, this will be prepended to the
URL. The exact location of the image below that will be determined by
the template and is theme-specific. So you can structure your images
anyway you like in a custom theme, but will need to learn the requirements
of a theme if you are using someone else's.
``stylesheets``
A list of stylesheets to be referenced by *every* page on your site.
This will be included first, followed by stylesheets requested in
other documents. TODO: this should really be in the theme.
``characters.yaml``
This is the data for a special page listing your series' characters.
TODO: should be optional.
``affiliates.yaml``
List of affiliate advertisements with ``name``, ``img``, and ``url`` fields
to generate the "affiliates banner". TODO: again, should be optional.
``products.yaml``
List of product ad images to advertise your merchandise storefront.
TODO: again, optional.
``software.yaml``
A list of software banners to call out your favorite production software,
advertising those projects so they get some support.
TODO: again, optional.
There is also an ``episodes`` directory, which contains the series and episode
data. Within it you will find:
``series.yaml``
This defines the available series of episodes, and defines several terms to
be used inside the episode files. It consists of a list of series, each of
which must define:
``name``
Name or title of the series, to be shown to the user.
``order``
This is an integer which is used to control the display order. It is
not directly shown, and does not have to be sequential (for example
we numbered our audiodrama series 100 to make sure it always appears
after the animated series). It also need not be in the same order
as the series are listed in your file.
``directory``
This is a brief identifier for the series, used as the directory name
for storing the episode files, and also as a key field.
``modes``
Defines the possible production modes for each episode. Should at least
contain a ``release`` mode for a finally-released episode, but it may
also have earlier workflow modes, such as ``fundraising`` or ``production``,
to show the state of the episode (and therefore what information will
be available for it). For each mode, there is a ``template`` value telling
what template the theme should use to format the episode.
TODO: this is theme-dependent, but I'm not sure how to separate it.
``credits``
This is a collection of definitions for credits blocks to be used in
your episode credits. It defines named blocks, for which the following
should be defined:
``order``
Controls the order of presentation of the fields.
``heading``
What heading to show in the credits listing on the output
page. For example, in our file, this tells us that ``animation_credits``
should be listed as "3D Models and Animation". Optional. If
no heading is provided, no heading will be shown.
``labels``
Controls how the credits will be listed. If this is a list,
it lists identifier and title pairs to be used in the listing.
The order of this list controls the order of the credits (they
may be identified in any order in the episode file).
The value may instead be one of the following strings:
``ordered``
Credits will simply be listed in the order presented in the
episode file, with labels expressed there.
``alpha``
Credits will be listed in alphabetized order.
The exact behavior of the labels value is controlled by the
credits template used, so may be theme-dependent.
``template``
Determines which template will be used to display this credits
block, determining layout behavior. The following are defined:
``centered_credits``
Credits will be listed in simple order, down the middle.
No columns are used, even on a wide screen. Typically used
for main credits.
``basic_credits``
Used for a variety of credit listings. Will try to save some
space by using columns to fill the screen better.
``cast_credits``
Designed to display paired credits, as in cast listings, with
character/actor pairings.
``music_credits``
This displays credits in blocks with named fields for each
title. This changes the interpretation of labels to refer
to the labels used in the individual blocks.
``sponsortypes``
Definitions for your sponsors. Determines what categories you have
and how they will be listed. Note that defining the sponsors here
means you can have a different system for different series.
For each type listed, the following fields may be defined:
``limit``
An integer expressing a limit on how many of this kind of sponsor
is accepted and will be listed (more than this will not be displayed).
``page``
An integer expressing the number of sponsors to be included in a single
block in the listing (this is used to space the sponsors out through
the credits).
``excludes``
The name of another sponsortype that can't be used on the same episode
as this one. Should suppress display of the other, but this isn't
implemented.
``template``
Template name to use for displaying a list of these sponsors.
``desc``
Description of the sponsor type. Will be used to create an informational
page for viewers and potential sponsors.
In the ``episodes`` directory, you will also find subdirectories for each series
using the directory names defined above. Inside each are files for each episode,
with episode-specific data:
*episode*``.yaml``
The following fields are required:
``series``
Backlink to the series identifier.
``episode``
The episode number -- an integer.
TODO: maybe change this to 'number' so we have episode.number instead
of episode.episode?
``mode``
Status of the episode, such as whether it's released, in-development,
in-production, etc. The value should be one of the values defined in
``modes`` in the ``series.yaml`` file. The value may also control
how other information in this file is handled and presented (and which
values are needed). In fact, this may be one way to handle information
that isn't available yet, such as animation credits for an episode that's
just in development.
``title``
The title presented for the episode. Used in several places.
``poster``
Image filename to be used to represent the episode. Ours are square
600x600 pixel images, but the format you use is theme-dependent.
``status``
A brief status message to be included under the title. Good for release
dates or fundraising messages.
``description``
One-paragraph description of the episode. The "blurb".
``credits``
The fields defined in this category must be the ones defined in the
series ``credits`` field. Here you will list the actual credits to
use, in a format determined by the template you listed.
``sponsors``
The actual sponsors, in formats determined by the templates you defined
in the series' ``sponsortypes`` fields. Typically includes ``name``,
``url``, and ``img`` fields for graphic sponsor types, or just a list of
strings for simple named credits (like Patrons or Backers).
``ordered`` and ``cast_credits`` require pairs to be defined of
credit name and credit, like this::
- - Director
- Terry Hancock
- - Writer
- Rosalyn Hunter
For credit blocks with listed labeled credits, the credits should
be given as mappings, using the identifiers you defined, like this::
mech_models:
- Chris Kuhn
Other fields are dependent on the mode, but may include:
``videos``
Videos to display in the video carousel for the episode page, typically
including at least a preview. Ours also include the full episode, a
brief explainer about our business model, and a thank-you message from
the creators. Each video need to define ``id``, ``name``, ``url``,
and ``btn``, needed by the video template.
``product``
Defines a product to pitch on the page. We use this to direct viewers to
the DVD or download bundle releases of our episode in our Gumroad store.
Values are defined by how they are used in the template. Ours provides:
``img``, ``url``, ``title``, and two message fields, ``msg1`` and ``msg2``
which are displayed under certain circumstances.
``funding``
A block defining fields for a crowdfunding campaign, which may include
multiple campaigns on separate platforms. This provides a combined display
of funds raised, and may include pre-sales, matching funds, sponsorships,
and fixed or flexible goal fundraising from crowdfunding platforms.
TODO:
Currently this is a display-only feature and requires manual updating, but
we might provide some kind of plugin system for updating this when the site
is regenerated.
Theme Author Guide
------------------
To be added: should explain the files, templates, and stylesheets a theme needs to
define and how they will be used.
Developer Guide
---------------
To be added: should explain how LunaGen works and how to contribute to it.
.. _Lunatics: http://lunatics.tv
.. _YAML: https://yaml.org/
.. _Jinja2: https://palletsprojects.com/p/jinja/
.. _Pelican: https://blog.getpelican.com/
.. _Jekyll: https://jekyllrb.com/
b836bef771