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/