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/