339 lines
13 KiB
ReStructuredText
339 lines
13 KiB
ReStructuredText
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/ |